1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
<!--$Id$-->
<articleinfo>
<title>Configuration Files Tips and Hints</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2001-2019</year>
<holder>Thomas M. Eastep</holder>
</copyright>
<legalnotice>
<para>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.2 or any later version published by the Free Software Foundation; with
no Invariant Sections, with no Front-Cover, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
</legalnotice>
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 5.0 and
later. If you are running a version of Shorewall earlier than Shorewall
5.0.0 then please see the documentation for that
release.</emphasis></para>
</caution>
<caution>
<para>If you copy or edit your configuration files on a system running
Microsoft Windows, you must run them through <ulink
url="http://www.megaloman.com/~hany/software/hd2u/">dos2unix</ulink>
before you use them with Shorewall.</para>
</caution>
<section>
<title id="Intro">Introduction</title>
<para>This article offers hints about how to accomplish common tasks with
Shorewall. The <ulink url="Introduction.html">Introduction to
Shorewall</ulink> is required reading for being able to use this article
effectively. For information about setting up your first Shorewall-based
firewall, see the <ulink url="GettingStarted.html">Quickstart
Guides</ulink>.in</para>
</section>
<section id="Files">
<title>Files</title>
<para><itemizedlist>
<listitem>
<para><filename>/etc/shorewall/shorewall.conf</filename> - used to
set global firewall parameters.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/params</filename> - use this file to
set shell variables that you will expand in other files. It is
always processed by /bin/sh or by the shell specified through
SHOREWALL_SHELL in
<filename>/etc/shorewall/shorewall.conf.</filename></para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/zones</filename> - partition the
firewall's view of the world into zones.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/policy</filename> - establishes
firewall high-level policy.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/initdone</filename> - An optional
Perl script that will be invoked by the Shorewall rules compiler
when the compiler has finished it's initialization.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/interfaces</filename> - describes the
interfaces on the firewall system.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/hosts</filename> - allows defining
zones in terms of individual hosts and subnetworks.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/masq</filename> - directs the
firewall where to use many-to-one (dynamic) Network Address
Translation (a.k.a. Masquerading) and Source Network Address
Translation (SNAT).</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/mangle</filename> - supersedes
<filename>/etc/shorewall/tcrules</filename> in Shorewall 4.6.0.
Contains rules for packet marking, TTL, TPROXY, etc.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/rules</filename> - defines rules that
are exceptions to the overall policies established in
/etc/shorewall/policy.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/nat</filename> - defines one-to-one
NAT rules.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/proxyarp</filename> - defines use of
Proxy ARP.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/routestopped</filename> - defines
hosts accessible when Shorewall is stopped. Superseded in Shorewall
4.6.8 by <filename>/etc/shorewall/stoppedrules</filename>. Not
supported in Shorewall 5.0.0 and later versions.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tcrules </filename>- The file has a
rather unfortunate name because it is used to define marking of
packets for later use by both traffic control/shaping and policy
routing. This file is superseded by
<filename>/etc/shorewall/mangle</filename> in Shorewall 4.6.0. Not
supported in Shorewall 5.0.0 and later releases.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tos</filename> - defines rules for
setting the TOS field in packet headers. Superseded in Shorewall
4.5.1 by the TOS target in
<filename>/etc/shorewall/tcrules</filename> (which file has since
been superseded by <filename>/etc/shorewall/mangle</filename>). Not
supported in Shorewall 5.0.0 and later versions.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tunnels</filename> - defines tunnels
(VPN) with end-points on the firewall system.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/blacklist</filename> - Deprecated in
favor of <filename>/etc/shorewall/blrules</filename>. Lists
blacklisted IP/subnet/MAC addresses. Not supported in Shorewall
5.0.0 and later releases.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/blrules</filename> — Added in
Shorewall 4.5.0. Define blacklisting and whitelisting.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/init</filename> - commands that you
wish to execute at the beginning of a <quote>shorewall
start</quote>, "shorewall reload" or <quote>shorewall
restart</quote>.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/start</filename> - commands that you
wish to execute near the completion of a <quote>shorewall
start</quote>, "shorewall reload" or <quote>shorewall
restart</quote></para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/started</filename> - commands that
you wish to execute after the completion of a <quote>shorewall
start</quote>, "shorewall reload" or <quote>shorewall
restart</quote></para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/stop </filename>- commands that you
wish to execute at the beginning of a <quote>shorewall
stop</quote>.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/stopped</filename> - commands that
you wish to execute at the completion of a <quote>shorewall
stop</quote>.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/ecn</filename> - disable Explicit
Congestion Notification (ECN - RFC 3168) to remote hosts or
networks.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/accounting</filename> - define IP
traffic accounting rules</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/actions</filename> and
<filename>/usr/share/shorewall/action.template</filename> allow
user-defined actions.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/providers</filename> - defines an
alternate routing table.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/rtrules</filename> - Defines routing
rules to be used in conjunction with the routing tables defined in
<filename>/etc/shorewall/providers</filename>.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tcdevices</filename>,
<filename>/etc/shorewall/tcclasses</filename>,
<filename>/etc/shorewall/tcfilters</filename> - Define complex
traffic shaping.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tcrules</filename> - Mark or classify
traffic for traffic shaping or multiple providers. Deprecated in
Shorewall 4.6.0 in favor of
<filename>/etc/shorewall/mangle</filename>. Not supported in
Shorewall 5.0.0 and later releases.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tcinterfaces</filename> and
<filename>/etc/shorewall-tcpri</filename> - Define simple traffic
shaping.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/secmarks</filename> - Added in
Shorewall 4.4.13. Attach an SELinux context to selected
packets.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/vardir</filename> - Determines the
directory where Shorewall maintains its state.</para>
</listitem>
<listitem>
<para><filename>/usr/share/shorewall/actions.std</filename> -
Actions defined by Shorewall.</para>
</listitem>
<listitem>
<para><filename>/usr/share/shorewall/action.*</filename> - Details
of actions defined by Shorewall.</para>
</listitem>
<listitem>
<para><filename>/usr/share/shorewall/macro.*</filename> - Details of
macros defined by Shorewall.</para>
</listitem>
<listitem>
<para><filename>/usr/share/shorewall/modules</filename> — Specifies
the kernel modules to be loaded during shorewall start/restart
(removed in Shorewall 5.2.3).</para>
</listitem>
<listitem>
<para><filename>/usr/share/helpers</filename> — Added in Shorewall
4.4.7. Specifies the kernel modules to be loaded during shorewall
start/restart when LOAD_HELPERS_ONLY=Yes in
<filename>shorewall.conf</filename>.</para>
</listitem>
<listitem>
<para><filename>/usr/share/arprules</filename> — Added in Shorewall
4.5.12. Allows specification of arptables rules.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/mangle</filename> -- Added in
Shorewall 4.6.0. Supersedes<filename>
/etc/shorewall/tcrules</filename>.</para>
</listitem>
</itemizedlist></para>
<para><emphasis role="bold">If you need to change a file in
/usr/share/shorewall/, copy it to <filename>/etc/shorewall</filename> and
modify the copy</emphasis></para>
</section>
<section id="Manpages">
<title>Man Pages</title>
<para>Man pages are provided in section 5 for each of the Shorewall
configuration files. The name of the page is formed by prefixing the file
name with "shorewall-".</para>
<para>Example — To view the manual page for
<filename>/etc/shorewall/interfaces</filename>:</para>
<programlisting>man shorewall-interfaces</programlisting>
<para>The /etc/shorewall/shorewall.conf file is an exception -- the man
page for that file is 'shorewall.conf':</para>
<programlisting>man shorewall.conf</programlisting>
</section>
<section id="Comments">
<title>Comments</title>
<para>You may place comments in configuration files by making the first
non-whitespace character a pound sign (<quote>#</quote>). You may also
place comments at the end of any line, again by delimiting the comment
from the rest of the line with a pound sign.</para>
<example id="comment">
<title>Comments in a Configuration File</title>
<programlisting># This is a comment
ACCEPT net $FW tcp www #This is an end-of-line comment</programlisting>
</example>
<important>
<para>If a comment ends with a backslash ("\"), the next line will also
be treated as a comment. See <link linkend="Continuation">Line
Continuation</link> below.</para>
</important>
</section>
<section id="Names">
<title>Names</title>
<para>When you define an object in Shorewall (<ulink
url="manpages/shorewall-zones.html">Zone</ulink>, <link
linkend="Logical">Logical Interface</link>, <ulink
url="ipsets.html">ipsets</ulink>, <ulink
url="Actions.html">Actions</ulink>, etc., you give it a name. Shorewall
names start with a letter and consist of letters, digits or underscores
("_"). Except for Zone names, Shorewall does not impose a limit on name
length.</para>
<para>When an ipset is referenced, the name must be preceded by a plus
sign ("+").</para>
<para>The last character of an interface may also be a plus sign to
indicate a wildcard name.</para>
<para>Physical interface names match names shown by 'ip link ls'; if the
name includes an at sign ("@"), do not include that character or any
character that follows. For example, "sit1@NONE" is referred to as simply
'sit1".</para>
</section>
<section>
<title>Zone and Chain Names</title>
<para>For a pair of zones, Shorewall creates two Netfilter chains; one for
connections in each direction. The names of these chains are formed by
separating the names of the two zones by either "2" or "-".</para>
<para>Example: Traffic from zone A to zone B would go through chain A2B
(think "A to B") or "A-B".</para>
<para>In Shorewall 4.6, the default separator is "-" but you can override
that by setting ZONE_SEPARATOR="2" in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
<note>
<para>Prior to Shorewall 4.6, the default separator was "2".</para>
</note>
<para>Zones themselves have names that begin with a letter and are
composed of letters, numerals, and "_". The maximum length of a name is
dependent on the setting of LOGFORMAT in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). See <ulink
url="manpages/shorewall-zones.html">shorewall-zones</ulink> (5) for
details.</para>
</section>
<section id="capabilities">
<title>Capabilities</title>
<para>Shorewall probes your system to determine the features that it
supports. The result of this probing is a set of
<firstterm>capabilities</firstterm>. This probing is normally done each
time that the compiler is run but can also be done by executing the
<command>shorewall show capabilities</command> command. Regardless of
whether the compiler or the command does the probing, this probing may
produce error messages in your system log. These log messages are to be
expected and do not represent a problem; they merely indicate that
capabilities that are being probed are not supported on your
system.</para>
<para>Probing may be suppressed by using a <firstterm>capabilities
file</firstterm>. A capabilities file may be generated using this
command:</para>
<programlisting><command>shorewall show -f capabilities > /etc/shorewall/capabilities</command></programlisting>
<important>
<para>If you use a capabilities file, be sure to regenerate it after you
have performed a Shorewall upgrade to ensure that all current
capabilities have been recorded in your file.</para>
</important>
</section>
<section id="BlankColumn">
<title>"Blank" Columns</title>
<para>If you don't want to supply a value in a column but want to supply a
value in a following column, simply enter '-' to make the column appear
empty.</para>
<para>Example:<programlisting>#INTERFACE BROADCAST OPTIONS
br0 - routeback</programlisting></para>
</section>
<section id="Continuation">
<title>Line Continuation</title>
<para>You may continue lines in the configuration files using the usual
backslash (<quote>\</quote>) followed immediately by a new line character
(Enter key).</para>
<programlisting>ACCEPT net $FW tcp \↵
smtp,www,pop3,imap #Services running on the firewall</programlisting>
<para>In certain cases, leading white space is ignored in continuation
lines:</para>
<orderedlist>
<listitem>
<para>The continued line ends with a colon (":")</para>
</listitem>
<listitem>
<para>The continued line ends with a comma (",")</para>
</listitem>
</orderedlist>
<important>
<para>What follows does NOT apply to <ulink
url="manpages/shorewall-params.html">shorewall-params(5)</ulink> and
<ulink url="shorewall.conf.html">shorewall.conf(5)</ulink>.</para>
</important>
<para>Example (<filename>/etc/shorewall/rules</filename>):</para>
<programlisting>#ACTION SOURCE DEST PROTO DPORT
ACCEPT net:\
206.124.146.177,\
206.124.146.178,\
206.124.146.180\
dmz tcp 873</programlisting>
<para>The leading white space on the first through third continuation
lines is ignored so the SOURCE column effectively contains
"net:206.124.146.177,206.124.147.178,206.124.146.180". Because the third
continuation line does not end with a comma or colon, the leading white
space in the last line is not ignored.</para>
<important>
<para>A trailing backslash is not ignored in a comment. So the continued
rule above can be commented out with a single '#' as follows:</para>
<programlisting>#ACTION SOURCE DEST PROTO DPORT
<emphasis role="bold">#</emphasis>ACCEPT net:\
206.124.146.177,\
206.124.146.178,\
206.124.146.180\
dmz tcp 873</programlisting>
</important>
</section>
<section id="Pairs">
<title>Alternate Specification of Column Values - Shorewall 4.4.24 and
Later</title>
<para>Some of the configuration files now have a large number of columns.
That makes it awkward to specify a value for one of the right-most columns
as you must have the correct number of intervening '-' columns.</para>
<para>This problem is addressed by allowing column values to be specified
as <replaceable>column-name</replaceable>/<replaceable>value</replaceable>
pairs.</para>
<para>There is considerable flexibility in how you specify the
pairs:</para>
<itemizedlist>
<listitem>
<para>At any point, you can enter a left curly bracket ('{') followed
by one or more specifications of the following forms:</para>
<simplelist>
<member><replaceable>column-name</replaceable>=<replaceable>value</replaceable></member>
<member><replaceable>column-name</replaceable>=<replaceable>>value</replaceable></member>
<member><replaceable>column-name</replaceable>:<replaceable>value</replaceable></member>
</simplelist>
<para>The pairs must be followed by a right curly bracket
("}").</para>
<para>The value may optionally be enclosed in double quotes.</para>
<para>The pairs must be separated by white space, but you can add a
comma adjacent to the <replaceable>values</replaceable> for
readability as in:</para>
<simplelist>
<member><emphasis role="bold">{ proto=>udp, port=1024
}</emphasis></member>
</simplelist>
</listitem>
<listitem>
<para>You can also separate the pairs from columns by using a
semicolon:</para>
<simplelist>
<member><emphasis role="bold">; proto:udp,
port:1024</emphasis></member>
</simplelist>
<important>
<para>This form is incompatible with INLINE_MATCHES=Yes. See the
INLINE_MATCHES option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink>.</para>
</important>
</listitem>
</itemizedlist>
<para>In Shorewall 5.0.3, the sample configuration files and the man pages
were updated to use the same column names in both the column headings and
in the alternate specification format. The following table shows the
column names for each of the table-oriented configuration files.</para>
<note>
<para>Column names are <emphasis
role="bold">case-insensitive</emphasis>.</para>
</note>
<informaltable>
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis role="bold">File</emphasis></entry>
<entry><emphasis role="bold">Column names</emphasis></entry>
</row>
<row>
<entry>accounting</entry>
<entry>action,chain, source, dest, proto, dport, sport, user,
mark, ipsec, headers</entry>
</row>
<row>
<entry>conntrack</entry>
<entry>action,source,dest,proto,dport,sport,user,switch</entry>
</row>
<row>
<entry>blacklist</entry>
<entry>networks,proto,port,options</entry>
</row>
<row>
<entry>blrules</entry>
<entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
</row>
<row>
<entry>ecn</entry>
<entry>interface,hosts. Beginning with Shorewall 4.5.4, 'host' is
a synonym for 'hosts'.</entry>
</row>
<row>
<entry>hosts</entry>
<entry>zone,hosts,options. Beginning with Shorewall 4.5.4, 'host'
is a synonym for 'hosts'.</entry>
</row>
<row>
<entry>interfaces</entry>
<entry>zone,interface,broadcast,options</entry>
</row>
<row>
<entry>maclist</entry>
<entry>disposition,interface,mac,addresses</entry>
</row>
<row>
<entry>mangle</entry>
<entry>action,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers</entry>
</row>
<row>
<entry>masq</entry>
<entry>interface,source,address,proto,port,ipsec,mark,user,switch</entry>
</row>
<row>
<entry>nat</entry>
<entry>external,interface,internal,allints,local</entry>
</row>
<row>
<entry>netmap</entry>
<entry>type,net1,interface,net2,net3,proto,dport,sport</entry>
</row>
<row>
<entry>notrack</entry>
<entry>source,dest,proto,dport,sport,user</entry>
</row>
<row>
<entry>policy</entry>
<entry>source,dest,policy,loglevel,limit,connlimit</entry>
</row>
<row>
<entry>providers</entry>
<entry>table,number,mark,duplicate,interface,gateway,options,copy</entry>
</row>
<row>
<entry>proxyarp and proxyndp</entry>
<entry>address,interface,external,haveroute,persistent</entry>
</row>
<row>
<entry>rtrules</entry>
<entry>source,dest,provider,priority</entry>
</row>
<row>
<entry>routes</entry>
<entry>provider,dest,gateway,device</entry>
</row>
<row>
<entry>routestopped</entry>
<entry>interface,hosts,options,proto,dport,sport</entry>
</row>
<row>
<entry>rules</entry>
<entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
</row>
<row>
<entry>secmarks</entry>
<entry>secmark,chain,source,dest,proto,dport,sport,user,mark</entry>
</row>
<row>
<entry>tcclasses</entry>
<entry>interface,mark,rate,ceil,prio,options</entry>
</row>
<row>
<entry>tcdevices</entry>
<entry>interface,in_bandwidth,out_bandwidth,options,redirect</entry>
</row>
<row>
<entry>tcfilters</entry>
<entry>class,source,dest,proto,dport,sport,tos,length</entry>
</row>
<row>
<entry>tcinterfaces</entry>
<entry>interface,type,in_bandwidth,out_bandwidth</entry>
</row>
<row>
<entry>tcpri</entry>
<entry>band,proto,port,address,interface,helper</entry>
</row>
<row>
<entry>tcrules</entry>
<entry>mark,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers.
Beginning with Shorewall 4.5.3, 'action' is a synonym for
'mark'.</entry>
</row>
<row>
<entry>tos</entry>
<entry>source,dest,proto,dport,sport,tos,mark</entry>
</row>
<row>
<entry>tunnels</entry>
<entry>type,zone,gateway,gateway_zone. Beginning with Shorewall
4.5.3, 'gateways' is a synonym for 'gateway'. Beginning with
Shorewall 4.5.4, 'gateway_zones' is a synonym for
'gateway_zone'.</entry>
</row>
<row>
<entry>zones</entry>
<entry>zone,type,options,in_options,out_options</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Example (rules file):</para>
<programlisting>#ACTION SOURCE DEST PROTO DPORT
DNAT net loc:10.0.0.1 tcp 80 ; mark="88"</programlisting>
<para>Here's the same line in several equivalent formats:</para>
<programlisting>{ action=>DNAT, source=>net, dest=>loc:10.0.0.1, proto=>tcp, dport=>80, mark=>88 }
; action:"DNAT" source:"net" dest:"loc:10.0.0.1" proto:"tcp" dport:"80" mark:"88"
DNAT { source=net dest=loc:10.0.0.1 proto=tcp dport=80 mark=88 }</programlisting>
<para>Beginning with Shorewall 5.0.11, ip[6]table comments can be attached
to individual rules using the <option>comment</option> keyword.</para>
<para>Example from the rules file:</para>
<programlisting> ACCEPT net $FW { proto=tcp, dport=22, comment="Accept \"SSH\"" }</programlisting>
<para>As shown in that example, when the comment contains whitespace, it
must be enclosed in double quotes and any embedded double quotes must be
escaped using a backslash ("\").</para>
</section>
<section>
<title>Using Netfilter Features not Directly Supported by
Shorewall</title>
<para>Shorewall doesn't contain built-in support for all ip[6]tables
targets and matches. Nevertheless, you can still use the unsupported
ip[6]tables features through several Shorewall facilities.</para>
<variablelist>
<varlistentry>
<term>INLINE</term>
<listitem>
<para>INLINE, added in Shorewall 4. is available in the mangle, snat
(masq) and rules files and allows you to specify ip[6]table text
following two semicolons to the right of the column-oriented
specifications.</para>
<para>INLINE takes one optional parameter which, if present, must be
a valid entry for the first column of the file. If the parameter is
omitted, then you can specify the target of the rule in the
text.</para>
<para>Examples from the rules file:</para>
<programlisting>#ACTION SOURCE DEST
?COMMENT Drop DNS Amplification Attack Packets
INLINE(DROP):info net $FW udp 53 ;; -m u32 --u32 "0>>22&0x3C\@8&0xffff=0x0100 && 0>>22&0x3C\@12&0xffff0000=0x00010000"
?COMMENT
?COMMENT Rule generated by the IfEvent action
INLINE net $FW ;; -m recent --rcheck 10 --hitcount 5 --name SSH -s 1.2.3.4 -j MARK --or-mark 0x4000
?COMMENT</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>IPTABLES and IP6TABLES</term>
<listitem>
<para>These are very similar to INLINE. The difference is that the
parameter to IPTABLES and IP6TABLES is the ip[6]tables target of the
Rule rather than a Shorewall-defined action or target.</para>
<para>Example from the mangle file:</para>
<programlisting>IPTABLES(MARK --set-mark 0x4):P eth0 1.2.3.4</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>Inline Matches</term>
<listitem>
<para>In Shorewall 4.6.0 and later, setting INLINE_MATCHES=Yes in
shorewall[6].conf allows you to include ip[6]tables matches
following a semicolon on any rule in the mangle, masq and rules
files. Note that this is incompatible with the Alternate Input form
that uses a semicolon to delimit column-oriented specifications from
column=value specifications. In Shorewall 5.0.0 and later, inline
matches are allowed in mangle, masq and rules following two adjacent
semicolons (";;"). If alternate input is present, the adjacent
semicolons should follow that input. In Shorewall 5.2.2, this
support was extended to the conntrack file.</para>
<caution>
<para>INLINE_MATCHES=Yes is deprecated and is not supported in
Shorewall 5.2 and beyond. Use two adjacent semicolons to introduce
inline matches.</para>
</caution>
<para>Example from the masq file that spits outgoing SNAT between
two public IP addresses</para>
<programlisting>COMB_IF !70.90.191.120/29 70.90.191.121 ;; -m statistic --mode random --probability 0.50
COMB_IF !70.90.191.120/29 70.90.191.123</programlisting>
<para>If the first character of the inline matches is a plus sign
("+"), then the matches are processed before the column-oriented
input in the rule. That is required when specifying additional TCP
protocol parameters.</para>
<para>Example from action.TCPFlags:</para>
<programlisting>DROP - - ;;+ -p 6 --tcp-flags ALL FIN,URG,PSH</programlisting>
</listitem>
</varlistentry>
</variablelist>
</section>
<section>
<title>Addresses</title>
<para>In both Shorewall and Shorewall6, there are two basic types of
addresses:</para>
<variablelist>
<varlistentry>
<term>Host Address</term>
<listitem>
<para>This address type refer to a single host.</para>
<para>In IPv4, the format is <emphasis>i.j.k.l</emphasis> where
<emphasis>i</emphasis> through <emphasis>l</emphasis> are decimal
numbers between 1 and 255.</para>
<para>In IPv6, the format is <emphasis>a:b:c:d:e:f:g:h</emphasis>
where <emphasis>a</emphasis> through <emphasis>h</emphasis> consist
of 1 to 4 hexidecimal digits (leading zeros may be omitted). a
single series of 0 addresses may be omitted. For example
2001:227:e857:1:0:0:0:0:1 may be written 2001:227:e857:1::1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Network Address</term>
<listitem>
<para>A network address refers to 1 or more hosts and consists of a
host address followed by a slash ("/") and a <firstterm>Variable
Length Subnet Mask</firstterm> (VLSM). This is known as
<firstterm>Classless Internet Domain Routing</firstterm> (CIDR)
notation.</para>
<para>The VLSM is a decimal number. For IPv4, it is in the range 0
through 32. For IPv6, the range is 0 through 128. The number
represents the number of leading bits in the address that represent
the network address; the remainder of the bits are a host address
and are generally given as zero.</para>
<para>Examples:</para>
<para>IPv4: 192.168.1.0/24</para>
<para>IPv6: 2001:227:e857:1:0:0:0:0:1/64</para>
</listitem>
</varlistentry>
</variablelist>
<para>In the Shorewall documentation and manpages, we have tried to make
it clear which type of address is accepted in each specific case.</para>
<para>Because Shorewall uses a colon (":") as a separator in many
contexts, IPv6 addresses are best written using the standard convention in
which the address itself is enclosed in square brackets:</para>
<simplelist>
<member>[2001:227:e857:1::1]</member>
<member>[2001:227:e857:1:0:0:0:0:1]/64</member>
</simplelist>
<para>For more information about addressing, see the<ulink
url="shorewall_setup_guide.htm#Addressing"> Setup Guide</ulink>.</para>
</section>
<section id="SOURCE-DEST">
<title>Specifying SOURCE and DEST</title>
<para>Entries in Shorewall configuration files often deal with the source
(SOURCE) and destination (DEST) of connections and Shorewall implements a
uniform way for specifying them.</para>
<para>A SOURCE or DEST consists of one to three parts separated by colons
(":"):</para>
<orderedlist>
<listitem>
<para>ZONE — The name of a zone declared in
<filename>/etc/shorewall/zones</filename> or
<filename>/etc/shorewall6/zones</filename>. This part is only
available in the rules file
(<filename>/etc/shorewall/rules</filename>,
<filename>/etc/shorewall/blrules</filename>,<filename>
/etc/shorewall6/rules</filename> and
<filename>/etc/shorewall6/blrules</filename>).</para>
</listitem>
<listitem>
<para>INTERFACE — The name of an interface that matches an entry in
<filename>/etc/shorewall/interfaces</filename>
(<filename>/etc/shorewall6/interfaces</filename>).</para>
</listitem>
<listitem>
<para>ADDRESS LIST — A list of one or more addresses (host or network)
or address ranges, separated by commas. In an IPv6 configuration, this
list must be included in square or angled brackets ("[...]" or
"<...>"). The list may have <link
linkend="Exclusion">exclusion</link>.</para>
</listitem>
</orderedlist>
<para>Examples.</para>
<orderedlist>
<listitem>
<para>All hosts in the <emphasis role="bold">net</emphasis> zone —
<emphasis role="bold">net</emphasis></para>
</listitem>
<listitem>
<para>Subnet 192.168.1.0/29 in the <emphasis
role="bold">loc</emphasis> zone — <emphasis
role="bold">loc:192.168.1.0/29</emphasis></para>
</listitem>
<listitem>
<para>All hosts in the net zone connecting through <filename
class="devicefile">ppp0</filename> — <emphasis
role="bold">net:ppp0</emphasis></para>
</listitem>
<listitem>
<para>All hosts interfaced by <filename
class="devicefile">eth3</filename> — <emphasis
role="bold">eth3</emphasis></para>
</listitem>
<listitem>
<para>Subnet 10.0.1.0/24 interfacing through <filename><filename
class="devicefile">eth2</filename></filename> — <emphasis
role="bold">eth2:10.0.1.0/24</emphasis></para>
</listitem>
<listitem>
<para>Host 2002:ce7c:92b4:1:a00:27ff:feb1:46a9 in the <emphasis
role="bold">loc</emphasis> zone — <emphasis
role="bold">loc:[2002:ce7c:92b4:1:a00:27ff:feb1:46a9]</emphasis></para>
</listitem>
<listitem>
<para>The primary IP address of eth0 in the $FW zone - <emphasis
role="bold">$FW:&eth0</emphasis> (see <link
linkend="Rvariables">Run-time Address Variables</link> below)</para>
</listitem>
<listitem>
<para>All hosts in Vatican City - <emphasis
role="bold">net:^VA</emphasis> (Shorwall 4.5.4 and later - See <ulink
url="ISO-3661.html">this article</ulink>).</para>
</listitem>
</orderedlist>
</section>
<section id="INCLUDE">
<title>INCLUDE Directive</title>
<para>Any configuration file may contain INCLUDE directives. An INCLUDE
directive consists of the word INCLUDE followed by a path name and causes
the contents of the named file to be logically included into the file
containing the INCLUDE. Relative path names given in an INCLUDE directive
are resolved using the current CONFIG_PATH setting (see <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>
<para>INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
directives are ignored with a warning message.</para>
<para>Beginning with Shorewall 4.4.17, the INCLUDE directive may also
appear in the following <ulink
url="shorewall_extension_scripts.htm">extension scripts</ulink>:</para>
<itemizedlist>
<listitem>
<para>clear</para>
</listitem>
<listitem>
<para>findgw</para>
</listitem>
<listitem>
<para>init</para>
</listitem>
<listitem>
<para>isusable</para>
</listitem>
<listitem>
<para>refresh</para>
</listitem>
<listitem>
<para>refreshed</para>
</listitem>
<listitem>
<para>restore</para>
</listitem>
<listitem>
<para>restored</para>
</listitem>
<listitem>
<para>start</para>
</listitem>
<listitem>
<para>started</para>
</listitem>
<listitem>
<para>stop</para>
</listitem>
<listitem>
<para>stopped</para>
</listitem>
<listitem>
<para>tcclear</para>
</listitem>
</itemizedlist>
<para>When used in these scripts, the INCLUDEd files are copied into the
compiled firewall script.</para>
<caution>
<para>Prior to Shorewall 4.4.17, if you are using <ulink
url="Shorewall-Lite.html">Shorewall Lite</ulink> , it is not advisable
to use INCLUDE in the <filename>params</filename> file in an export
directory if you set EXPORTPARAMS=Yes in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). If you do
that, you must ensure that the included file is also present on the
firewall system's <filename
class="directory">/etc/shorewall-lite/</filename> directory.</para>
<para>If you only need the <filename>params</filename> file at compile
time, you can set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>. That prevents the
<filename>params</filename> file from being copied into the compiled
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
<filename>params</filename> file. Note that with Shorewall 4.4.17 and
later:</para>
<itemizedlist>
<listitem>
<para>The variables set at compile time are available at run-time
even with EXPORTPARAMS=No.</para>
</listitem>
<listitem>
<para>The INCLUDE directive in the <filename>params</filename> file
is processed at compile time and the INCLUDEd file is copied into
the compiled script.</para>
</listitem>
</itemizedlist>
</caution>
<example id="include">
<title>Use of INCLUDE</title>
<programlisting> shorewall/params.mgmt:
  MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3
  TIME_SERVERS=4.4.4.4
  BACKUP_SERVERS=5.5.5.5
  ----- end params.mgmt -----
  shorewall/params:
  # Shorewall 1.3 /etc/shorewall/params
  [..]
  #######################################
Â
  INCLUDE params.mgmt  Â
Â
  # params unique to this host here
 Â
  ----- end params -----
  shorewall/rules.mgmt:
  ACCEPT net:$MGMT_SERVERS   $FW   tcp   22
  ACCEPT $FW         net:$TIME_SERVERS   udp   123
  ACCEPT $FW         net:$BACKUP_SERVERS tcp   22
  ----- end rules.mgmt -----
  shorewall/rules:
  # Shorewall version 1.3 - Rules File
  [..]
  #######################################
Â
  INCLUDE rules.mgmt   Â
Â
  # rules unique to this host here
 Â
  ----- end rules -----</programlisting>
<para>You may include multiple files in one command using an <link
linkend="Embedded">embedded shell command</link>.</para>
<para>Example (include all of the files ending in ".rules" in a
directory:):<programlisting>gateway:/etc/shorewall # ls rules.d
ALL.rules DNAT.rules FW.rules NET.rules REDIRECT.rules VPN.rules
gateway:/etc/shorewall # </programlisting></para>
<para>/etc/shorewall/rules:<programlisting>?SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
<para>If you are the sort to put such an entry in your rules file even
though /etc/shorewall/rules.d might not exist or might be empty, then
you probably want:</para>
<programlisting>?SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules 2> /dev/null || true</programlisting>
<para>Beginning with Shorewall 4.5.2, in files other than
<filename>/etc/shorewall/params</filename> and
<filename>/etc/shorewall/conf</filename>, INCLUDE may be immediately
preceded with '?' to signal that the line is a compiler directive and
not configuration data.</para>
<para>Example:</para>
<programlisting>?INCLUDE common.rules</programlisting>
</example>
</section>
<section>
<title>?FORMAT Directive</title>
<para>A number of configuration files support multiple formats. Prior to
Shorewall 4.5.11, the format was specified by a line having 'FORMAT' as
the first token. This requires each of the file processors to handle
FORMAT separately.</para>
<para>In Shorewall 4.5.11, the ?FORMAT directive was created to centralize
processing of FORMAT directives. The old entries, while still supported in
Shorewall 4.5-4.6, are now deprecated. They are no longer supported in
Shorewall 5.0 and later versions.</para>
<para>The ?FORMAT directive is as follows:</para>
<variablelist>
<varlistentry>
<term>?FORMAT <replaceable>format</replaceable></term>
<listitem>
<para>Where format is an integer. In all cases, the default format
is 1. The following table shows the files that have different
formats and the supported formats for each.</para>
</listitem>
</varlistentry>
</variablelist>
<informaltable>
<tgroup align="left" cols="2">
<tbody>
<row>
<entry>FILE</entry>
<entry>FORMATS</entry>
</row>
<row>
<entry>action files (action.*)</entry>
<entry>1 and 2</entry>
</row>
<row>
<entry>conntrack</entry>
<entry>1, 2 and 3</entry>
</row>
<row>
<entry>interfaces</entry>
<entry>1 and 2</entry>
</row>
<row>
<entry>macro files (macro.*)</entry>
<entry>1 and 2</entry>
</row>
<row>
<entry>tcrules</entry>
<entry>1 and 2</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>?COMMENT Directive</title>
<para>A number of files allow attaching comments to generated Netfilter
rules:</para>
<simplelist>
<member><filename>accounting</filename></member>
<member><filename>action</filename>.* files</member>
<member><filename>blrules</filename></member>
<member><filename>conntrack</filename></member>
<member><filename>macro</filename>.* files</member>
<member><filename>snat</filename></member>
<member><filename>nat</filename></member>
<member><filename>rules</filename></member>
<member><filename>secmarks</filename></member>
<member><filename>tcrules</filename></member>
<member><filename>tunnels</filename></member>
</simplelist>
<para>Prior to Shorewall 4.5.11, comments were specified by a line having
COMMENT as the first token. The remainder of the line is treated as a
comment to be attached to rules.</para>
<para>In Shorewall 4.5.11, the ?COMMENT directive was created to
centralize processing of COMMENT directives. The old entries, while still
supported in Shorewall 4.5 and 4.6, are now deprecated. They are no longer
supported in Shorewall 5.0 and later versions.</para>
<para>Use of this directive requires Comment support in your kernel and
iptables - see the output of <command><link
linkend="capabilities">shorewall show
capabilities</link></command>.</para>
<para>The ?COMMENT directive is as follows:</para>
<variablelist>
<varlistentry>
<term>?COMMENT [ <replaceable>comment</replaceable> ]</term>
<listitem>
<para>If <replaceable>comment</replaceable> is present, it will
appear enclosed in /*....*/ in the output of the <command>shorewall
show </command>and <command>shorewall dump</command> commands. If no
<replaceable>comment</replaceable> is present, the rules generated
by following entries will not have comments attached.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Example (<filename>/etc/shorewall/rules</filename>):</para>
<programlisting>?COMMENT Stop NETBIOS noise
REJECT loc net tcp 137,445
REJECT loc net udp 137:139
?COMMENT Stop my idiotic work laptop from sending to the net with an HP source/dest IP address
DROP loc:!192.168.0.0/22 net
?COMMENT</programlisting>
<para>Here's the corresponding output from
<filename>/sbin/shorewall-lite</filename>:</para>
<programlisting>gateway:~ # <command>shorewall-lite show loc-net</command>
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008
Counters reset Mon Oct 16 14:52:17 PDT 2006
Chain loc-net (1 references)
pkts bytes target prot opt in out source destination
0 0 LOG tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25
0 0 LOG udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 137,445 <emphasis
role="bold">/* Stop NETBIOS noise */</emphasis>
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:137:139 <emphasis
role="bold">/* Stop NETBIOS noise */</emphasis>
0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 <emphasis
role="bold">/* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */</emphasis>
5 316 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0
gateway:~ #
</programlisting>
<para>?COMMENT lines in macro files work somewhat differently from other
files. ?COMMENT lines in macros are ignored if COMMENT support is not
available or if there was a COMMENT in use when the top-level macro was
invoked. This allows the following:</para>
<para><filename>/usr/share/shorewall/macro.SSH</filename>:</para>
<para><programlisting>#ACTION SOURCE DEST PROTO DPORT SPORT RATE USER
?COMMENT SSH
PARAM - - tcp 22 </programlisting>
<filename>/etc/shorewall/rules</filename>:<programlisting>?COMMENT Allow SSH from home
SSH(ACCEPT) net:$MYIP $FW
?COMMENT</programlisting>The comment line in macro.SSH will not override the
?COMMENT line in the rules file and the generated rule will show <emphasis
role="bold">/* Allow SSH from home */</emphasis> when displayed through
the Shorewall show and dump commands.</para>
<para>Beginning with Shorewall 5.0.11, the <link linkend="Pairs">alternate
input format </link>allows attaching comments to individual rules in the
files listed above.</para>
</section>
<section id="CONFIG_PATH">
<title>CONFIG_PATH</title>
<para>The CONFIG_PATH option in shorewall.conf determines where the
compiler searches for configuration files. The default setting is
CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that the
compiler first looks in /etc/shorewall and if it doesn't find the file, it
then looks in /usr/share/shorewall.</para>
<para>You can change this setting to have the compiler look in different
places. For example, if you want to put your own versions of standard
macros in /etc/shorewall/Macros, then you could set
CONFIG_PATH=/etc/shorewall:/etc/shorewall/Macros:/usr/share/shorewall and
the compiler will use your versions rather than the standard ones.</para>
</section>
<section id="Variables">
<title>Using Shell Variables</title>
<para>You may use the <filename>/etc/shorewall/params</filename> file to
set shell variables that you can then use in the other configuration
files.</para>
<para>It is suggested that variable names begin with an upper case letter
to distinguish them from variables used internally within the Shorewall
programs</para>
<para>The following variable names must be avoided. Those in <emphasis
role="bold">bold font</emphasis> must be avoided in all Shorewall
versions; those in regular font must be avoided in versions prior to
4.4.8.</para>
<simplelist>
<member><emphasis role="bold">Any option from <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>
(5)</emphasis></member>
<member><emphasis role="bold">COMMAND</emphasis></member>
<member><emphasis role="bold">CONFDIR</emphasis></member>
<member>DEBUG</member>
<member>ECHO_E</member>
<member>ECHO_N</member>
<member>EXPORT</member>
<member>FAST</member>
<member>FILEMODE</member>
<member>HOSTNAME</member>
<member>IPT_OPTIONS</member>
<member>NOROUTES</member>
<member>PREVIEW</member>
<member>PRODUCT</member>
<member>PROFILE</member>
<member>PURGE</member>
<member>RECOVERING</member>
<member>RESTOREPATH</member>
<member>RING_BELL</member>
<member><emphasis role="bold">SHAREDIR</emphasis></member>
<member><emphasis role="bold">Any name beginning with SHOREWALL_ or
SW_</emphasis></member>
<member>STOPPING</member>
<member>TEST</member>
<member>TIMESTAMP</member>
<member>USE_VERBOSITY</member>
<member><emphasis role="bold">VARDIR</emphasis></member>
<member><emphasis role="bold">VARLIB</emphasis></member>
<member>VERBOSE</member>
<member>VERBOSE_OFFSET</member>
<member>VERSION</member>
</simplelist>
<para>Example:</para>
<blockquote>
<programlisting>Â Â Â /etc/shorewall/params
NET_IF=eth0
NET_BCAST=130.252.100.255
NET_OPTIONS=routefilter,routefilter
   /etc/shorewall/interfaces record:
net $NET_IF $NET_BCAST $NET_OPTIONS
   The result will be the same as if the record had been written
net eth0 130.252.100.255 routefilter,routefilter
</programlisting>
</blockquote>
<para>Variables may be used anywhere in the other configuration
files.<note>
<para>If you use "$FW" on the right side of assignments in the
<filename>/etc/shorewall/params</filename> file, you must also set the
FW variable in that file.</para>
<para>Example:<programlisting>/etc/shorewall/zones:
#ZONE TYPE OPTIONS
<emphasis role="bold">fw</emphasis> firewall
/etc/shorewall/params:
FW=<emphasis role="bold">fw</emphasis>
BLARG=$FW:206.124.146.176</programlisting></para>
</note></para>
<para>Because the <filename>/etc/shorewall/params</filename> file is
simply sourced into the shell, you can place arbitrary shell code in the
file and it will be executed each time that the file is read. Any code
included should follow these guidelines:</para>
<orderedlist>
<listitem>
<para>The code should not have side effects, especially on other
shorewall configuration files.</para>
</listitem>
<listitem>
<para>The code should be safe to execute multiple times without
producing different results.</para>
</listitem>
<listitem>
<para>Should not depend on where the code is called from.</para>
</listitem>
<listitem>
<para>Should not assume anything about the state of Shorewall.</para>
</listitem>
<listitem>
<para>The names of any functions or variables declared should begin
with an upper case letter.</para>
</listitem>
<listitem>
<para>The <filename>/etc/shorewall/params</filename> file is processed
by the compiler at compile-time and by the compiled script at
run-time. If you have set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>, then the
<filename><filename>params</filename></filename> file is only
processed by the compiler; it is not run by the compiled script.
Beginning with Shorewall 4.4.17, the values of the variables set at
compile time are available at run time with EXPORTPRARMS=No.</para>
</listitem>
<listitem>
<para>If you are using <ulink url="Shorewall-Lite.html">Shorewall
Lite</ulink> and if the <filename>params</filename> script needs to
set shell variables based on the configuration of the firewall system,
you can use this trick:</para>
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
<para>The <command>shorewall-lite call</command> command allows you to
call interactively any Shorewall function that you can call in an
extension script.</para>
<note>
<para>Within your configuration files, only the $VAR and ${VAR}
forms of variable expansion are supported. You may not use the more
exotic forms supported by the shell (${VAR:=val}, ${VAR:-val},
...)</para>
</note>
</listitem>
</orderedlist>
<para>Beginning with Shorewall 4.4.27, you may also use options in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5) (e.g.,
$BLACKLIST_LOGLEVEL).</para>
<note>
<para>When an option is set to 'No' in shorewall.conf, the corresponding
shell variable will be empty.</para>
</note>
<note>
<para>Options that were not set in shorewall.conf will expand to their
default value.</para>
</note>
<para id="Rvariables">Beginning with Shorewall 4.5.2, configuration files
can access variables defined in the <ulink
url="Install.htm#shorewallrc">shorewallrc file</ulink>.</para>
<para>Beginning with Shorewall 4.5.11, variables can be altered by
compiler directives.</para>
<variablelist>
<varlistentry>
<term>?SET <replaceable>variable value</replaceable></term>
<listitem>
<para>The <replaceable>variable</replaceable> can be specified
either with or without a leading '$' to allow using both Perl and
Shell variable representation. The ${...} form (e.g. ${foo}) is not
allowed.</para>
<para>The <replaceable>value</replaceable> is a Perl-compatible
expression.</para>
<note>
<para>The Shorewall compiler performs variable expansion within
the expression. So variables are expanded even when they appear in
single quotes.</para>
</note>
<note>
<para>If a variable within the expression can contain a
non-numeric value, it is a good idea to enclose it in quotes.
Otherwise, the Shorewall compiler has to guess whether to enclose
the variable's value in quotes or not.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>?RESET <replaceable>variable</replaceable></term>
<listitem>
<para>Removes the named <replaceable>variable</replaceable> from the
compiler's variable table.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Action variables are read-only and cannot be ?SET (although you can
change their values <ulink url="Actions.html#Embedded">using embedded
Perl</ulink>).</para>
<para>Beginning with Shorewall 4.5.13, <link
linkend="ShorewallVariables">Shorewall Variables</link> may be set. When
setting a Shorewall Variable, the <replaceable>variable</replaceable> must
include the leading '@' and the @{...} form is not allowed.</para>
</section>
<section id="AddressVariables">
<title>Address Variables</title>
<caution>
<para>Prior to Shorewall 5.0.14, if you use address variables that refer
to an optional interface, the <command>enable</command> command will not
change/insert the rules that use the variable. Therefore, to be
completely safe, if you use such address variables then you must follow
a successful <command>enable</command> command with a
<command>reload</command> command.</para>
<para>Beginning with Shorewall 5.0.14, if a Shorewall-defined address
variable's value has changed since the Netfilter ruleset was
instantiated, then a successful <command>enable</command> command will
automatically reload the ruleset.</para>
</caution>
<para>Given that shell variables are expanded at compile time, there is no
way to cause such variables to be expanded at run time. Prior to Shorewall
4.4.17, this made it difficult (to impossible) to include dynamic IP
addresses in a <ulink url="Shorewall-Lite.html">Shorewall-lite</ulink>
configuration.</para>
<para>Version 4.4.17 implemented <firstterm>Run-time address
variables</firstterm>. In configuration files, these variables are
expressed as an apersand ('&') followed by the logical name of an
interface defined in shorewall-interfaces (5). Wildcard interfaces (those
ending in '+') are not supported and will cause a compilation
error.</para>
<variablelist>
<varlistentry>
<term>Example:</term>
<listitem>
<para><emphasis role="bold">&eth0</emphasis> would represent the
primary IP address of eth0.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Beginning with Shorewall 4.5.11, you can define your own address
variables by using this syntax:</para>
<simplelist>
<member>&{<replaceable>variable</replaceable>}</member>
</simplelist>
<para>where <replaceable>variable</replaceable> is a valid shell variable
name. The generated script will verify that the
<replaceable>variable</replaceable> contains a valid host or network
address, either from the environment or from it being assigned in your
<emphasis>init</emphasis> <ulink
url="shorewall_extension_scripts.htm">extension script</ulink>, and will
raise an error if it does not. In the error case, the state of the
firewall will remain unchanged.</para>
<para>Example:</para>
<para>/etc/shorewall/init:</para>
<programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>
<para>/etc/shorewall/rules:</para>
<programlisting>test:debug net:<emphasis role="bold">&{SMC_ADDR}</emphasis> fw</programlisting>
<para>A second form is also available beginning with Shorewall
4.5.11</para>
<simplelist>
<member>%{<replaceable>variable</replaceable>}</member>
</simplelist>
<para>Unlike with the first form, this form does not require the variable
to be set. If the variable is empty, the generated script will supply the
all-zeros address (0.0.0.0 in IPv4 and :: in IPv6). In most cases, the
compiler simply omits rules containing matches on the all-zeros
address.</para>
<para>Example:</para>
<para>/etc/shorewall/init:</para>
<programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>
<para>/etc/shorewall/rules:</para>
<programlisting>test:debug net:<emphasis role="bold">%{SMC_ADDR}</emphasis> fw</programlisting>
<important>
<para>For a particular address variable, all references must use the
same prefix character ('&' or '%'). Otherwise, the following error
message is raised:</para>
<simplelist>
<member>ERROR: Mixed required/optional usage of address variable
<replaceable>variable</replaceable></member>
</simplelist>
</important>
<para>Run-time address variables may be used in the SOURCE and DEST column
of the following configuration files:</para>
<itemizedlist>
<listitem>
<para><ulink
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink url="Actions.html">Action</ulink> files</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-blrules.html">shorewall-blrules</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink url="Macros.html">Macro</ulink> files</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-mangle.html">shorewall-mangle</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5)</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
</listitem>
</itemizedlist>
<para>They may also appear in the ORIGDEST column of:</para>
<itemizedlist>
<listitem>
<para><ulink
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink url="Macros.html">Macro</ulink> files</para>
</listitem>
<listitem>
<para><ulink url="Actions.html">Action</ulink> files</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
</listitem>
</itemizedlist>
<para>For optional interfaces, if the interface is not usable at the time
that the firewall starts, one of two approaches are taken, depending on
the context:</para>
<itemizedlist>
<listitem>
<para>the all-zero address will be used (0.0.0.0 in IPv4 and :: in
IPv6), resulting in no packets matching the rule (or all packets if
used with exclusion).</para>
</listitem>
<listitem>
<para>the entire rule is omitted from the ruleset.</para>
</listitem>
</itemizedlist>
<para>Beginning with Shorewall 4.5.1, <firstterm>Run-time Gateway
Variables</firstterm> in the form of a percent sign ('%') followed by a
logical interface name are also supported. These are expanded at run-time
to the gateway through the named interface. For optional interfaces, if
the interface is not usable at the time that the firewall starts, the nil
address will be used (0.0.0.0 in IPv4 and :: in IPv6), resulting in no
packets matching the rule. Run-time gateway variables may be used in the
SOURCE and DEST columns of the following configuration files:</para>
<itemizedlist>
<listitem>
<para><ulink
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink url="Actions.html">Action</ulink> files</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-blrules.html">shorewall-blrules</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink url="Macros.html">Macro</ulink> files</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-mangle.html">shorewall-mangle</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5) (As a
qualifier to the INTERFACE).</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-routes.html">shorewall-routes</ulink>
(5)</para>
</listitem>
<listitem>
<para><ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
</listitem>
</itemizedlist>
<variablelist>
<varlistentry>
<term>Example:</term>
<listitem>
<para><emphasis role="bold">%eth0</emphasis> would represent the IP
address of the gateway out of eth0.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If there is no gateway out of the named interface, rules containing
the intefaces's run-time gateway variable are omitted.</para>
</section>
<section id="Port_Variables">
<title>Port Variables</title>
<para>Beginning with Shorewall 5.1.5, <firstterm>Run-time Port
Variables</firstterm> are supported. These variables have the format
%{<replaceable>variable</replaceable>} and may appear any place that a
port number or service name may appear. Like their address-variable
counterparts above, Run-time Port Variables are most useful when
Shorewall[6]-lite is being used.</para>
<para>Example using both Run-time Address and Run-time Port
Variables:</para>
<para>/etc/shorewall/init:</para>
<programlisting> SERVER_PORT=4126
SERVER_ADDRESS=192.0.44.12</programlisting>
<para>/etc/shorewall/rules:</para>
<programlisting> ACCEPT net dmz:%{SERVER_ADDRESS} tcp %{SERVER_PORT}</programlisting>
<para>Rather than assigning a numerical literal to SERVER_PORT in the
<filename>init</filename> extension script as shown above, the variable
could be assigned a dynamic value based on a database lookup.</para>
<important>
<para>If no value is assigned to a Run-time Port Variable in the
<filename>init</filename> extension script, then the value 255 is
assumed.</para>
</important>
<caution>
<para>Care must be exercised when using port variables in port ranges.
At run-time, the generated script will verify that each port variable is
either empty or contains a valid port number or service name. It does
not ensure that the low port number in a range is strictly less than the
high port number, when either of these is specified as a port
variable.</para>
<para>Example: The following definitions will result in an
iptables-restore failure during start/restart/reload:</para>
<para>/etc/shorewall/init:</para>
<programlisting> LOW_PORT=100
HIGH_PORT=50</programlisting>
<para>/etc/shorewall/rules:</para>
<programlisting> ACCEPT net $FW tcp ${LOW_PORT}:${HIGH_PORT}</programlisting>
</caution>
</section>
<section id="ActionVariables">
<title>Action Variables</title>
<para>Action variables were introduced in Shorewall 4.4.16 and may be
accessed within the body of an <ulink
url="Actions.html">action</ulink>.</para>
<variablelist>
<varlistentry>
<term>Parameter variables</term>
<listitem>
<para>Parameter variables expand to the value of the corresponding
action parameter. <emphasis>$1</emphasis> is the first parameter,
<emphasis>$2</emphasis> is the second parameter and so on.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Chain name</term>
<listitem>
<para>Beginning with Shorewall 4.5.10, $0 expands to the name of the
action chain. Shorewall generates a separate chain for each unique
(action,log-level,log-tag,parameters) tupple. The first such chain
has the same name as the action itself. Subsequent chains are formed
by prepending '%' to the action name and appending a number to
insure uniqueness. For an action called 'Action', the chains would
be <emphasis>Action</emphasis>, <emphasis>%Action</emphasis>,
<emphasis>%Action0</emphasis>, <emphasis>%Action1</emphasis> and so
on.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="ShorewallVariables">
<title>Shorewall Variables</title>
<para>Shorewall Variables were introduced in Shorewall 4.5.11. To insure
uniqueness, these variables start with the character @; the name of the
variable must be enclosed in {...} when the following character is
alphanumeric or is an underscore ("_"). With the exception of @0 (or it's
alias @chain), Shorewall variables may only be used within an action
body.</para>
<para>Prior to Shorewall 4.5.13, Shorewall variables are read-only.
Beginning with Shorewall 4.5.13, their values may be altered using the
?SET directive.</para>
<para>The Shorewall variables are:</para>
<variablelist>
<varlistentry>
<term>@0 and @chain (@{0} and @{chain})</term>
<listitem>
<para>Expands to the name of the current chain. Unlike $0, @0 has
all non-alphanumeric characters except underscore removed. Also
unlike $0, @0 may be used in SWITCH columns in configuration
files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@1, @2, ... (@{1}, @{2}, ...</term>
<listitem>
<para>These are synonyms for the Action parameter variables $1, $2,
etc.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@loglevel (@{loglevel})</term>
<listitem>
<para>Expands to the log level specified when the action was
invoked.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@logtag (@{logtag})</term>
<listitem>
<para>Expands to the log tag specified when the action was
invoked.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@action(@{action})</term>
<listitem>
<para>Expands to the name of the action being compiled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@disposition (@{disposition})</term>
<listitem>
<para>Added in Shorewall 4.5.13. When a non-inlined action is
entered, this variable is set to the empty value. When an inline
action is entered, the variable's value is unchanged.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>@caller (@{caller})</term>
<listitem>
<para>Added in Shorewall 4.5.13. Within an action, expands to the
name of the chain that invoked the action.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Beginning with Shorewall 4.5.13, the values of @chain and
@disposition are used to generated the --log-prefix in logging rules. When
either is empty, the historical value is used to generate the
--log-prefix.</para>
<para>Within an action body, if a parameter is omitted in a DEFAULTS
statement, then the value of the corresponding action and Shorewall
variables is '-', while if the parameter is specified as '-' in the
parameter list, the value of the action/Shorewall variable is '', if it is
expanded before the DEFAULTS statement.</para>
<para>Additionally, when an expression is evaluated, the value 0 evaluates
as false, so '?IF @n' and '?IF $n' fail if the nth parameter is passed
with value zero. To make testing of the presense of parameters more
efficient and uniform, an new function has been added in Shorewall 5.0.7
for use in ?IF and ?ELSEIF:</para>
<simplelist>
<member>?IF [!] passed(<variable>)</member>
</simplelist>
<para>where <variable> is an action or Shorewall variable.</para>
<para>'passed(@n)' and 'passed($n)' evaluate to true if the nth parameter
is not empty and its contents are other than '-'. If '!' is present, the
result is inverted.</para>
<para>In this simple form, the expression is evaluated by the compiler
without having to invoke the (expensive) Perl exec() function. The
'passed' function may also be used in more complex expressions, but exec()
will be invoked to evaluate those expressions.</para>
</section>
<section id="Conditional">
<title>Conditional Entries</title>
<para>Beginning with Shorewall 4.5.2, lines in configuration files may be
conditionally included or omitted based on the setting of <link
linkend="Variables">Shell variables</link>.</para>
<para>The general form is:</para>
<programlisting>?IF <replaceable>$variable
</replaceable><lines to be included if $variable is non-empty and non-zero>
?ELSE
<lines to be omitted if $variable is non-empty and non-zero>
?ENDIF</programlisting>
<para>The compiler predefines two special
<replaceable>variable</replaceable>s that may only be used in ?IF
lines:</para>
<variablelist>
<varlistentry>
<term>__IPV4</term>
<listitem>
<para>True if this is an IPv4 compilation</para>
</listitem>
</varlistentry>
<varlistentry>
<term>__IPV6</term>
<listitem>
<para>True if this is an IPv6 compilation.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Unless <replaceable>variable</replaceable> is one of these
pre-defined ones, it is searched for in the following places in the order
listed.</para>
<itemizedlist>
<listitem>
<para>the compiler's environmental variables.</para>
</listitem>
<listitem>
<para>variables set in
<filename>/etc/shorewall/params</filename>.</para>
</listitem>
<listitem>
<para>options set in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
</listitem>
<listitem>
<para>options set in the <filename>shorewallrc</filename> file when
Shorewall Core was installed.</para>
</listitem>
</itemizedlist>
<important>
<para>Beginning with Shorewall 4.5.11, the compiler's environmental
variables are search last rather than first.</para>
</important>
<para>If the <replaceable>variable</replaceable> is still not
found:</para>
<itemizedlist>
<listitem>
<para>if it begins with '__', then those leading characters are
stripped off.</para>
</listitem>
<listitem>
<para>the variable is then searched for in the defined
<firstterm>capabilities</firstterm>. The current set of capabilities
may be obtained by the command <command>shorewall show
capabilities</command> (the capability names are in
parentheses).</para>
</listitem>
</itemizedlist>
<para>If it is not found in any of those places, the
<replaceable>variable</replaceable> is assumed to have a value of 0
(false) in Shorewall versions prior to 4.5.11. In 4.5.11 and later, it is
assumed to have the value '' (an empty string, which also evaluates to
false).</para>
<para>The setting in <filename>/etc/shorewall/params</filename> may be
overridden at runtime, provided the setting in
<filename>/etc/shorewall/params</filename> is done like this:</para>
<programlisting>[ -n "${<replaceable>variable</replaceable>:=0}" ]</programlisting>
<para>or like this:</para>
<programlisting>[ -n "${<replaceable>variable</replaceable>}" ] || <replaceable>variable</replaceable>=0</programlisting>
<para>Either of those will set variable to 0 if it is not set to a
non-empty value in the environment. The setting can be overridden at
runtime:</para>
<programlisting><replaceable>variable</replaceable>=1 shorewall restart -c # use -c to force recompilation if AUTOMAKE=Yes in /etc/shorewall/shorewall.conf</programlisting>
<para>The ?ELSE may be omitted if there are no lines to be omitted.</para>
<para>The test may also be inverted using '!':</para>
<programlisting>?IF ! <replaceable>$variable
</replaceable><lines to be omitted if $variable is non-empty and non-zero>
?ELSE
<lines to be included if $variable is non-empty and non-zero>
?ENDIF</programlisting>
<para>Conditional entries may be nested but the number of ?IFs must match
the number of ?ENDs in any give file. <link linkend="INCLUDE">INCLUDE
directives</link> are ignored in omitted lines.</para>
<programlisting>?IF <replaceable>$variable1
</replaceable><lines to be included if $variable1 is non-empty and non-zero>
?IF $variable2
<lines to be included if $variable1 and $variable2 are non-empty and non-zero>
?ELSE
<lines to be omitted if $variable1 is non-empty and non-zero and if $variable2 is empty or zero>
?ENDIF
<replaceable>
</replaceable><lines to be included if $variable1 is non-empty and non-zero>
?ELSE
<lines to be omitted if $variable is non-empty and non-zero>
?ENDIF</programlisting>
<para>Beginning with Shorewall 4.5.6, rather than a simple variable in ?IF
directives, Perl-compatible expressions are allowed (after the Shorewall
compiler expands all variables, the resulting expression is then evaluated
by Perl). Variables in the expressions are as described above.</para>
<para>Example:</para>
<programlisting>?IF $BLACKLIST_LOGLEVEL == 6 && ! __LOG_OPTIONS</programlisting>
<para>Additionally, a ?ELSIF directive is supported.</para>
<para>Example:</para>
<programlisting>?IF <replaceable>expression-1
</replaceable><lines to be included if expression-1 evaluates to true (non-empty and non-zero)
?ELSIF <replaceable>expression1-2</replaceable>
<lines to be included if expression-1 evaluates to false (zero or empty) and expression-2 evaluates to true
?ELSIF <replaceable>expression-3
</replaceable>
<lines to be included if expression-1 and expression-2 both evalute to false and expression-3 evalutes to true
?ELSE
<lines to be included if all three expressions evaluate to false.
?ENDIF</programlisting>
<para>Beginning in Shorewall 5.0.7, an error can be raised using the
?ERROR directive:</para>
<programlisting>?ERROR <replaceable>message</replaceable></programlisting>
<para>Variables in the message are evaluated and the result appears in a
standard Shorewall ERROR: message.</para>
<para>Example from the 5.0.7 action.GlusterFS:</para>
<programlisting>?if @1 !~ /^\d+/ || ! @1 || @1 > 1024
?error Invalid value for Bricks (@1)
?elsif @2 !~ /^[01]$/
?error Invalid value for IB (@2)
?endif
</programlisting>
<para>The above code insures that the first action paramater is a non-zero
number <= 1024 and that the second parameter is either 0 or 1. If 2000
is passed for the first parameter, the following error message is
generated:</para>
<programlisting> ERROR: Invalid value for Bricks (2000) /usr/share/shorewall/action.GlusterFS (line 15)
from /etc/shorewall/rules (line 45)</programlisting>
<para>In Shorewall 5.0.8, ?WARNING and ?INFO directives were added.</para>
<programlisting>?WARNING <replaceable>message</replaceable>
?INFO <replaceable>message</replaceable></programlisting>
<para>?WARNING message produces a standard Shorewall WARNING: message,
while ?INFO produces a similar message which is prefaced by INFO: rather
than WARNING:. Both write the message to STDERR. The message is also
written to the STARTUP_LOG, if any, provided that the command is
<command>start</command>, <command>try</command>,
<command>restart</command>, <command>reload</command>,
<command>refresh</command>, or one of the <command>safe</command>-*
commands.</para>
<para>See the VERBOSE_MESSAGES option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink> for
additional information.</para>
<para>In Shorewall 5.1.4, the behavior of ?ERROR, ?WARNING and ?INFO was
changed when they appear in an action file. Rather than reporting the
action filename and line number, the generated message reports where the
action was invoked. For example, the GlusterFS message above was changed
to:</para>
<programlisting> ERROR: Invalid value (2000) for the GlusterFS Bricks argument /etc/shorewall/rules (line 45)</programlisting>
</section>
<section id="Embedded">
<title>Embedded Shell and Perl</title>
<para>Earlier versions of Shorewall offered <ulink
url="shorewall_extension_scripts.htm">extension scripts</ulink> to allow
users to extend Shorewall's functionality. Extension scripts were designed
to work under the limitations of the Bourne Shell. With the current
Perl-based compiler, <firstterm>Embedded scripts</firstterm> offer a
richer and more flexible extension capability.</para>
<para>While inline scripts may be written in either Shell or Perl, those
written in Perl have a lot more power. They may be used in all
configuration files except <filename>/etc/shorewall/params</filename> and
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
<para><emphasis role="bold">Note:</emphasis>In this section, '[' and ']'
are meta-characters which indicate that what they enclose is optional and
may be omitted.</para>
<para>Single line scripts take one of the following forms:</para>
<itemizedlist>
<listitem>
<para>[<emphasis role="bold">?</emphasis>]<emphasis
role="bold">PERL</emphasis> <<emphasis>perl
script</emphasis>></para>
</listitem>
<listitem>
<para>[<emphasis role="bold">?</emphasis>]<emphasis
role="bold">SHELL</emphasis> <<emphasis>shell
script</emphasis>></para>
</listitem>
</itemizedlist>
<note>
<para>The optional leading question mark (?) is allowed in Shorewall
4.5.5 and later.</para>
</note>
<para>Shell scripts run in a child shell process and their output is piped
back to the compiler which processes that output as if it were embedded at
the point of the script.</para>
<para>Example: The following entries in
<filename>/etc/shorewall/rules</filename> are equivalent:<programlisting>SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done</programlisting><programlisting>ACCEPT net fw tcp 22
ACCEPT loc fw tcp 22
ACCEPT dmz fw tcp 22</programlisting></para>
<para>Perl scripts run in the context of the compiler process using Perl's
eval() function. Perl scripts are implicitly prefixed by the
following:</para>
<programlisting>package Shorewall::User;
use Shorewall::Config ( qw/shorewall/ );</programlisting>
<para>To produce output that will be processed by the compiler as if it
were embedded in the file at the point of the script, pass that output to
the Shorewall::Config::shorewall() function. The Perl equivalent of the
above SHELL script would be:<programlisting>PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</programlisting>A
couple of more points should be mentioned:</para>
<orderedlist>
<listitem>
<para>Compile-time extension scripts are also implicitly prefixed by
"package Shorewall::User;".</para>
</listitem>
<listitem>
<para>A <emphasis role="bold">compile</emphasis> extension script is
supported. That script is run early in the compilation process and
allows users to load additional modules and to define data and
functions for use in subsequent embedded scripts and extension
scripts.</para>
</listitem>
<listitem>
<para><ulink url="ManualChains.html">Manual Chains</ulink> may be
added in the <emphasis role="bold">compile</emphasis> extension
script..</para>
</listitem>
</orderedlist>
<para>Multi-line scripts use one of the following forms:<programlisting>[<emphasis
role="bold">?</emphasis>]<emphasis role="bold">BEGIN SHELL</emphasis>
<<emphasis>shell script</emphasis>>
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
role="bold">SHELL</emphasis> ]</programlisting><programlisting>[<emphasis
role="bold">?</emphasis>]<emphasis role="bold">BEGIN PERL</emphasis> [<emphasis
role="bold">;</emphasis>]
<<emphasis>perl script</emphasis>>
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
role="bold">PERL</emphasis> ] [<emphasis role="bold">;</emphasis>]</programlisting><note>
<para>The optional leading question mark (?) is allowed in Shorewall
4.5.5 and later.</para>
</note></para>
</section>
<section id="dnsnames">
<title>Using DNS Names</title>
<caution>
<para>I personally recommend strongly against using DNS names in
Shorewall configuration files. If you use DNS names and you are called
out of bed at 2:00AM because Shorewall won't start as a result of DNS
problems then don't say that you were not forewarned.</para>
</caution>
<para>Host addresses in Shorewall configuration files may be specified as
either IP addresses or DNS Names.</para>
<para>DNS names in iptables rules aren't nearly as useful as they first
appear. When a DNS name appears in a rule, the iptables utility resolves
the name to one or more IP addresses and inserts those addresses into the
rule. So changes in the DNS->IP address relationship that occur after
the firewall has started have absolutely no effect on the firewall's rule
set.</para>
<para>For some sites, using DNS names is very risky. Here's an
example:</para>
<programlisting>teastep@ursa:~$ dig pop.gmail.com
; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com
;; global options: printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1774
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0
;; QUESTION SECTION:
;pop.gmail.com. IN A
;; ANSWER SECTION:
pop.gmail.com. <emphasis role="bold">300</emphasis> IN CNAME gmail-pop.l.google.com.
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.109
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.111</programlisting>
<para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
minutes later, the answer may change!</para>
<para>So this rule may work for five minutes then suddently stop
working:</para>
<programlisting>#ACTION SOURCE DEST PROTO DPORT
POP(ACCEPT) loc net:pop.gmail.com</programlisting>
<para>There are two options in <ulink
url="manpages/shorewall.conf.html">shorewall[6].conf(5)</ulink> that
affect the use of DNS names in Shorewall[6] config files:</para>
<itemizedlist>
<listitem>
<para>DEFER_DNS_RESOLUTION - When set to No, DNS names are resolved at
compile time; when set to Yes, DNS Names are resolved at
runtime.</para>
</listitem>
<listitem>
<para>AUTOMAKE - When set to Yes, <command>start</command>,
<command>restart</command> and <command>reload</command> only result
in compilation if one of the files on the CONFIG_PATH has changed
since the the last compilation.</para>
</listitem>
</itemizedlist>
<para>So by setting AUTOMAKE=Yes, and DEFER_DNS_RESOLUTION=No, compilation
will only take place at boot time if a change had been make to the config
but no <command>restart</command> or <command>reload</command> had taken
place. This is clearly spelled out in the shorewall.conf manpage. So with
these settings, so long as a 'reload' or 'restart' takes place after the
Shorewall configuration is changes, there should be no DNS-related
problems at boot time.</para>
<important>
<para>When DEFER_DNS_RESOLUTION=No and AUTOMAKE=Yes and a DNS change
makes it necessary to recompile an existing firewall script, the
<option>-c</option> option must be used with the
<command>reload</command> or <command>restart</command> command to force
recompilation.</para>
</important>
<para>If your firewall rules include DNS names then, even if
DEFER_DNS_RESOLUTION=No and AUTOMAKE=Yes:</para>
<itemizedlist>
<listitem>
<para>If your <filename>/etc/resolv.conf </filename>is wrong then your
firewall may not start.</para>
</listitem>
<listitem>
<para>If your <filename>/etc/nsswitch.conf</filename> is wrong then
your firewall may not start.</para>
</listitem>
<listitem>
<para>If your Name Server(s) is(are) down then your firewall may not
start.</para>
</listitem>
<listitem>
<para>If your startup scripts try to start your firewall before
starting your DNS server then your firewall may not start.</para>
</listitem>
<listitem>
<para>Factors totally outside your control (your ISP's router is down
for example), can prevent your firewall from starting.</para>
</listitem>
<listitem>
<para>You must bring up your network interfaces prior to starting your
firewall, or the firewall may not start.</para>
</listitem>
</itemizedlist>
<para>Each DNS name must be fully qualified and include a minimum of two
periods (although one may be trailing). This restriction is imposed by
Shorewall to insure backward compatibility with existing configuration
files.</para>
<example id="validdns">
<title>Valid DNS Names</title>
<itemizedlist>
<listitem>
<para>mail.shorewall.net</para>
</listitem>
<listitem>
<para>shorewall.net. (note the trailing period).</para>
</listitem>
</itemizedlist>
</example>
<example id="invaliddns">
<title>Invalid DNS Names</title>
<itemizedlist>
<listitem>
<para>mail (not fully qualified)</para>
</listitem>
<listitem>
<para>shorewall.net (only one period)</para>
</listitem>
</itemizedlist>
</example>
<para>DNS names may not be used as:</para>
<itemizedlist>
<listitem>
<para>The server address in a DNAT rule (/etc/shorewall/rules
file)</para>
</listitem>
<listitem>
<para>In the ADDRESS column of an entry in /etc/shorewall/masq.</para>
</listitem>
<listitem>
<para>In the <filename>/etc/shorewall/nat</filename> file.</para>
</listitem>
</itemizedlist>
<para>These restrictions are imposed by Netfilter and not by
Shorewall.</para>
</section>
<section id="Lists">
<title>Comma-separated Lists</title>
<para>Comma-separated lists are allowed in a number of contexts within the
configuration files. A comma separated list:</para>
<itemizedlist>
<listitem>
<para>Must not have any embedded white space.+<programlisting> Valid: routefilter,dhcp,arpfilter
Invalid: routefilter,    dhcp,    arpfilter</programlisting></para>
</listitem>
<listitem>
<para>If you use line continuation to break a comma-separated list,
the comma must be the last thing on the continued line before '\'
unless the continuation line has no leading white space.</para>
</listitem>
<listitem>
<para>Entries in a comma-separated list may appear in any
order.</para>
</listitem>
</itemizedlist>
</section>
<section id="Compliment">
<title>Complementing an Address, Subnet, Protocol or Port List</title>
<para>Where specifying an IP address, a subnet or an interface, you can
precede the item with <quote>!</quote> to specify the complement of the
item. For example, !192.168.1.4 means <quote>any host but
192.168.1.4</quote>. There must be no white space following the
<quote>!</quote>.</para>
<para>Similarly, in columns that specify an IP protocol, you can precede
the protocol name or number by "!". For example, !tcp means "any protocol
except tcp".</para>
<para>This also works with port lists, providing that the list contains 15
or fewer ports (where a <link linkend="Ranges">port range</link> counts as
two ports). For example !ssh,smtp means "any port except 22 and
25".</para>
<para>In Shorewall 4.4.19 and later, icmp type lists are supported but
complementing an icmp type list is <emphasis>not</emphasis> supported. You
may, however, complement a single icmp (icmp6) type.</para>
</section>
<section id="Exclusion">
<title>Exclusion Lists</title>
<para>Where a comma-separated list of addresses is accepted, an
<firstterm>exclusion list</firstterm> may also be included. An exclusion
list is a comma-separated list of addresses that begins with "!".</para>
<para>Example:</para>
<programlisting>!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
<para>The above list refers to "All addresses except 192.168.1.3,
192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
<para>Exclusion lists can also be added after a network address.</para>
<para>Example:</para>
<programlisting>192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
<para>The above list refers to "All addresses in 192.168.1.0-192.168.1.255
except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
</section>
<section id="IPRanges">
<title>IP Address Ranges</title>
<para>If you kernel and iptables have iprange match support, you may use
IP address ranges in Shorewall configuration file entries; IP address
ranges have the syntax <<emphasis>low IP
address</emphasis>>-<<emphasis>high IP address</emphasis>>.
Example: 192.168.1.5-192.168.1.12.</para>
<para>To see if your kernel and iptables have the required support, use
the <command>shorewall show capabilities</command> command:</para>
<programlisting>>~ <command>shorewall show capabilities</command>
...
Shorewall has detected the following iptables/netfilter capabilities:
NAT: Available
Packet Mangling: Available
Multi-port Match: Available
Connection Tracking Match: Available
Packet Type Match: Not available
Policy Match: Available
Physdev Match: Available
<emphasis role="bold">IP range Match: Available <--------------</emphasis></programlisting>
</section>
<section id="Ports">
<title>Protocol Number/Names and Port Numbers/Service Names</title>
<para>Unless otherwise specified, when giving a protocol number you can
use either an integer or a protocol name from
<filename>/etc/protocols</filename>. Similarly, when giving a port number
you can use either an integer or a service name from
<filename>/etc/services</filename>.<note>
<para>The rules compiler translates protocol names to protocol numbers
and service names to port numbers itself.</para>
</note></para>
<para>Also, unless otherwise documented, a protocol number/name can be
preceded by '!' to specify "All protocols except this one" (e.g.,
"!tcp").</para>
</section>
<section id="Ranges">
<title>Port Ranges</title>
<para>If you need to specify a range of ports, the proper syntax is
<low port number>:<high port number>. For example, if you want
to forward the range of tcp ports 4000 through 4100 to local host
192.168.1.3, the entry in /etc/shorewall/rules is:</para>
<programlisting>#ACTION SOURCE DESTINATION PROTO DPORT
DNAT net loc:192.168.1.3 tcp <emphasis role="bold">4000:4100</emphasis></programlisting>
<para>If you omit the low port number, a value of zero is assumed; if you
omit the high port number, a value of 65535 is assumed.</para>
<para>Also, unless otherwise documented, a port range can be preceded by
'!' to specify "All ports except those in this range" (e.g.,
"!4000:4100").</para>
<para>Beginning with Shorewall 5.0.14, a hyphen ("-") may also be used to
separate the two port numbers; when using service names, the colon must
still be used.</para>
<programlisting>#ACTION SOURCE DESTINATION PROTO DPORT
DNAT net loc:192.168.1.3 tcp <emphasis role="bold">4000-4100</emphasis></programlisting>
</section>
<section id="Portlists">
<title>Port Lists</title>
<para>In most cases where a port or port range may appear, a
comma-separated list of ports or port ranges may also be entered.
Shorewall requires the Netfilter <emphasis
role="bold">multiport</emphasis> match capability if ports lists are used
(see the output of "<emphasis role="bold">shorewall show
capabilities</emphasis>").</para>
<para>Also, unless otherwise documented, a port list can be preceded by
'!' to specify "All ports except these" (e.g., "!80,443").</para>
<para>Prior to Shorewall 4.4.4, port lists appearing in the <ulink
url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
(5) file may specify no more than 15 ports; port ranges appearing in a
list count as two ports each.</para>
</section>
<section id="ICMP">
<title>ICMP and ICMP6 Types and Codes</title>
<para>When dealing with ICMP, the DEST PORT specifies the type or type and
code. You may specify the numeric type, the numeric type and code
separated by a slash (e.g., 3/4) or you may use a type name.</para>
<para>Type names for IPv4 and their corresponding type or type/code
are:</para>
<programlisting>echo-reply' => 0
destination-unreachable => 3
network-unreachable => 3/0
host-unreachable => 3/1
protocol-unreachable => 3/2
port-unreachable => 3/3
fragmentation-needed => 3/4
source-route-failed => 3/5
network-unknown => 3/6
host-unknown => 3/7
network-prohibited => 3/9
host-prohibited => 3/10
TOS-network-unreachable => 3/11
TOS-host-unreachable => 3/12
communication-prohibited => 3/13
host-precedence-violation => 3/14
precedence-cutoff => 3/15
source-quench => 4
redirect => 5
network-redirect => 5/0
host-redirect => 5/1
TOS-network-redirect => 5/2
TOS-host-redirect => 5/3
echo-request => 8
router-advertisement => 9
router-solicitation => 10
time-exceeded => 11
ttl-zero-during-transit => 11/0
ttl-zero-during-reassembly=> 11/1
parameter-problem => 12
ip-header-bad => 12/0
required-option-missing => 12/1
timestamp-request => 13
timestamp-reply => 14
address-mask-request => 17
address-mask-reply => 18</programlisting>
<para>Type names for IPv6 and their corresponding type or type/code
are:</para>
<programlisting>destination-unreachable => 1
no-route' => 1/0
communication-prohibited => 1/1
address-unreachable' => 1/3
port-unreachable' => 1/4
packet-too-big => 2
time-exceeded' => 3
ttl-exceeded' => 3
ttl-zero-during-transit => 3/0
ttl-zero-during-reassembly => 3/1
parameter-problem => 4
bad-header => 4/0
unknown-header-type => 4/1
unknown-option => 4/2
echo-request => 128
echo-reply => 129
router-solicitation => 133
router-advertisement => 134
neighbour-solicitation => 135
neighbour-advertisement => 136
redirect => 137</programlisting>
<para>Shorewall 4.4 does not accept lists if ICMP (ICMP6) types prior to
Shorewall 4.4.19.</para>
</section>
<section id="MAC">
<title>Using MAC Addresses</title>
<para>Media Access Control (MAC) addresses can be used to specify packet
source in several of the configuration files. In order to control traffic
to/from a host by its MAC address, the host must be on the same network as
the firewall.</para>
<para>To use this feature, your kernel must have MAC Address Match support
(CONFIG_IP_NF_MATCH_MAC) included.</para>
<para>MAC addresses are 48 bits wide and each Ethernet Controller has a
unique MAC address.</para>
<para>In GNU/Linux, MAC addresses are usually written as a series of 6 hex
numbers separated by colons.</para>
<example id="mac">
<title>MAC Address of an Ethernet Controller</title>
<programlisting> gateway:~ # <command>ip link ls dev eth0</command>
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc htb qlen 1000
link/ether <emphasis role="bold">02:00:08:E3:FA:55</emphasis> brd ff:ff:ff:ff:ff:ff
gateway:~ #</programlisting>
</example>
<para>Because Shorewall uses colons as a separator for address fields,
Shorewall requires MAC addresses to be written in another way. In
Shorewall, MAC addresses begin with a tilde (<quote>~</quote>) and consist
of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in
the example above would be written <emphasis
role="bold">~02-00-08-E3-FA-55</emphasis>.</para>
<note>
<para>It is not necessary to use the special Shorewall notation in the
<filename><ulink
url="MAC_Validation.html">/etc/shorewall/maclist</ulink></filename>
file.</para>
</note>
</section>
<section id="RateLimit">
<title>Rate Limiting (Rate and Burst)</title>
<para>Shorewall supports rate limiting in a number of ways. When
specifying a rate limit, both a <firstterm>rate</firstterm> and a
<firstterm>burst</firstterm> value are given.</para>
<para>Example from <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>
<simplelist>
<member>LOGLIMIT=10/minute:5</member>
</simplelist>
<para>For each logging rule, the first time the rule is reached, the
packet will be logged; in fact, since the burst is 5, the first five
packets will be logged. After this, it will be 6 seconds (1 minute divided
by the rate of 10) before a message will be logged from the rule,
regardless of how many packets reach it. Also, every 6 seconds which
passes, one of the bursts will be regained; if no packets hit the rule for
30 seconds, the burst will be fully recharged; back where we
started.</para>
<para>Shorewall also supports per-IP rate limiting.</para>
<para>Another example from <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>
<simplelist>
<member>LOGLIMIT="s:5/min:5"</member>
</simplelist>
<para>Here, the leading "s:" indicates that logging is to be limited by
source IP address ("d:" would indicate limiting by destination IP
address).</para>
<para>"s:" is followed by the rate (5 messages per minute) and the burst
(5).</para>
<para>The rate and limit arguments have the same meaning as in the example
above.</para>
</section>
<section id="TIME">
<title>TIME Columns</title>
<para>Several of the files include a TIME colum that allows you to specify
times when the rule is to be applied. Contents of this column is a list of
<replaceable>timeelement</replaceable>s separated by apersands
(&).</para>
<para>Each <replaceable>timeelement</replaceable> is one of the
following:</para>
<variablelist>
<varlistentry>
<term>timestart=<replaceable>hh</replaceable>:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]</term>
<listitem>
<para>Defines the starting time of day.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>timestop=<replaceable>hh</replaceable>:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]</term>
<listitem>
<para>Defines the ending time of day.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>contiguous</term>
<listitem>
<para>Added in Shoreawll 5.0.12. When <emphasis
role="bold">timestop</emphasis> is smaller than <emphasis
role="bold">timestart</emphasis> value, match this as a single time
period instead of distinct intervals. See the Examples below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>utc</term>
<listitem>
<para>Times are expressed in Greenwich Mean Time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>localtz</term>
<listitem>
<para>Deprecated by the Netfilter team in favor of <emphasis
role="bold">kerneltz</emphasis>. Times are expressed in Local Civil
Time (default).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>kerneltz</term>
<listitem>
<para>Added in Shorewall 4.5.2. Times are expressed in Local Kernel
Time (requires iptables 1.4.12 or later).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>weekdays=ddd[,ddd]...</term>
<listitem>
<para>where <replaceable>ddd</replaceable> is one of
<option>Mon</option>, <option>Tue</option>, <option>Wed</option>,
<option>Thu</option>, <option>Fri</option>, <option>Sat</option> or
<option>Sun</option></para>
</listitem>
</varlistentry>
<varlistentry>
<term>monthdays=dd[,dd],...</term>
<listitem>
<para>where <replaceable>dd</replaceable> is an ordinal day of the
month</para>
</listitem>
</varlistentry>
<varlistentry>
<term>datestart=<replaceable>yyyy</replaceable>[-<replaceable>mm</replaceable>[-<replaceable>dd</replaceable>[<option>T</option><replaceable>hh</replaceable>[:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]]]]]</term>
<listitem>
<para>Defines the starting date and time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>datestop=<replaceable>yyyy</replaceable>[-<replaceable>mm</replaceable>[-<replaceable>dd</replaceable>[<option>T</option><replaceable>hh</replaceable>[:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]]]]]</term>
<listitem>
<para>Defines the ending date and time.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Examples:</para>
<variablelist>
<varlistentry>
<term>To match on weekends, use:</term>
<listitem>
<para/>
<para>weekdays=Sat,Sun</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Or, to match (once) on a national holiday block:</term>
<listitem>
<para/>
<para>datestart=2016-12-24&datestop=2016-12-27</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Since the stop time is actually inclusive, you would need the
following stop time to not match the first second of the new
day:</term>
<listitem>
<para/>
<para>datestart=2016-12-24T17:00&datestop=2016-12-27T23:59:59</para>
</listitem>
</varlistentry>
<varlistentry>
<term>During Lunch Hour</term>
<listitem>
<para/>
</listitem>
</varlistentry>
<varlistentry>
<term>The fourth Friday in the month:</term>
<listitem>
<para/>
<para>weekdays=Fri&monthdays=22,23,24,25,26,27,28</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Matching across days might not do what is expected. For
instance,</term>
<listitem>
<para/>
<para>weekdays=Mon&timestart=23:00&timestop=01:00</para>
<para>Will match Monday, for one hour from midnight to 1 a.m., and
then again for another hour from 23:00 onwards. If this is unwanted,
e.g. if you would like 'match for two hours from Montay 23:00
onwards' you need to also specify the <emphasis
role="bold">contiguous</emphasis> option in the example
above.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="Switches">
<title>Switches</title>
<para>There are times when you would like to enable or disable one or more
rules in the configuration without having to do a <command>shorewall
reload</command> or <command>shorewall restart</command>. This may be
accomplished using the SWITCH column in <ulink
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5) or <ulink
url="manpages6/shorewall6-rules.html">shorewall6-rules</ulink> (5). Using
this column requires that your kernel and iptables include
<firstterm>Condition Match Support</firstterm> and you must be running
Shorewall 4.4.24 or later. See the output of <command>shorewall show
capabilities</command> and <command>shorewall version</command> to
determine if you can use this feature.</para>
<para>The SWITCH column contains the name of a
<firstterm>switch.</firstterm> Each switch is initially in the <emphasis
role="bold">off</emphasis> position. You can turn on the switch named
<emphasis>switch1</emphasis> by:</para>
<simplelist>
<member><command>echo 1 >
/proc/net/nf_condition/switch1</command></member>
</simplelist>
<para>You can turn it off again by:</para>
<simplelist>
<member><command>echo 0 >
/proc/net/nf_condition/switch1</command></member>
</simplelist>
<para>If you simply include the switch name in the SWITCH column, then the
rule is enabled only when the switch is <emphasis
role="bold">on</emphasis>. If you precede the switch name with ! (e.g.,
!switch1), then the rule is enabled only when the switch is <emphasis
role="bold">off</emphasis>. Switch settings are retained over
<command>shorewall restart</command>.</para>
<para>Shorewall requires that switch names:</para>
<itemizedlist>
<listitem>
<para>begin with a letter and be composed of letters, digits,
underscore ('_') or hyphen ('-'); and</para>
</listitem>
<listitem>
<para>be 30 characters or less in length.</para>
</listitem>
</itemizedlist>
<para>Multiple rules can be controlled by the same switch.</para>
<para>Example:</para>
<blockquote>
<para>Forward port 80 to dmz host $BACKUP if switch 'primary_down' is
on.</para>
<programlisting>#ACTION SOURCE DEST PROTO DPORT SPORT ORIGDEST RATE USER MARK CONNLIMIT TIME HEADERS SWITCH
DNAT net dmz:$BACKUP tcp 80 - - - - - - - - <emphasis
role="bold">primary_down</emphasis> </programlisting>
</blockquote>
</section>
<section id="Logical">
<title>Logical Interface Names</title>
<para>When dealing with a complex configuration, it is often awkward to
use physical interface names in the Shorewall configuration.</para>
<itemizedlist>
<listitem>
<para>You need to remember which interface is which.</para>
</listitem>
<listitem>
<para>If you move the configuration to another firewall, the interface
names might not be the same.</para>
</listitem>
</itemizedlist>
<para>Beginning with Shorewall 4.4.4, you can use logical interface names
which are mapped to the actual interface using the
<option>physical</option> option in <ulink
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink>
(5).</para>
<para>Here is an example:</para>
<programlisting>#ZONE INTERFACE OPTIONS
net <emphasis role="bold">COM_IF </emphasis> dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,<emphasis
role="bold">physical=eth0</emphasis>
net <emphasis role="bold">EXT_IF</emphasis> dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,<emphasis
role="bold">physical=eth2</emphasis>
loc <emphasis role="bold">INT_IF </emphasis> dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,<emphasis
role="bold">physical=eth1</emphasis>
dmz <emphasis role="bold">VPS_IF </emphasis> logmartians=1,routefilter=0,routeback,<emphasis
role="bold">physical=venet0</emphasis>
loc <emphasis role="bold">TUN_IF</emphasis> <emphasis role="bold">physical=tun+</emphasis></programlisting>
<para>In this example, COM_IF is a logical interface name that refers to
Ethernet interface <filename class="devicefile">eth0</filename>, EXT_IF is
a logical interface name that refers to Ethernet interface <filename
class="devicefile">eth2</filename>, and so on.</para>
<para>Here are a couple of more files from the same configuration:</para>
<para><ulink url="manpages/shorewall-masq.html">shorewall-masq</ulink>
(5):</para>
<programlisting>#INTERFACE SOURCE ADDRESS
COMMENT Masquerade Local Network
<emphasis role="bold">COM_IF</emphasis> 0.0.0.0/0
<emphasis role="bold">EXT_IF </emphasis> !206.124.146.0/24 206.124.146.179:persistent</programlisting>
<para><ulink
url="manpages/shorewall-providers.html">shorewall-providers</ulink>
(5)</para>
<programlisting>#NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
Avvanta 1 0x10000 main <emphasis role="bold">EXT_IF </emphasis> 206.124.146.254 loose,fallback <emphasis
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis>
Comcast 2 0x20000 main <emphasis role="bold">COM_IF</emphasis> detect balance <emphasis
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis></programlisting>
<para>Note in particular that Shorewall translates TUN_IF to <filename
class="devicefile">tun*</filename> in the COPY column.</para>
</section>
<section>
<title>Optional and Required Interfaces</title>
<para>Normally, Shorewall assumes that all interfaces described in <ulink
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5)
are going to be in an up and usable state when Shorewall starts or
restarts. You can alter that assumption by specifying the <emphasis
role="bold">optional</emphasis> option in the OPTIONS column.</para>
<para>When an interface is marked as optional, Shorewall will determine
the interface state at <command>start</command>, <command>reload</command>
and <command>restart</command> and adjust its configuration
accordingly.</para>
<itemizedlist>
<listitem>
<para>The <emphasis role="bold">arp_filter</emphasis>, <emphasis
role="bold">arp_ignore</emphasis>, <emphasis
role="bold">routefilter</emphasis>, <emphasis
role="bold">logmartians</emphasis>, <emphasis
role="bold">proxyarp</emphasis> and <emphasis
role="bold">sourceroute</emphasis> options are not enforced when the
interface is down, thus avoiding an error message such
as:<programlisting>WARNING: Cannot set Martian logging on ppp0</programlisting></para>
</listitem>
<listitem>
<para>If the interface is associated with a provider in <ulink
url="manpages/shorewall-providers.html">shorewall-providers</ulink>
(5), <command>start</command>, <command>reload</command> and
<command>restart</command> will not fail if the interface is not
usable.</para>
</listitem>
<listitem>
<para>When DETECT_DNAT_IPADDRS=Yes in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5), DNAT
rules in shorewall-rules (5) involving the interface will be omitted
when the interface does not have an IP address.</para>
</listitem>
<listitem>
<para>If <emphasis role="bold">detect</emphasis> is specified in the
ADDRESS column of an entry in <ulink
url="manpages/shorewall-masq.html">shorewall-masq</ulink> (5) then the
firewall still starts if the optional interface in the INTERFACE
column does not have an IP address.</para>
</listitem>
</itemizedlist>
<para>If you don't want the firewall to start unless a given interface is
usable, then specify <emphasis role="bold">required</emphasis> in the
OPTIONS column of <ulink
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5).
If you have installed and configured the Shorewall-init package, then when
the interface becomes available, an automatic attempt will be made to
start the firewall.</para>
</section>
<section id="Levels">
<title>Shorewall Configurations</title>
<para>Shorewall allows you to have configuration directories other than
<filename class="directory">/etc/shorewall</filename>. The shorewall
<command>check</command>, <command>start</command>,
<command>reload</command> and <command>restart</command> commands allow
you to specify an alternate configuration directory and Shorewall will use
the files in the alternate directory rather than the corresponding files
in /etc/shorewall. The alternate directory need not contain a complete
configuration; those files not in the alternate directory will be read
from <filename class="directory">/etc/shorewall</filename>.<important>
<para>Shorewall requires that the file
<filename>/etc/shorewall/shorewall.conf</filename> to always exist.
Certain global settings are always obtained from that file. If you
create alternative configuration directories, do not remove
/etc/shorewall/shorewall.conf.</para>
</important></para>
<para>This facility permits you to easily create a test or temporary
configuration by</para>
<orderedlist>
<listitem>
<para>copying the files that need modification from /etc/shorewall to
a separate directory;</para>
</listitem>
<listitem>
<para>modify those files in the separate directory; and</para>
</listitem>
<listitem>
<para>specifying the separate directory in a <command>shorewall
start</command>, <command>shorewall reload</command> or
<command>shorewall restart</command> command (e.g., <command>shorewall
restart /etc/testconfig</command> )</para>
</listitem>
</orderedlist>
</section>
<section id="Save">
<title>Saved Configurations</title>
<para>Shorewall allows you to <firstterm>save</firstterm> the
currently-running configuration in a form that permits it to be
re-installed quickly. When you save the configuration using the
<command>shorewall save</command> command, the running configuration is
saved in a file in the <filename
class="directory">/var/lib/shorewall</filename> directory. The default
name of that file is <filename>/var/lib/shorewall/restore</filename> but
you can specify a different name as part of the command. For example, the
command <command>shorewall save standard</command> will save the running
configuration in <filename>/var/lib/shorewall/standard</filename>. A saved
configuration is re-installed using the <command>shorewall
restore</command> command. Again, that command normally will restore the
configuration saved in <filename>/var/lib/shorewall/restore</filename> but
as with the <command>save</command> command, you can specify a different
file name in the command. For example, <command>shorewall restore
standard</command> will re-install the configuration saved in
<filename>/var/lib/shorewall/standard</filename>. By permitting you to
save different configurations under different names, Shorewall provides a
means for quickly switching between these different saved
configurations.</para>
<para>As mentioned above, the default configuration is called 'restore'
but like most things in Shorewall, that default can be changed. The
default name is specified using the <emphasis
role="bold">RESTOREFILE</emphasis> option in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
<warning>
<para>The default saved configuration is used by Shorewall in a number
of ways besides in the <command>restore</command> command; to avoid
surprises, I recommend that you read the <ulink
url="starting_and_stopping_shorewall.htm#Saved">Shorewall Operations
documentation section about saved configurations</ulink> before creating
one.</para>
</warning>
</section>
</article>
|