From 463206a3eb2b146a36a082a61bcdadec838fbbbf Mon Sep 17 00:00:00 2001 From: Tom Eastep Date: Sat, 22 Aug 2015 13:53:25 -0700 Subject: [PATCH] Add Shorewall-5 Article Signed-off-by: Tom Eastep --- docs/Shorewall-5.xml | 409 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 docs/Shorewall-5.xml diff --git a/docs/Shorewall-5.xml b/docs/Shorewall-5.xml new file mode 100644 index 000000000..7e03fd6b3 --- /dev/null +++ b/docs/Shorewall-5.xml @@ -0,0 +1,409 @@ + + +
+ + + + Shorewall 5 + + + + Tom + + Eastep + + + + + + + 2015 + + Thomas M. Eastep + + + + 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 + GNU Free Documentation + License. + + + +
+ Introduction + + There are currently two principle groups of changes that distinguish + Shorewall 5 from Shorewall 4: + + + + Cruft Removal - over the years, as new ways to accomplish + various tasks are added to Shorewall, support for the old way of doing + things has generally been retained but deprecated. Shorewall 5 drops + support for those deprecated features. + + + + Changes to CLI commands - In order to make command names more + accurately reflect what the associated commands do, a number of + commands have been renamed or the function that they perform has been + changed. + + + + Each of these groups is described in more detail in the sections + that follow. +
+ +
+ Cruft Removal + + Removal of superseded features makes the code cleaner and easier to + extend while also reducing compilation and execution time. The following + subsections detail the features that are no longer supported in Shorewall + 5. + +
+ Scripts Compiled with Shorewall 4.4.7 or Earlier + + Shorewall 5 cannot correctly run scripts compiled with Shorewall + 4.4.7 or earlier releases. Such scripts must be recompiled with 4.4.8 or + later prior to upgrading to Shorewall 5. +
+ +
+ Workarounds + + Over the years, a number of workarounds have been added to + Shorewall to work around defects in other products. In current + distributions, those defects have been corrected and in 4.6.11, a + WORKAROUNDS configuration option was added to disable those workarounds. + In Shorewall 5, the WORKAROUNDS setting is still available in the + shorewall[6].conf files but: + + + + Its default setting has been changed to No. + + + + All workarounds for old distributions have been + eliminated. + + +
+ +
+ Removal of Configuration Options + + A number of configuration options have been eliminated in + Shorewall 5. The following options have been eliminated and the + functionality that they enabled is been removed: + + + + EXPORTPARAMS + + + + IPSECFILE + + + + LEGACY_FASTSTART + + + + A compilation warning is issued when any of these options are + encountered in the .conf file, and the shorewall[6] + update command will remove them from the configuration + file. + + These options have been eliminated because they have been + superseded by newer options. + + + + LOGRATE and LOGBURST (superseded by LOGLIMIT) + + + + WIDE_TC_MARKS (superseded by TC_BITS) + + + + HIGH_ROUTE_MARKS (superseded by PROVIDER_OFFSET) + + + + BLACKLISTNEWONLY (superseded by BLACKLIST) + + + + A fatal compilation error is emitted if any of these options are + present in the .conf file, and the shorewall[6] + update command will replace these options with equivalent + setting for the options that supersede them. +
+ +
+ Obsolete Configuration Files + + Support has been removed for the 'blacklist', 'tcrules', + 'routestopped', 'notrack' and 'tos' files. + + The and options of the + update command are still available to convert the + 'tcrules' file to the equivalent 'mangle' file and to convert the + 'blacklist' file into an equivalent 'blrules' file. + + As in Shorewall 4.6.12, the option is + available to convert the 'routestopped' file into the equivalent + 'stoppedrules' file and the option is available to + convert a 'notrack' file to the equivalent 'conntrack' file. + + No update option is available to update the 'tos' file. Its + entries must be manually converted to TOS rules in the 'mangle' + file. +
+ +
+ Macro and Action Formats + + Originally, macro and action files had formats that were different + from that of the rules file, + + Format-1 action files had the following columns: + + + + TARGET + + + + SOURCE + + + + DEST + + + + PROTO + + + + DEST PORT(S) + + + + SOURCE PORT(S) + + + + RATE + + + + USER/GROUP + + + + MARK + + + + Format-1 macro files were similar but did not support the MARK + column. + + Format-2 macro and action files have these columns: + + + + TARGET + + + + SOURCE + + + + DEST + + + + PROTO + + + + DEST PORT(S) + + + + SOURCE PORT(S) + + + + ORIGINAL DEST + + + + RATE + + + + USER/GROUP + + + + MARK + + + + CONNLIMIT + + + + TIME + + + + HEADERS (Only valid for IPv6) + + + + SWITCH + + + + HELPER + + + + Notice that the first five columns of both sets are the + same. + + In Shorewall 5, support for format-1 macros and actions has been + dropped and all macros and actions will be processed as if ?FORMAT 2 + were included before the first entry. Given that the vast majority of + actions and macros only use the first five columns, this change will be + of no concern to most users, but will cause compilation errors if + columns beyold the fifth one are populated. +
+ +
+ COMMENT, FORMAT and SECTION Lines + + COMMENT, FORMAT and SECTION Lines now require the leading question + mark ("?"). In earlier releases, the question mark was optional. The + shorewall[6] update -D command will insert the + question marks for you. +
+
+ +
+ CLI Command Changes + + A number of commands have been renamed and/or now perform a + different function. + +
+ restart + + The restart command now does a true restart and + is equivalent to a stop followed by a + start. +
+ +
+ load + + The function performed by the Shorewall-4 load + command is now performed by the remote_start + command. +
+ +
+ reload + + In Shorewall 5, the reload command now performs + the same function as the restart command did in + Shorewall 4. The action taken by the Shorewall-4 + reload command is now performed by the + remote_restart command. + + For those that can't get used to the idea of using + reload in place of restart, a + LEGACY_RESTART option has been added to shorewall[6].conf. The option + defaults to No but if set to Yes, then the restart + command does what it did in earlier releases. +
+
+ +
+ Upgrading to Shorewall 5 + + It is stongly recommended that you first upgrade your installation + to a 4.6 release that supports the option to the + update command; 4.6.12 or later is preferred. + + Once you are on that release, execute the shorewall update + -A command (and shorewall6 update -A if you + also have Shorewall6). + + If you have a non-empty 'tos' file, it is also suggested that you + manually convert its entries to equivalent TOS entries in the 'mangle' + file. + + Finally, add ?FORMAT 2 to each of your macro and action files and be + sure that the check command does not produce errors -- if it does, you can + shuffle the columns around to make them work on both Shorewall 4 and + Shorewall 5. + + These steps can also be taken after you upgrade, but your firewall + likely won't start or work correctly until you do. +
+ +
+ Potential Upgrade Issues + + There are several potential problems with using the update + -A command. These are described in the following + sections. + +
+ Sparse /etc/shorewall[6] Directory + + If you run a Debian-based distribution or another once that does + not fully populate /etc/shorewall[6] and you include a fully-populated + directory in your CONFIG_PATH, then an additional step is required + before running update -A. You must copy skeleton + 'blrules', 'mangle' and 'conntrack' files into /etc/shorewall[6] or + update -A will update the files in the fully + populated directory rather than creating new files in + /etc/shorewall[6]. +
+ +
+ Old Multi-ISP Configurations + + If you have an old Multi-ISP configuration that does not include + USE_DEFAULT_RT in shorewall.conf, then you need to add USE_DEFAULT_RT=No + in that file prior to running update -A. Otherwise, + the update command will fail with the error: + + + ERROR: The COPY column must be empty when + USE_DEFAULT_RT=Yes + + + If you receive this error, modify the setting of USE_DEFAULT_RT to + No and rerun the command. +
+
+