Shorewall 3.3.6 Note to users upgrading from Shorewall 3.0 or 3.2 Most problems associated with upgrades come from two causes: - The user didn't read and follow the migration considerations in these release notes. - The user mis-handled the /etc/shorewall/shorewall.conf file during upgrade. Shorewall is designed to allow the default behavior of the product to evolve over time. To make this possible, the design assumes that you will not replace your current shorewall.conf file during upgrades. If you feel absolutely compelled to have the latest comments and options in your shorewall.conf then you must proceed carefully. While you are at it, if you have a file named /etc/shorewall/rfc1918 then please check that file. If it has addresses listed that are NOT in one of these three ranges, then please rename the file to /etc/shorewall/rfc1918.old. 10.0.0.0 - 10.255.255.255 172.16.0.0 - 172.31.255.255 192.168.0.0 - 192.168.255.255 If you have a file named /etc/shorewall/modules, please remove it. The default modules file is now located in /usr/share/shorewall/ (see the "Migration Considerations" below). Please see the "Migration Considerations" below for additional upgrade information. Problems Corrected in 3.3.6 1) Handling of saved ipsets in /etc/shorewall/ipsets was broken when used on a system running Shorewall Lite. If there was a file named 'ipsets' on the CONFIG_PATH when the firewall script was compiled, then the compiled script attempted to restore the ipsets from that file (which may not have existed on the firewall system). 2) Previously, "shorewall safe-[re]start" was badly broken. This breakage had been corrected. Other Changes in 3.3.6 1) Now that the manpages are in place, /etc/shorewall/Documentation has been removed. Command-specific help has also been removed since it duplicates information in the man pages. 2) Prior to this release, on firewall systems with Shorewall Lite installed, the local modules file is used to determine which kernel modules to load. Beginning with this release, if there is a 'modules' file in the CONFIG_PATH when the firewall script is compiled (other than /usr/share/shorewall/modules), then that file will be copied into the compiled script and used on the firewall system. 3) Shorewall now uses tc fwmark filters to classify packets for traffic shaping when the DEVICE isn't an interface described in /etc/shorewall/interfaces. This is in preparation for the upcoming change to the way that --physdev-out works in iptables/Netfilter. 4) If your kernel and iptables have extended multiport support, then Shorewall will use that support for the destination port when generating rules from entries in the /etc/shorewall/tcrules file. 5) The 'safe-start' and 'safe-restart' command have been improved. Both now accept an optional directory name; if supplied, Shorewall will look first in that directory for configuration files. The commands have also been enhanced to only restore the configuration once in the event of a failure. Previously, if there was a current 'safe' command in effect, then that configuration would be restored on a failure and then the last-running configuration would be restored. 6) The 'try' command has been reimplemented with new semantics. If Shorewall is started then the firewall state is saved to a temporary saved configuration (/var/lib/shorewall/.try). Next, if Shorewall is currently started then a restart command is issued; otherwise, a start command is performed. if an error occurs during the compliation phase of the restart or start, the command terminates without changing the Shorewall state. If an error occurs during the restart phase, then a 'shorewall restore' is performed using the saved configuration. If an error occurs during the start phase, then Shorewall is cleared. If the start/restart succeeds and a timeout is specified then a 'clear' or 'restore' is performed after timeout seconds. 7) The syntax of the 'export' command has been made slightly friendlier. The old syntax: export [user@]system:[] It is now: export [user@]system[:] In other words, if you don't need to specify , you may omit the colon (":") following the system name. The old syntax is still accepted -- that is, you can still type: export firewall2: which is equivalent to export firewall2 8) Shorewall commands may be speeded up slightly by using a 'capabilities' file. The 'capabilities' file was originally designed for use with Shorewall Lite and records the iptables/Netfilter features available on the target system. To generate a capabilities file, execute the following command as root: shorewall show -f capabilities > /etc/shorewall/capabilities When you install a new kernel and/or iptables, be sure to generate a new file. Migration Considerations: 1) Shorewall supports the notion of "default actions". A default action defines a set of rules that are applied before a policy is enforced. Default actions accomplish two goals: a) Relieve log congestion. Default actions typically include rules to silently drop or reject traffic that would otherwise be logged when the policy is enforced. b) Insure correct operation. Default actions can also avoid common pitfalls like dropping connection requests on TCP port 113. If these connections are dropped (rather than rejected) then you may encounter problems connecting to internet services that utilize the AUTH protocol of client authentication. In prior Shorewall versions, default actions (action.Drop and action.Reject) were defined for DROP and REJECT policies in /usr/share/shorewall/actions.std. These could be overridden in /etc/shorewall/actions. This approach has two drawbacks: a) All DROP policies must use the same default action and all REJECT policies must use the same default action. b) Now that we have modularized action processing (see the New Features section below), we need a way to define default rules for a policy that does not involve actions. If you have not overridden the defaults using entries in /etc/shorewall/actions then you need make no changes to migrate to Shorewall version 3.3. Otherwise, please see item 3) in the New Features below. 2) The 'Limit' action is now a builtin. If you have 'Limit' listed in /etc/shorewall/actions, remove the entry. Also remove the files /etc/shorewall/action.Limit and/or /etc/shorewall/Limit if you have them. 3) The 'shorewall try' command has been eliminated. The syntax of 'try' was: shorewall try [ ] A better way to accomplish the same thing is: shorewall save #Do this only once before you start testing shorewall restart [ && sleep && shorewall restore ] --- fix problems --- shorewall restart [ && sleep && shorewall restore ] --- fix problems --- ... shorewall save #Do this only once after you have installed #the new configuration New Features: 1) In order to accomodate small embedded applications, Shorewall 3.3 is now modularized. In addition to the base files, there are loadable "libraries" that may be included or omitted from an embedded system as required. Loadable Shorewall libraries reside in /usr/share/shorewall/ and have names that begin with "lib.". The following libraries are included in Shorewall 3.3: - lib.accounting. Must be available if you include entries in /etc/shorewall/accounting. - lib.actions. Must be available if you do not specify USE_ACTIONS=No in /etc/shorewall/shorewall.conf. - lib.base. The base Shorewall library required by all programs, including compiled firewall scripts. - lib.cli. Library containing the code common to /sbin/shorewall, /sbin/shorewall-lite. - lib.config. Library containing the code that is common to /usr/share/shorewall/compiler and /usr/share/shorewall/firewall. - lib.dynamiczones. Must be available if you specify DYNAMIC_ZONES=Yes in shorewall.conf. - lib.maclist. Must be available if you specify the 'maclist' option in /etc/shorewall/interfaces or /etc/shorewall/hosts. - lib.nat. Must be available if you have entries in /etc/shorewall/masq, /etc/shorewall/nat or /etc/shorewall/netmap or if you use DNAT or REDIRECT rules. - lib.providers. Must be available if you have entries in /etc/shorewall/providers. - lib.proxyarp. Must be available if you have entries in /etc/shorewall/proxyarp or if you specify the 'proxyarp' option in /etc/shorewall/interfaces. - lib.tc. Must be available if you have entries in /etc/shorewall/tcdevices and /etc/shorewall/tcclasses. - lib.tcrules. Must be available if you have entries in /etc/shorewall/tcrules. - lib.tunnels. Must be available if you have entries in /etc/shorewall/tunnels. Embedded applications can further decrease the size of the Shorewall footprint by: - Omitting the macro files. - Omitting all unused extension scripts. 2) As hinted in the previous bullet, there is a new USE_ACTIONS option in /etc/shorewall/shorewall.conf. Shorewall actions can be very powerful but they also require a lot of code to implement. Embedded applications can omit that code by setting USE_ACTIONS=No. Shorewall will ignore all action-related files including /usr/share/shorewall/actions.std and /etc/shorewall/actions. Builtin actions will still be available for use in rules and macros. The 'Limit' action has been converted to a builtin so that Limit is available even when USE_ACTIONS=No. See the next item for more information. 3) Prior to Shorewall 3.3, default actions were specified in /usr/share/shorewall/actions.std or in /etc/shorewall/actions. This approach has two drawbacks: a) All DROP policies must use the same default action and all REJECT policies must use the same default action. b) Now that we have modularized action processing (see the New Features section below), we need a way to define default rules for a policy that does not involve actions. The solution is two-fold: - Four new options have been added to the /etc/shorewall/shorewall.conf file that allow specifying the default action for DROP, REJECT, ACCEPT and QUEUE. The options are DROP_DEFAULT, REJECT_DEFAULT, ACCEPT_DEFAULT and QUEUE_DEFAULT. DROP_DEFAULT describes the rules to be applied before a connection request is dropped by a DROP policy; REJECT_DEFAULT describes the rules to be applied if a connection request is rejected by a REJECT policy. The other two are similar for ACCEPT and QUEUE policies. The value assigned to these may be: a) The name of an action. b) The name of a macro c) 'None' or 'none' The default values are: DROP_DEFAULT="Drop" REJECT_DEFAULT="Reject" ACCEPT_DEFAULT=none QUEUE_DEFAULT=none If USE_ACTIONS=Yes, then these values refer to action.Drop and action.Reject respectively. If USE_ACTIONS=No, then these values refer to macro.Drop and macro.Reject. If you set the value of either option to "None" then no default action will be used and the default action or macro (if any) must be specified in /etc/shorewall/policy - The POLICY column in /etc/shorewall/policy has been extended. In /etc/shorewall/policy, when the POLICY is DROP, REJECT, ACCEPT or QUEUE then the policy may be followed by ":" and one of the following: a) The word "None" or "none". This causes any default action defined in /etc/shorewall/shorewall.conf to be omitted for this policy. b) The name of an action (requires that USE_ACTIONS=Yes in shorewall.conf). That action will be invoked before the policy is enforced. c) The name of a macro. The rules in that macro will be applied before the policy is enforced. This does not require USE_ACTIONS=Yes. Example: #SOURCE DEST POLICY LOG # LEVEL loc net ACCEPT net all DROP:MyDrop info # # THE FOLLOWING POLICY MUST BE LAST # all all REJECT:MyReject info 4) For users whose kernel and iptables have Extended MARK Target support, it is now possible to logically AND or OR a value into the current packet mark by preceding the mark value (and optional mask) with an ampersand ("&") or vertical bar ("|") respectively. Example: To logically OR the value 4 into the mark value for packets from 192.168.1.1: #MARK SOURCE |4 192.168.1.1 5) Previously, zone names were restricted to five characters in length. That limit derives from the --log-prefix in Netfilter log messages which must be 29 bytes or less in length. With the standard Shorewall LOGFORMAT, that leaves 11 characters for the chain name; given that many chain names are of the form 2, that gives a maximum zone name length of 5. Beginning with this release, the maximum length of a zone name is dependent on the LOGFORMAT (the maximum length may never be less than 5 but it may be greater than 5). For example, setting LOGFORMAT="FW:%s:%s:" will allow zone names of up to 8 characters. 6) Netfilter provides support for attachmend of comments to Netfilter rules. Comments can be up to 255 bytes in length and are visible using the "shorewall show ", "shorewall show nat", "shorewall show mangle" and "shorewall dump" commands. Comments are delimited by '/* ... */" in the output. Beginning with Shorewall 3.3.3, you may place COMMENT lines in the /etc/shorewall/rules, /etc/shorewall/tcrules, /etc/shorewall/nat and /etc/shorewall/masq files and in action files. The remainder of the line is treated as a comment and it will be attached as a Netfilter comment to the rule(s) generated by succeding entries in the file. Note: Do not prefix the comment with "#". Shorewall's two-pass compiler strips off "#" comments in the first pass and processes COMMENT lines in the second pass. Hence, by the time that COMMENT is processed, the "#" and everything following it has been removed (see example below). To stop the current comment from being attached to further rules, simply include COMMENT on a line by itself (so that the following rules will have no comment) or specify a new COMMENT. If you do not have Comment support in your iptables/kernel (see the output of "shorewall[-lite] show capabilities") then COMMENTS are ignored with this warning: COMMENT ignored -- requires comment support in iptables/Netfilter Example from my rules file: #SOURCE SOURCE DEST PROTO DEST PORT(S) COMMENT Stop Microsoft Noise REJECT loc net tcp 137,445 REJECT loc net udp 137:139 COMMENT # Stop comment from being attached to rules below The output of "shorewall show loc2net" includes (folded): 0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 137,445 /* Stop Microsoft Noise */ 0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:137:139 /* Stop Microsoft Noise */ 7) A new macro (macro.RDP) has been added for Microsoft Remote Desktop. This macro was contributed by Tuomo Soini. 8) A new 'maclog' extension file has been added. This file is processed just before logging based on the setting of MACLIST_LOG_LEVEL is done. When the extension is invoked, the CHAIN variable will contain the name of the chain where rules should be inserted. Remember that if you have specified MACLIST_TABLE=mangle, then your run_iptables commands should include "-t mangle". 9) The SUBNET column in /etc/shorewall/masq has been renamed SOURCE to more accurately describe the contents of the column. 10) Previously, it was not possible to use exclusion in /etc/shorewall/hosts. Beginning with this release, you may now use exclusion lists in entries in this file. Exclusion lists are discussed at: http://www.shorewall.net/configuration_file_basics.htm#Exclusion. Example: loc eth0:192.168.1.0/24!192.168.1.4,192.168.1.16/28 In that example, the 'loc' zone is defined to be the subnet 192.168.1.0/24 interfacing via eth0 *except* for host 192.168.1.4 and hosts in the sub-network 192.168.1.16/28. 11) New "shorewall[-lite] show ip" and "shorewall[-lite] show routing" commands have been added. The first produces the same output as "ip addr ls". The second produces a report about your routing rules and tables. 12) Beginning with this release, Shorewall and Shorewall Lite will share common change logs and release notes. 13) In Shorewall versions prior to 3.3.2, multiple jumps to a '2all' chain could be generated in succession. Example from an earlier shorewall version: gateway:~ # shorewall-lite show eth2_fwd Shorewall Lite 3.3.2 Chains eth2_fwd at gateway - Thu Oct 19 08:54:37 PDT 2006 Counters reset Thu Oct 19 08:34:47 PDT 2006 Chain eth2_fwd (1 references) pkts bytes target prot opt in out source destination 0 0 dynamic all -- * * 0.0.0.0/0 0.0.0.0/0 state INVALID,NEW 0 0 wifi2all all -- * eth0 0.0.0.0/0 0.0.0.0/0 0 0 wifi2all all -- * br0 0.0.0.0/0 0.0.0.0/0 0 0 wifi2all all -- * eth3 0.0.0.0/0 0.0.0.0/0 0 0 wifi2all all -- * tun+ 0.0.0.0/0 0.0.0.0/0 gateway:~ # This redundancy may be eliminated by setting OPTIMIZE=1 in shorewall.conf. gateway:~ # shorewall-lite show eth2_fwd Shorewall Lite 3.3.3 Chains eth2_fwd at gateway - Thu Oct 19 09:15:24 PDT 2006 Counters reset Thu Oct 19 09:15:19 PDT 2006 Chain eth2_fwd (1 references) pkts bytes target prot opt in out source destination 0 0 dynamic all -- * * 0.0.0.0/0 0.0.0.0/0 state INVALID,NEW 0 0 wifi2all all -- * * 0.0.0.0/0 0.0.0.0/0 gateway:~ # Note that with OPTIMIZE=1, traffic destined for an interface/Address that falls outside of all defined zones may now be logged out of a '2all' chain rather than out of the FORWARD chain. The OPTIMIZE setting also controls the suppression of redundant wildcard rules (those specifying "all" in the SOURCE or DEST column). A wildcard rule is considered to be redundant when it has the same ACTION and Log Level as the applicable policy. Example: /etc/shorewall/policy #SOURCE DEST POLICY LEVEL loc net ACCEPT /etc/shorewall/rules #ACTION SOURCE DEST PROTO DEST # PORT(S) ... ACCEPT all all icmp 8 OPTIMIZE=0 gateway:~ # shorewall show loc2net Shorewall Lite 3.3.3 Chains loc2net at gateway - Thu Oct 26 07:55:03 PDT 2006 Counters reset Thu Oct 26 07:54:58 PDT 2006 Chain loc2net (1 references) pkts bytes target prot opt in out source destination ... 0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 0 0 ACCEPT icmp -- * * 0.0.0.0/0 0.0.0.0/0 icmp type 8 0 0 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 gateway:~ OPTIMIZE=1 gateway:~ # shorewall show loc2net Shorewall Lite 3.3.3 Chains loc2net at gateway - Thu Oct 26 07:57:12 PDT 2006 Counters reset Thu Oct 26 07:56:38 PDT 2006 Chain loc2net (1 references) pkts bytes target prot opt in out source destination ... 0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 0 0 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0 gateway:~ If you really want a rule that duplicates the policy, follow the action with "!": #ACTION SOURCE DEST PROTO DEST # PORT(S) ... ACCEPT! all all icmp 8 14) IP Address ranges are now allowed in the drop, reject, allow and logdrop shorewall[-lite] commands. 15) Previously, Shorewall has not attempted to undo the changes it has made to the firewall's routing as a result of entries in /etc/shorewall/providers and /etc/shorewall/routes. Beginning with this release, Shorewall will attempt to undo these changes. When Shorewall starts or is restarted and there are entries in /etc/shorewall/providers, Shorewall will capture the contents of /etc/shorewall/rt_tables and will restore that database when Shorewall is stopped or restarted. Similarly, the default route will be captured the first time that you [re]start Shorewall using this version and will be restored under the following conditions: a) shorewall stop b) shorewall clear c) shorewall restart or restore and there are no entries in /etc/shorewall/providers. Once the default route has been restored, Shorewall will delete the saved copy so that it will once again be captured at the next shorewall start or shorewall restore. 16) Shorewall no longer includes policy matches in its generated ruleset when no IPSEC zones or IPSEC networks are defined (IPSEC networks are defined using the 'ipsec' option in /etc/shorewall/hosts). 17) The Makefile installed in /usr/share/shorewall/configfiles/ is now the same one mentioned at http://www.shorewall.net/CompiledPrograms.html. Once the file is copied into an export directory, you modify the setting of the HOST variable to match the name of the remote firewall. The default target is the "firewall" script so "make" compiles the firewall script if any of the configuration files have changed. "make install" builds "firewall" if necessary then installs it on the remote firewall. "make capabilities" will generate the "capabilities" file if that file doesn't exist. "make save" will save the running configuration on the remote firewall. 18) Shorewall and Shorewall Lite now include the following manpages. shorewall-accounting(5) shorewall-actions(5) shorewall-blacklist(5) shorewall.conf(5) shorewall-hosts(5) shorewall-interfaces(5) shorewall-lite(8) shorewall-maclist(5) shorewall-masq(5) shorewall-nat(5) shorewall-netmap(5) shorewall-params(5) shorewall-policy(5) shorewall-providers(5) shorewall-proxyarp(5) shorewall-route_rules(5) shorewall-routestopped(5) shorewall-rules(5) shorewall-tcclasses(5) shorewall-tcdevices(5) shorewall-tcrules(5) shorewall-template(5) shorewall-tos(5) shorewall-tunnels(5) shorewall(8) shorewall-zones(5) 19) From the beginning, the Shorewall configuration files in /etc/shorewall/ have contained documentary comments. While these comments are useful, they present an upgrade problem. Beginning with this release, these comments are removed from the configuration files themselves and are replaced by the manpages described in the preceding release note entry.