Shorewall 3.0.4 Note to users upgrading from Shorewall 2.x 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. The new/changed options in shorewall 3.0 are listed below. If you don't want to convert to the new 3.0 format for /etc/shorewall/zones and you don't want to replace your current rules that use 2.x builtin actions, then if you plan to use the 3.0 shorewall.conf file then you must change it as follows: - SPECFILE The 3.0 shorewall.conf file has IPSECFILE=zones. You want to set it to IPSECFILE=ipsec. This will indicate that your /etc/shorewall/zones file is in the pre-3.0 format. - FW The 3.0 shorewall.conf file has FW undefined. If you have named your firewall zone something other than 'fw' then you must set FW accordingly. - MAPOLDACTIONS The 3.0 shorewall.conf file has MAPOLDACTIONS=No. You want to set it to MAPOLDACTIONS=Yes in order to permit rules that use the 2.x builtin actions such as AllowPing to continue to work. 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 Please see the "Migration Considerations" below for additional upgrade information. Problems Corrected in 3.0.4 1) The shorewall.conf file is once again "console friendly". Patch is courtesy of Tuomo Soini. Migration Considerations for Users upgrading from Shorewall 2.x. 1) The "monitor" command has been eliminated. 2) The "DISPLAY" and "COMMENTS" columns in the /etc/shorewall/zones file have been removed and have been replaced by the former columns of the /etc/shorewall/ipsec file. The latter file has been removed. Additionally the FW option in shorewall.conf has been deprecated and is no longer set to 'fw' by default. New users are expected to define the firewall zone in /etc/shorewall/zones. Adhering to the principle of least astonishment, the old /etc/shorewall/ipsec file will continue to be supported. A new IPSECFILE variable in /etc/shorewall/shorewall.conf determines the name of the file that Shorewall looks in for IPSEC information. If that variable is not set or is set to the empty value then IPSECFILE=ipsec is assumed. So if you simply upgrade and don't do something idiotic like replace your current shorewall.conf file with the new one, your old configuration will continue to work. A dummy 'ipsec' file is included in the release so that your package manager (e.g., rpm) won't remove your existing file. The shorewall.conf file included in this release sets IPSECFILE=zones so that new users are expected to use the new zone file format. As a result, the columns in the /etc/shorewall/zones file are now as follows: ZONE Short name of the zone (5 Characters or less in length). The names "all" and "none" are reserved and may not be used as zone names. Where a zone is nested in one or more other zones, you may follow the (sub)zone name by ":" and a comma-separated list of the parent zones. The parent zones must have been defined in earlier records in this file. Example: #ZONE TYPE OPTIONS a ipv4 b ipv4 c:a,b ipv4 Currently, Shorewall uses this information only to reorder the zone list so that parent zones appear after their sub zones in the list. In the future, Shorewall may make more extensive use of that information. TYPE ipv4 - This is the standard Shorewall zone type and is the default if the column is left empty or if it is entered as "-". Communication with some zone hosts may be encrypted. Encrypted hosts are designated using the 'ipsec' option in /etc/shorewall/hosts. ipsec - Communication with all zone hosts is encrypted Your kernel and iptables must include policy match support. firewall - Designates the firewall itself. You must have exactly one 'firewall' zone. No options are permitted with a 'firewall' zone. OPTIONS, A comma-separated list of options as IN OPTIONS, follows: OUT OPTIONS reqid= where is specified using setkey(8) using the 'unique: option for the SPD level. spi= where is the SPI of the SA used to encrypt/decrypt packets. proto=ah|esp|ipcomp mss= (sets the MSS field in TCP packets) mode=transport|tunnel tunnel-src=
[/] (only available with mode=tunnel) tunnel-dst=
[/] (only available with mode=tunnel) strict Means that packets must match all rules. next Separates rules; can only be used with strict.. Example: mode=transport,reqid=44 The options in the OPTIONS column are applied to both incoming and outgoing traffic. The IN OPTIONS are applied to incoming traffic (in addition to OPTIONS) and the OUT OPTIONS are applied to outgoing traffic. If you wish to leave a column empty but need to make an entry in a following column, use "-". THE ORDER OF THE ENTRIES IN THIS FILE IS IMPORTANT IF YOU HAVE NESTED OR OVERLAPPING ZONES DEFINED THROUGH /etc/shorewall/hosts. 3) The DROPINVALID option has been removed from shorewall.conf. The behavior will be as if DROPINVALID=No had been specified. If you wish to drop invalid state packets, use the dropInvalid built-in action. 4) The 'nobogons' interface and hosts option as well as the BOGON_LOG_LEVEL option have been eliminated. 5) Most of the standard actions have been replaced by parametrized macros (see below). So for example, action.AllowSMTP and action.DropSMTP have been removed and a parametrized macro macro.SMTP has been added to replace them. In order that current users don't have to immediately update their rules and user-defined actions, Shorewall can substitute an invocation of a new macro for an existing invocation of one of the old actions. So if your rules file calls AllowSMTP, Shorewall will replace that call with SMTP/ACCEPT. Because this substitution is expensive, it is conditional based on the setting of MAPOLDACTIONS in shorewall.conf. If this option is set to YES or if it is not set (such as if you are using your old shorewall.conf file) then Shorewall will perform the substitution. Once you have converted to use the new macros, you can set MAPOLDACTIONS=No and invocations of those actions will go much quicker during 'shorewall [re]start'. 6) The STATEDIR variable in /etc/shorewall/shorewall.conf has been removed. STATEDIR is now fixed at /var/lib/shorewall. If you have previously set STATEDIR to another directory, please copy the files from that directory to /var/lib/shorewall/ before [re]starting Shorewall after the upgrade to this version. 7) The "shorewall status" command now just gives the status of Shorewall (started or not-started). The previous status command has been renamed "dump". The command also shows the state relative to the state diagram at http://shorewall.net/starting_and_stopping_shorewall.htm. In addition to the state, the time and date at which that state was entered is shown. Note that at least one "shorewall [re]start" must be issued after upgrading to this release before "shorewall status" will show anything but "Unknown" for the state. 8) The "shorewall forget" command now removes the dynamic blacklist save file (/var/lib/shorewall/save). 9) In previous versions of Shorewall, the rules generated by entries in /etc/shorewall/tunnels preceded those rules generated by entries in /etc/shorewall/rules. Beginning with this release, the rules generated by entries in the tunnels file will appear *AFTER* the rules generated by the rules file. This may cause you problems if you have REJECT, DENY or CONTINUE rules in your rules file that would cause the tunnel transport packets to not reach the rules that ACCEPT them. See http://www.shorewall.net/VPNBasics.html for information on the rules generated by entries in the tunnels file. 10) The NEWNOTSYN and LOGNEWNOTSYN options in shorewall.conf have been removed as have the 'newnotsyn' options in /etc/shorewall/interfaces and /etc/shorewall/hosts. TCP new-not-syn packets may be blocked using the 'dropNotSyn' or 'rejNotSyn' built-in actions. Example: Reject all new-not-syn packets from the net and log them at the 'info' level. #ACTION SOURCE DEST PROTO SECTION NEW rejNotSyn:info net all tcp Note that the rule is added at the front of the NEW section of the rules file. 11) A new value is defined for the TC_ENABLED option in shorewall.conf to enable the built-in tc4shorewall traffic shaper. If you set TC_ENABLED=internal then tc4shorewall will be used. If the option is set to Yes then Shorewall will continue to look for a 'tcstart' script. Note that Shorewall itself does not provide a file named /etc/shorewall/tcstart so if you set TC_ENABLED=Yes, then you must supply that script. Additional Migration Considerations for Users upgrading from Shorewall 2.2 or 2.0. Note that these are in addition to the considerations listed above. 1) Shorewall now enforces the restriction that mark values used in /etc/shorewall/tcrules are less than 256. If you are using mark values >= 256, you must change your configuration before you upgrade. 2) LEAF/Bering packages for version 2.4.0 and later will not be available from shorewall.net. See http://leaf.sf.net for the lastest version of Shorewall for LEAF variants. Additional Migration Considerations for Users upgrading from Shorewall 2.0. Note that these are in addition to the considerations listed above. 1) Shorewall configuration files except shorewall.conf are now empty (they contain only comments). If you wish to retain the defaults in any of the following files, you should copy these files before upgrading them then restore them after the upgrade: /etc/shorewall/zones /etc/shorewall/policy /etc/shorewall/tos 2) If shorewall.conf is upgraded to the latest version, it needs to be modified to set STARTUP_ENABLED=Yes 3) The ORIGINAL DEST column of the /etc/shorewall/rules file may no longer contain a second (SNAT) address. You must use an entry in /etc/shorewall/masq instead. Example from Shorewall FAQ #1: Prior to Shorewall 2.2: /etc/shorewall/interfaces loc eth1 detect routeback,... /etc/shorewall/rules DNAT loc loc:192.168.1.12 tcp 80 \ - 130.252.100.69:192.168.1.254 Shorewall 2.2 and Later: /etc/shorewall/interfaces loc eth1 detect routeback,... /etc/shorewall/masq: eth1 eth1 192.168.1.254 tcp 80 /etc/shorewall/rules: DNAT loc loc:192.168.1.12 tcp 80 \ - 130.252.100.69 4) The 'logunclean' and 'dropunclean' options that were deprecated in Shorewall 2.0 have now been removed completely. 5) A new IPTABLES variable has been added to shorewall.conf. This variable names the iptables executable that Shorewall will use. The variable is set to "/sbin/iptables". If you use the new shorewall.conf, you may need to change this setting to maintain compabibility with your current setup (if you use your existing shorewall.conf that does not set IPTABLES then you should experience no change in behavior). 6) The default port for OpenVPN tunnels has been changed from 5000 to 1194 to reflect the recent IANA allocation of that port for OpenVPN. 7) If you are setting a shell variable using a statement similar to: ETH0_IP=`find_interface_address eth0` then you must change that statement to read as follows: ETH0_IP=`find_first_interface_address eth0` New Features in Shorewall 3.0.0. 1) Error and warning messages are made easier to spot by using capitalization (e.g., ERROR: and WARNING:). 2) A new option 'critical' has been added to /etc/shorewall/routestopped. This option can be used to enable communication with a host or set of hosts during the entire "shorewall [re]start/stop" process. Listing a host with this option differs from listing it without the option in several ways: a) The option only affect traffic between the listed host(s) and the firewall itself. b) If there are any entries with 'critical', the firewall will be completely opened briefly during start, restart and stop but there will be no chance of any packets to/from the listed host(s) being dropped or rejected. Possible uses for this option are: a) Root file system is NFS mounted. You will want to list the NFS server in the 'critical' option. b) You are running Shorewall in a Crossbeam environment (www.crossbeam.com). You will want to list the Crossbeam interface in this option 3) A new 'macro' feature has been added. Macros are very similar to actions and can be used in similar ways. The differences between actions and macros are as follows: a) An action creates a separate chain with the same name as the action (when logging is specified on the invocation of an action, a chain beginning with "%" followed by the name of the action and possibly followed by a number is created). When a macro is invoked, it is expanded in-line and no new chain is created. b) An action may be specified as the default action for a policy; macros cannot be specified this way. c) Actions must be listed in either /usr/share/shorewall/actions.std or in /etc/shorewall/actions. Macros are defined simply by placing their definition file in the CONFIG_PATH. d) Actions are defined in a file with a name beginning with "action." and followed by the name of the action. Macro files are defined in a file with a name beginning with "macro.". e) Actions may invoke other actions. Macros may not directly invoke other macros although they may invoke other macros indirectly through an action. f) DNAT[-] and REDIRECT[-] rules may not appear in an action. They are allowed in a macro with the restriction that the a macro containing one of these rules may not be invoked from an action. g) The values specified in the various columns when you invoke a macro are substituted in the corresponding column in each rule in the macro. The first three columns get special treatment: ACTION If you code PARAM as the action in a macro then when you invoke the macro, you can include the name of the macro followed by a slash ("/") and an ACTION (either built-in or user-defined. All instances of PARAM in the body of the macro will be replaced with the ACTION. Any logging applied when the macro is invoked is applied following the same rules as for actions. SOURCE and DEST If the rule in the macro file specifies a value and the invocation of the rule also specifies a value then the value in the invocation is appended to the value in the rule using ":" as a separator. Example: /etc/shorewall/macro.SMTP PARAM - loc tcp 25 /etc/shorewall/rules: SMTP/DNAT:info net 192.168.1.5 Would be equivalent to the following in the rules file: DNAT:info net loc:192.168.1.5 tcp 25 Rest Any value in the invocation replaces the value in the rule in the macro. One additional restriction applies to the mixing of macros and actions. Macros that are invoked from actions cannot themselves invoke other actions. 4) If you have 'make' installed on your firewall, then when you use the '-f' option to 'shorewall start' (as happens when you reboot), if your /etc/shorewall/ directory contains files that were modified after Shorewall was last restarted then Shorewall is started using the config files rather than using the saved configuration. 5) The 'arp_ignore' option has been added to /etc/shorewall/interfaces entries. This option sets /proc/sys/net/ipv4/conf//arp_ignore. By default, the option sets the value to 1. You can also write arp_ignore= where value is one of the following: 1 - reply only if the target IP address is local address configured on the incoming interface 2 - reply only if the target IP address is local address configured on the incoming interface and both with the sender's IP address are part from same subnet on this interface 3 - do not reply for local addresses configured with scope host, only resolutions for global and link addresses are replied 4-7 - reserved 8 - do not reply for all local addresses WARNING -- DO NOT SPECIFY arp_ignore FOR ANY INTERFACE INVOLVED IN PROXY ARP. 6) In /etc/shorewall/rules, "all+" in the SOURCE or DEST column works like "all" but also includes intrazone traffic. So the rule: ACCEPT loc all+ tcp 22 would allow SSH traffic from loc->loc whereas ACCEPT loc all tcp 22 does not. 7) A new FASTACCEPT option has been added to shorewall.conf. Normally, Shorewall defers accepting ESTABLISHED/RELATED packets until these packets reach the chain in which the original connection was accepted. So for packets going from the 'loc' zone to the 'net' zone, ESTABLISHED/RELATED packets are ACCEPTED in the 'loc2net' chain. If you set FASTACCEPT=Yes, then ESTABLISHED/RELEATED packets are accepted early in the INPUT, FORWARD and OUTPUT chains. If you set FASTACCEPT=Yes then you may not include rules in the ESTABLISHED or RELATED sections of /etc/shorewall/rules. 8) Shorewall now generates an error if the 'norfc1918' option is specified for an interface with an RFC 1918 address. 9) You may now specify "!" followed by a list of addresses in the SOURCE and DEST columns of entries in /etc/shorewall/rules, /etc/shorewall/tcrules and in action files and Shorewall will generate the rule that you expect. Example 1 (/etc/shorewall/rules): #ACTION SOURCE DEST PROTO DEST PORT(S) ACCEPT loc:!192.168.1.0/24,10.0.0.0/8 net tcp 80 That rule would allow loc->net HTTP access except for the local networks 192.168.1.0/24 and 10.0.0.0/8. Example 2 (/etc/shorewall/rules): #ACTION SOURCE DEST PROTO DEST PORT(S) ACCEPT loc:10.0.0.0/24!10.0.0.4,10.0.0.22 \ net tcp 80 That rule would allow loc->net HTTP access from the local network 10.0.0.0/24 except for hosts 10.0.0.4 and 10.0.0.22. 10) Tunnel types "openvpnserver" and "openvpnclient" have been added to reflect the introduction of client and server OpenVPN configurations in OpenVPN 2.0. 11) The COMMAND variable is now set to 'restore' in restore scripts. The value of this variable is sometimes of interest to programmers providing custom /etc/shorewall/tcstart scripts. 12) Previously, if you defined any intra-zone rule(s) then any traffic not matching the rule(s) was subject to normal policies (which usually turned out to involve the all->all REJECT policy). Now, the intra-zone ACCEPT policy will still be in effect in the presence of intra-zone rules. That policy can still be overridden by an explicit policy in your /etc/shorewall/policy file. Example: /etc/shorewall/rules: DNAT loc:!192.168.1.4 loc:192.168.1.4:3128 tcp 80 Any other loc->loc traffic will still be accepted. If you want to also log that other loc->loc traffic at the info log level then insert this into /etc/shorewall/policy: #SOURCE DEST POLICY LOG LEVEL loc loc ACCEPT info 13) Prior to Shorewall 2.5.3, the rules file only controlled packets in the Netfilter states NEW and INVALID. Beginning with this release, the rules file can also deal with packets in the ESTABLISHED and RELATED states. The /etc/shorewall/rules file may now be divided into "sections". Each section is introduced by a line that begins with the keyword SECTION followed by the section name. Sections are as listed below and must appear in the order shown. ESTABLISHED Rules in this section apply to packets in the ESTABLISHED state. RELATED Rules in this section apply to packets in the RELATED state. NEW Rules in this section apply to packets in the NEW and INVALID states. Rules in the ESTABLISHED and RELATED sections are limited to the following ACTIONs: ACCEPT, DROP, REJECT, QUEUE, LOG and User-defined actions. Macros may be used in these sections provided that they expand to only these ACTIONs. At the end of the ESTABLISHED and RELATED sections, there is an implicit "ALLOW all all all" rule. RESTRICTION: If you specify FASTACCEPT=Yes in /etc/shorewall.shorewall.conf then the ESTABLISHED and RELATED sections must be empty. 14) The value 'ipp2p' is once again allowed in the PROTO column of the rules file. It is recommended that rules specifying 'ipp2p' only be included in the ESTABLISHED section of the file. 15) Shorewall actions lack a generalized way to pass parameters to an extension script associated with an action. To work around this lack, some users have used the log tag as a parameter. This works but requires that a log level other than 'none' be specified when the action is invoked. Beginning with this release, you can invoke an action with 'none'. Example: #ACTION SOURCE DEST A:none:these,are,parameters $FW net When /etc/shorewall/A is invoked, the LEVEL variable will be empty but the TAG variable will contain "these,are,parameters" which can be easily parsed to isolate "these", "are" and "parameters": ifs=$IFS IFS=, set -- $TAG IFS=$ifs Now, $1 = these, $2 = are and $3 = parameters 16) The "shorewall check" command now checks the /etc/shorewall/masq, /etc/shorewall/blacklist, /etc/shorewall/proxyarp, /etc/shorewall/nat and /etc/shorewall/providers files. 17) Arne Bernin's "tc4shorewall" package has been integrated into Shorewall. See: http://www.shorewall.net/3.0/traffic_shaping.htm for details. Thanks, Arne! 18) When /usr/share/shorewall/functions is loaded it now sets SHOREWALL_LIBRARY=Loaded Application code such as /etc/shorewall/tcstart may test that variable to determine if the library has been loaded into the current shell process. 19) The install.sh script now does a much cleaner job of backing up the current installation. It copies the directories /etc/shorewall, /usr/share/shorewall and /var/lib/shorewall to a directory of the same name with "-$VERSION.bkout" appended. The init script and /sbin/shorewall are backed up to the /usr/share/shorewall and /var/lib/shorewall directories respectively. This makes it very simple to remove the backups: rm -rf /etc/shorewall-*.bkout rm -rf /usr/share/shorewall-*.bkout rm -rf /var/lib/shorewall-*.bkout 20) A new '-n' option has been added to the "start", "restart", "restore", "stop" and "try" commands. This option instructs Shorewall to not alter the routing in any way. This option is useful when you have a multi-ISP environment because it prevents the route cache from being flushed which preserves the mapping of end-point address pairs to routes. 21) The output of "shorewall dump" now includes a capabilities report such as the one produced by "shorewall show capabilities". 22) Note: This change is only important for users who ran Shorewall 2.5.x. The "plain" zone type has been replaced by "ipv4". The types "IPv4" and "IPV4" are synonyms for "ipv4". In addition, "IPSEC", "ipsec4" and "IPSEC4" are recognized synonyms for "ipsec". 23) The NEWNOTSYN and LOGNEWNOTSYN options in shorewall.conf have been removed as have the 'newnotsyn' options in /etc/shorewall/interfaces and /etc/shorewall/hosts. See the Migration Considerations for instructions if you wish to block "new-not-syn" TCP packets. 24) The "shorewall show zones" command now displays the zone type. You must have restarted Shorewall using this release before this feature will work correctly. 25) Shorewall now supports UDP IPP2P matching. In addition to the "ipp2p" keyword in the PROTOCOL column of the relevant files, the following values may be specified: ipp2p:tcp Equivalent to ipp2p and matches TCP traffic only. ipp2p:udp Matches UDP traffic. ipp2p:all Matches both UDP and TCP traffic. You may not specify a SOURCE PORT with this PROTOCOL. 26) Normally MAC verification triggered by the 'maclist' interface and host options is done out of the INPUT and FORWARD chains of the filter table. Users have reported that under some circumstances, MAC verification is failing for forwarded packets when the packets are being forwarded out of a bridge. To work around this problem, a MACLIST_TABLE option has been added to shorewall.conf. The default value is MACLIST_TABLE=filter which results in the current behavior. If MACLIST_TABLE=mangle then filtering will take place out of the PREROUTING chain of the mangle table. Because the REJECT target may not be used in the PREROUTING chain, the settings MACLIST_DISPOSITION=REJECT and MACLIST_TABLE=mangle are incompatible. 27) The sample configurations are now packaged with the product. They are in the Samples directory on the tarball and are in the RPM they are in the Samples sub-directory of the Shorewall documentation directory. New Features in 3.0.1 1) To make the macro facility more flexible, Shorewall now examines the contents of the SOURCE and DEST columns in both the macro body and in the invocation and tries to create the intended rule. If the value in the invocation appears to be an address (IP or MAC) or the name of an ipset, then it is placed after the value in the macro body. Otherwise, it is placed before the value in the macro body. Example 1: /etc/shorewall/macro.foo: PARAM - 192.168.1.5 tcp http /etc/shorewallrules: foo/ACCEPT net loc Effective rule: ACCEPT net loc:192.168.1.5 tcp http Example 2: /etc/shorewall/macro.bar: PARAM net loc tcp http /etc/shorewall/rules: bar/ACCEPT - 192.168.1.5 Effective rule: ACCEPT net loc:192.168.1.5 tcp http New Features in 3.0.2 1) A new Webmin macro has been added. This macro assumes that Webmin is running on its default port (10000). New Features in 3.0.3 1) A "shorewall show macros" command has been added. This command displays a list of the standard macros along with a brief description of each. 2) The '-q' option is now supported with 'safe-start' and 'safe-restart'. 3) The value "-" is now allowed in the ADDRESS/SUBNET column of /etc/shorewall/blacklist. That value is equivalent to specifying 0.0.0.0/0 in that column. 4) The output of "shorewall show tc" and "shorewall show classifiers" is now included in the output from "shorewall dump". This will aid us in analyzing traffic shaping problems. 5) You can now specify 'none' in the COPY column of /etc/shorewall/providers to signal that you want Shorewall to only copy routes through the interface listed in the INTERFACE column. Note: This works on older versions of Shorewall as well. It is now documented. 6) An 'ipdecimal' command has been added to /sbin/shorewall. This command converts between dot-quad and decimal. Example: gateway:/etc/openvpn# shorewall ipdecimal 192.168.1.4 3232235780 gateway:/etc/openvpn# shorewall ipdecimal 3232235780 192.168.1.4 gateway:/etc/openvpn# 7) /etc/init.d/shorewall now supports a 'reload' command which is synonymous with the 'restart' command.