From d933b26daca44da4240d6b647e59d27c09d233ea Mon Sep 17 00:00:00 2001 From: teastep Date: Tue, 19 Dec 2006 17:00:09 +0000 Subject: [PATCH] Some more 3.4 doc changes git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5136 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- docs/Documentation.xml | 1402 ++++++++++++++++++++-------------------- 1 file changed, 693 insertions(+), 709 deletions(-) diff --git a/docs/Documentation.xml b/docs/Documentation.xml index 397e6bc28..e780db5ca 100644 --- a/docs/Documentation.xml +++ b/docs/Documentation.xml @@ -1195,7 +1195,7 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 /usr/share/shorewall/actions.std or in /etc/shorewall/actions. - This approach has two drawbacks: + This approach has had drawbacks: @@ -1211,11 +1211,11 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 - The solution is two-fold: + The solution was two-fold: - Four new options have been added to the + Four new options were 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 @@ -1265,8 +1265,7 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 - The POLICY column in /etc/shorewall/policy has been - extended. + The POLICY column in /etc/shorewall/policy was extended. In /etc/shorewall/policy, when the POLICY is DROP, REJECT, ACCEPT or QUEUE then the policy may be followed by @@ -1275,8 +1274,8 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 The word "None" or "none". This causes any default action - defined in /etc/shorewall/shorewall.conf to be omitted for this - policy. + defined in /etc/shorewall/shorewall.conf to + be omitted for this policy. @@ -1291,6 +1290,10 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 USE_ACTIONS=Yes. + + If the value names both an action and a macro, then the action + will be used if USE_ACTIONS=Yes and the macro will be used if + USE_ACTIONS=No. @@ -1326,12 +1329,12 @@ loc eth1:192.168.1.0/24,192.168.12.0/24 The default policy for connection requests from the SOURCE - zone to the DESTINATION zone. Beginning with Shorewall version 3.4, - the policy may be optionally followed by a colon (":") and the - default action or default macro to be used before - the policy is applied. Default actions or macros specified here - override any such default specified using the + zone to the DESTINATION zone. Beginning with Shorewall version + 3.4.0, the policy may be optionally followed by a colon (":") and + the default action or + default macro to be used + before the policy is applied. Default actions or macros specified + here override any such default specified using the policy_DEFAULT options in /etc/shorewall/shorewall.conf. @@ -2901,140 +2904,289 @@ eth0 eth1 206.124.146.176 The special value "none" is used to indicate that no default - action/default should be used. + action/default macro should be used. + + For more information on this topic, see the /etc/shorewall/policy section + above. - USE_ACTIONS (Added in version 3.4.0) + ADD_IP_ALIASES - If set to 'Yes' (the default) then user-defined and standard - actions may be used. If set to 'No', only built-in actions may be - used. + This parameter determines whether Shorewall automatically adds + the external address(es) in . If the variable is set to Yes or + yes then Shorewall automatically adds these aliases. + If it is set to No or no, you must add + these aliases yourself using your distribution's network + configuration tools. + + If this variable is not set or is given an empty value + (ADD_IP_ALIASES="") then ADD_IP_ALIASES=Yes is assumed. + + + Addresses added by ADD_IP_ALIASES=Yes are deleted and + re-added during shorewall restart. As a + consequence, connections using those addresses may be + severed. + - OPTIMIZE (Added in version 3.4.0) + ADD_SNAT_ALIASES - In Shorewall versions prior to 3.3.2, multiple jumps to a - '2all' chain could be generated in succession. + This parameter determines whether Shorewall automatically adds + the SNAT ADDRESS in . If + the variable is set to Yes or yes then + Shorewall automatically adds these addresses. If it is set to + No or no, you must add these addresses + yourself using your distribution's network configuration + tools. - Example from an earlier shorewall version: + If this variable is not set or is given an empty value + (ADD_SNAT_ALIASES="") then ADD_SNAT_ALIASES=No is assumed. - gateway:~ # shorewall-lite show eth2_fwd -Shorewall Lite 3.3.2 Chains eth2_fwd at gateway - Thu Oct 19 08:54:37 PDT 2006 + + Addresses added by ADD_SNAT_ALIASES=Yes are deleted and + re-added during shorewall restart. As a + consequence, connections using those addresses may be + severed. + + + -Counters reset Thu Oct 19 08:34:47 PDT 2006 + + ADMINISABSENTMINDED -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:~ # + + The value of this variable affects Shorewall's stopped state. + When ADMINISABSENTMINDES=No, only traffic to/from those addresses + listed in /etc/shorewall/routestopped is accepted when Shorewall is + stopped. When ADMINISABSENTMINDED=Yes, in addition to traffic + to/from addresses in + /etc/shorewall/routestopped, connections that + were active when Shorewall stopped continue to work and all new + connections from the firewall system itself are allowed. If this + variable is not set or is given the empty value then + ADMINISABSENTMINDED=No is assumed. + + - This redundancy may be eliminated by setting OPTIMIZE=1 in - shorewall.conf. + + BLACKLIST_DISPOSITION - gateway:~ # shorewall-lite show eth2_fwd -Shorewall Lite 3.3.3 Chains eth2_fwd at gateway - Thu Oct 19 09:15:24 PDT 2006 + + This parameter determines the disposition of packets from + blacklisted hosts. It may have the value DROP if the packets are to + be dropped or REJECT if the packets are to be replied with an ICMP + port unreachable reply or a TCP RST (tcp only). If you do not assign + a value or if you assign an empty value then DROP is assumed. + + -Counters reset Thu Oct 19 09:15:19 PDT 2006 + + BLACKLIST_LOGLEVEL -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:~ # + + This parameter determines if packets from blacklisted hosts + are logged and it determines the syslog level that they are to be + logged at. Its value is a syslog + level (Example: BLACKLIST_LOGLEVEL=debug). If you do not + assign a value or if you assign an empty value then packets from + blacklisted hosts are not logged. + + - 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 + + BRIDGING + + + When set to Yes or yes, enables Shorewall Bridging support. + + + + + CLAMPMSS[=<value>] + + + This parameter enables the TCP Clamp MSS to PMTU feature of + Netfilter and is usually required when your internet connection is + through PPPoE or PPTP. If set to Yes or + yes, the feature is enabled. If left blank or set to + No or no, the feature is not + enabled. + + + This option requires CONFIG_IP_NF_TARGET_TCPMSS in your kernel. + + + You may also set CLAMPMSS to a numeric value (e.g., + CLAMPMSS=1400). This will set the MSS field in TCP SYN packets going + through the firewall to the value that you specify. + + + + + CLEAR_TC + + + If this option is set to No then Shorewall + won't clear the current traffic control rules during [re]start. This + setting is intended for use by people that prefer to configure + traffic shaping when the network interfaces come up rather than when + the firewall is started. If that is what you want to do, set + TC_ENABLED=Yes and CLEAR_TC=No and do not supply an + /etc/shorewall/tcstart file. That way, your + traffic shaping rules can still use the fwmark + classifier based on packet marking defined in + /etc/shorewall/tcrules. If not specified, CLEAR_TC=Yes is + assumed. + + + + + CONFIG_PATH + + + Specifies where configuration files other than + shorewall.conf may be found. CONFIG_PATH is + specifies as a list of directory names separated by colons (":"). + When looking for a configuration file other than + shorewall.conf: + + + + If the command is "try" or if "-c <configuration + directory>" was specified in the command then the directory + given in the command is searched first. + + + + Next, each directory in the CONFIG_PATH setting is + searched in sequence. + + + + If CONFIG_PATH is not given or if it is set to the empty value + then the contents of + /usr/share/shorewall/configpath are used. As + released from shorewall.net, that file sets the CONFIG_PATH to + /etc/shorewall:/usr/share/shorewall + but your particular distribution may set it differently. + See the output of shorewall show config for the + default on your system. + + Note that the setting in + /usr/share/shorewall/configpath is always used + to locate shorewall.conf. + + + + + DELAYBLACKLISTLOAD + + + Users with a large static black list + (/etc/shorewall/blacklist) may want to set the + DELAYBLACKLISTLOAD option to Yes. When DELAYBLACKLISTLOAD=Yes, + Shorewall will enable new connections before loading the blacklist + rules. While this may allow connections from blacklisted hosts to + slip by during construction of the blacklist, it can substantially + reduce the time that all new connections are disabled during + shorewall [re]start. + + + + + DETECT_DNAT_ADDRS + + + If set to Yes or yes, Shorewall + will detect the first IP address of the interface to the source zone + and will include this address in DNAT rules as the original + destination IP address. If set to No or + no, Shorewall will not detect this address and any + destination IP address will match the DNAT rule. If not specified or + empty, DETECT_DNAT_ADDRS=Yes is assumed. + + + + + DYNAMIC_ZONES + + + When set to Yes or yes, enables dynamic + zones. DYNAMIC_ZONES=Yes is not allowed in configurations + that will run under Shorewall Lite. + + + + + FASTACCEPT + + + Normally, Shorewall 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. - 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 - - With 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:~ - - With 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 + 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. - VERBOSITY (Added in version 3.2.0) + HIGH_ROUTE_MARKS (Added in version 3.2.0) - Shorewall has traditionally been very noisy (produced lots of - output). You may now set the default level of verbosity using the - VERBOSITY OPTION. + Prior to version 3.2.0, it was not possible to use connection + marking in /etc/shorewall/tcrules if you have a + multi-ISP configuration that uses the track option. - Values are: + Beginning with release 3.2.0, you may now set + HIGH_ROUTE_MARKS=Yes in to effectively divide the packet mark and + connection mark into two 8-byte mark fields. - - 0 — Silent. You may make it more verbose using the -v - option + When you do this: - 1 — Major progress messages displayed + + + The MARK field in the providers file + must have a value that is less than 65536 and that is a multiple + of 256 (using hex representation, the values are 0x0100-0xFF00 + with the low-order 8 bits being zero). + - 2 — All progress messages displayed (old default - behavior) - + + You may only set those mark values in the PREROUTING + chain. + - If not specified, then 2 is assumed. + + Marks used for traffic shaping must still be in the range + of 1-255 and may still not be set in the PREROUTING + chain. + + + + When you SAVE or RESTORE in tcrules, only the TC mark + value is saved or restored. Shorewall handles saving and + restoring the routing (provider) marks. + + @@ -3091,152 +3243,68 @@ $FW chld ACCEPT - HIGH_ROUTE_MARKS (Added in version 3.2.0) + IP_FORWARDING - Prior to version 3.2.0, it was not possible to use connection - marking in /etc/shorewall/tcrules if you have a - multi-ISP configuration that uses the track option. + This parameter determines whether Shorewall enables or + disables IPV4 Packet Forwarding (/proc/sys/net/ipv4/ip_forward). + Possible values are: - Beginning with release 3.2.0, you may now set - HIGH_ROUTE_MARKS=Yes in to effectively divide the packet mark and - connection mark into two 8-byte mark fields. + + + On or on - When you do this: + + packet forwarding will be enabled. + + - - - The MARK field in the providers file - must have a value that is less than 65536 and that is a multiple - of 256 (using hex representation, the values are 0x0100-0xFF00 - with the low-order 8 bits being zero). - + + Off or off - - You may only set those mark values in the PREROUTING - chain. - + + packet forwarding will be disabled. + + - - Marks used for traffic shaping must still be in the range - of 1-255 and may still not be set in the PREROUTING - chain. - + + Keep or keep - - When you SAVE or RESTORE in tcrules, only the TC mark - value is saved or restored. Shorewall handles saving and - restoring the routing (provider) marks. - - + + Shorewall will neither enable nor disable packet + forwarding. + + + + + If this variable is not set or is given an empty value + (IP_FORWARD="") then IP_FORWARD=On is assumed. - FASTACCEPT + IPTABLES - Normally, Shorewall 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. + This parameter names the iptables executable to be used by + Shorewall. If not specified or if specified as a null value, then + the iptables executable located using the PATH option is + used. - STARTUP_ENABLED + LOG_MARTIANS - When set to Yes or yes, Shorewall may be started. Used as - guard against Shorewall being accidentally started before it has - been configured. - - - - - MACLIST_TTL - - - The performance of configurations with a large numbers of - entries in /etc/shorewall/maclist can be improved by setting the - MACLIST_TTL variable in /etc/shorewall/shorewall.conf. - - If your iptables and kernel support the "Recent Match" (see - the output of "shorewall check" near the top), you can cache the - results of a 'maclist' file lookup and thus reduce the overhead - associated with MAC - Verification. - - When a new connection arrives from a 'maclist' interface, the - packet passes through then list of entries for that interface in - /etc/shorewall/maclist. If there is a match then the source IP - address is added to the 'Recent' set for that interface. Subsequent - connection attempts from that IP address occurring within - $MACLIST_TTL seconds will be accepted without having to scan all of - the entries. After $MACLIST_TTL from the first accepted connection - request from an IP address, the next connection request from that IP - address will be checked against the entire list. - - If MACLIST_TTL is not specified or is specified as empty (e.g, - MACLIST_TTL="" or is specified as zero then 'maclist' lookups will - not be cached). - - - - - MACLIST_TABLE - - - Normally, MAC verification occurs in the filter table (INPUT - and FORWARD) chains. When forwarding a packet from an interface with - MAC verification to a bridge interface, that doesn't work. - - This problem can be worked around by setting - MACLIST_TABLE=mangle which will cause Mac verification to occur out - of the PREROUTING chain. Because REJECT isn't available in that - environment, you may not specify MACLIST_DISPOSITION=REJECT with - MACLIST_TABLE=mangle. - - - - - RFC1918_STRICT - - - Traditionally, the RETURN target in the 'rfc1918' file has - caused norfc1918 processing to - cease for a packet if the packet's source IP address matches the - rule. Thus, if you have this entry in /etc/shorewall/rfc1918: - - #SUBNETS TARGET -192.168.1.0/24 RETURN - - then traffic from 192.168.1.4 to 10.0.3.9 will be accepted - even though you also have: - - #SUBNETS TARGET -10.0.0.0/8 logdrop - - Setting RFC1918_STRICT=Yes in shorewall.conf will cause such - traffic to be logged and dropped since while the packet's source - matches the RETURN rule, the packet's destination matches the - 'logdrop' rule. - - If not specified or specified as empty (e.g., - RFC1918_STRICT="") then RFC1918_STRICT=No is assumed. - - - RFC1918_STRICT=Yes requires that your kernel and iptables - support 'Connection Tracking' match. - + If set to Yes or yes, sets + /proc/sys/net/ipv4/conf/all/log_martians and + /proc/sys/net/ipv4/conf/default/log_martians to + 1. Default is which sets both of the above to zero. If you do not + enable martian logging for all interfaces, you may still enable it + for individual interfaces using the logmartians interface option in /etc/shorewall/interfaces. @@ -3281,51 +3349,291 @@ $FW chld ACCEPT - DYNAMIC_ZONES + LOGFILE - When set to Yes or yes, enables dynamic - zones. DYNAMIC_ZONES=Yes is not allowed in configurations - that will run under Shorewall Lite. + This parameter tells the /sbin/shorewall program where to look + for Shorewall messages when processing the show log, + monitor, status and + hits commands. If not assigned or if assigned an + empty value, /var/log/messages is assumed. - CONFIG_PATH + LOGFORMAT - Specifies where configuration files other than - shorewall.conf may be found. CONFIG_PATH is - specifies as a list of directory names separated by colons (":"). - When looking for a configuration file other than - shorewall.conf: + The value of this variable generate the --log-prefix setting + for Shorewall logging rules. It contains a printf + formatting template which accepts three arguments (the chain name, + logging rule number (optional) and the disposition). To use + LOGFORMAT with fireparse, set it as: - - - If the command is "try" or if "-c <configuration - directory>" was specified in the command then the directory - given in the command is searched first. - + LOGFORMAT="fp=%s:%d a=%s " - - Next, each directory in the CONFIG_PATH setting is - searched in sequence. - - + If the LOGFORMAT value contains the substring + %d then the logging rule number is calculated and + formatted in that position; if that substring is not included then + the rule number is not included. If not supplied or supplied as + empty (LOGFORMAT="") then Shorewall:%s:%s: is + assumed. - If CONFIG_PATH is not given or if it is set to the empty value - then the contents of - /usr/share/shorewall/configpath are used. As - released from shorewall.net, that file sets the CONFIG_PATH to - /etc/shorewall:/usr/share/shorewall - but your particular distribution may set it differently. - See the output of shorewall show config for the - default on your system. + + In Shorewall major versions prior to 3.4, + /sbin/shorewall uses the leading part of the + LOGFORMAT string (up to but not including the first + %) to find log messages in the show + log, status and hits + commands. This part should not be omitted (the LOGFORMAT should + not begin with %) and the leading part should be + sufficiently unique for /sbin/shorewall to + identify Shorewall messages. + + + - Note that the setting in - /usr/share/shorewall/configpath is always used - to locate shorewall.conf. + + LOGRATE and LOGBURST + + + These parameters set the match rate and initial burst size for + logged packets. Please see the iptables man page for a description + of the behavior of these parameters (the iptables option --limit is + set by LOGRATE and --limit-burst is set by LOGBURST). If both + parameters are set empty, no rate-limiting will occur. + + + + + LOGRATE=10/minute +LOGBURST=5 + + 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 without matching a packet, 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. + + + + + + MACLIST_DISPOSITION + + + Determines the disposition of connections requests that fail + MAC Verification and must + have the value ACCEPT (accept the connection request anyway), REJECT + (reject the connection request) or DROP (ignore the connection + request). If not set or if set to the empty value (e.g., + MACLIST_DISPOSITION="") then MACLIST_DISPOSITION=REJECT is + assumed. + + + + + MACLIST_LOG_LEVEL + + + Determines the syslog + level for logging connection requests that fail MAC Verification. The value must + be a valid syslogd log level. If you don't want to log these + connection requests, set to the empty value (e.g., + MACLIST_LOG_LEVEL=""). + + + + + MACLIST_TABLE + + + Normally, MAC verification occurs in the filter table (INPUT + and FORWARD) chains. When forwarding a packet from an interface with + MAC verification to a bridge interface, that doesn't work. + + This problem can be worked around by setting + MACLIST_TABLE=mangle which will cause Mac verification to occur out + of the PREROUTING chain. Because REJECT isn't available in that + environment, you may not specify MACLIST_DISPOSITION=REJECT with + MACLIST_TABLE=mangle. + + + + + MACLIST_TTL + + + The performance of configurations with a large numbers of + entries in /etc/shorewall/maclist can be improved by setting the + MACLIST_TTL variable in /etc/shorewall/shorewall.conf. + + If your iptables and kernel support the "Recent Match" (see + the output of "shorewall check" near the top), you can cache the + results of a 'maclist' file lookup and thus reduce the overhead + associated with MAC + Verification. + + When a new connection arrives from a 'maclist' interface, the + packet passes through then list of entries for that interface in + /etc/shorewall/maclist. If there is a match then the source IP + address is added to the 'Recent' set for that interface. Subsequent + connection attempts from that IP address occurring within + $MACLIST_TTL seconds will be accepted without having to scan all of + the entries. After $MACLIST_TTL from the first accepted connection + request from an IP address, the next connection request from that IP + address will be checked against the entire list. + + If MACLIST_TTL is not specified or is specified as empty (e.g, + MACLIST_TTL="" or is specified as zero then 'maclist' lookups will + not be cached). + + + + + MARK_IN_FORWARD_CHAIN + + + If your kernel has a FORWARD chain in the mangle table, you + may set MARK_IN_FORWARD_CHAIN=Yes to cause the marking specified in + the tcrules file to + occur in that chain rather than in the PREROUTING chain. This + permits you to mark inbound traffic based on its destination address + when SNAT or Masquerading are in use. To determine if your kernel + has a FORWARD chain in the mangle table, use the + /sbin/shorewall show mangle + command; if a FORWARD chain is displayed then your kernel will + support this option. If this option is not specified or if it is + given the empty value (e.g., MARK_IN_FORWARD_CHAIN="") then + MARK_IN_FORWARD_CHAIN=No is assumed. + + + + + MODULE_SUFFIX + + + The value of this variable determines the possible file + extensions of kernel modules. The default value is "o gz ko and + o.gz". See for more details. + + + + + MODULESDIR + + + This parameter specifies the directory/directories where your + kernel netfilter modules may be found. If you leave the variable + empty, Shorewall will supply the value "/lib/modules/`uname + -r`/kernel/net/ipv4/netfilter" in versions of Shorewall prior to + 3.2.4 and "/lib/modules/`uname + -r`/kernel/net/ipv4/netfilter:/lib/modules/`uname + -r`/kernel/net/ipv4/netfilter" in later versions. + + + + + OPTIMIZE (Added in version 3.4.0) + + + 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 + + With 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:~ + + With 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 @@ -3371,11 +3679,88 @@ $FW chld ACCEPT - BRIDGING + RETAIN_ALIASES - When set to Yes or yes, enables Shorewall Bridging support. + During "shorewall start", IP addresses to be added as a + consequence of ADD_IP_ALIASES=Yes and ADD_SNAT_ALIASES=Yes are + quietly deleted when /etc/shorewall/nat + and /etc/shorewall/masq are processed + then are re-added later. This is done to help ensure that the + addresses can be added with the specified labels but can have the + undesirable side effect of causing routes to be quietly deleted. + When RETAIN_ALIASES is set to Yes, existing addresses will not be + deleted. Regardless of the setting of RETAIN_ALIASES, addresses + added during "shorewall start" are still deleted at a subsequent + "shorewall stop" or "shorewall restart". + + + + + RFC1918_LOG_LEVEL + + + This parameter determines the level at which packets logged + under the norfc1918 + mechanism are logged. The value must be a valid syslog level and if no level is + given, then info is assumed. + + + + + RFC1918_STRICT + + + Traditionally, the RETURN target in the 'rfc1918' file has + caused norfc1918 processing to + cease for a packet if the packet's source IP address matches the + rule. Thus, if you have this entry in /etc/shorewall/rfc1918: + + #SUBNETS TARGET +192.168.1.0/24 RETURN + + then traffic from 192.168.1.4 to 10.0.3.9 will be accepted + even though you also have: + + #SUBNETS TARGET +10.0.0.0/8 logdrop + + Setting RFC1918_STRICT=Yes in shorewall.conf will cause such + traffic to be logged and dropped since while the packet's source + matches the RETURN rule, the packet's destination matches the + 'logdrop' rule. + + If not specified or specified as empty (e.g., + RFC1918_STRICT="") then RFC1918_STRICT=No is assumed. + + + RFC1918_STRICT=Yes requires that your kernel and iptables + support 'Connection Tracking' match. + + + + + + ROUTE_FILTER + + + If this parameter is given the value Yes or + yes then route filtering (anti-spoofing) is enabled + on all network interfaces which are brought up while Shorewall is in + the started state. The default value is no. + + + + + SHOREWALL_SHELL + + + This parameter is used to specify the shell program to be used + to interpret the firewall script (/usr/share/shorewall/firewall). If + not specified or specified as a null value, /bin/sh is + assumed. @@ -3392,134 +3777,26 @@ $FW chld ACCEPT - MODULE_SUFFIX + STARTUP_ENABLED - The value of this variable determines the possible file - extensions of kernel modules. The default value is "o gz ko and - o.gz". See for more details. + When set to Yes or yes, Shorewall may be started. Used as + guard against Shorewall being accidentally started before it has + been configured. - ADMINISABSENTMINDED + SUBSYSLOCK - The value of this variable affects Shorewall's stopped state. - When ADMINISABSENTMINDES=No, only traffic to/from those addresses - listed in /etc/shorewall/routestopped is accepted when Shorewall is - stopped. When ADMINISABSENTMINDED=Yes, in addition to traffic - to/from addresses in - /etc/shorewall/routestopped, connections that - were active when Shorewall stopped continue to work and all new - connections from the firewall system itself are allowed. If this - variable is not set or is given the empty value then - ADMINISABSENTMINDED=No is assumed. - - - - - SHOREWALL_SHELL - - - This parameter is used to specify the shell program to be used - to interpret the firewall script (/usr/share/shorewall/firewall). If - not specified or specified as a null value, /bin/sh is - assumed. - - - - - IPTABLES - - - This parameter names the iptables executable to be used by - Shorewall. If not specified or if specified as a null value, then - the iptables executable located using the PATH option is - used. - - - - - LOGFORMAT - - - The value of this variable generate the --log-prefix setting - for Shorewall logging rules. It contains a printf - formatting template which accepts three arguments (the chain name, - logging rule number (optional) and the disposition). To use - LOGFORMAT with fireparse, set it as: - - LOGFORMAT="fp=%s:%d a=%s " - - If the LOGFORMAT value contains the substring - %d then the logging rule number is calculated and - formatted in that position; if that substring is not included then - the rule number is not included. If not supplied or supplied as - empty (LOGFORMAT="") then Shorewall:%s:%s: is - assumed. - - - /sbin/shorewall uses the leading part of - the LOGFORMAT string (up to but not including the first - %) to find log messages in the show - log, status and hits - commands. This part should not be omitted (the LOGFORMAT should - not begin with %) and the leading part should be - sufficiently unique for /sbin/shorewall to - identify Shorewall messages. - - - - - - CLEAR_TC - - - If this option is set to No then Shorewall - won't clear the current traffic control rules during [re]start. This - setting is intended for use by people that prefer to configure - traffic shaping when the network interfaces come up rather than when - the firewall is started. If that is what you want to do, set - TC_ENABLED=Yes and CLEAR_TC=No and do not supply an - /etc/shorewall/tcstart file. That way, your - traffic shaping rules can still use the fwmark - classifier based on packet marking defined in - /etc/shorewall/tcrules. If not specified, CLEAR_TC=Yes is - assumed. - - - - - MARK_IN_FORWARD_CHAIN - - - If your kernel has a FORWARD chain in the mangle table, you - may set MARK_IN_FORWARD_CHAIN=Yes to cause the marking specified in - the tcrules file to - occur in that chain rather than in the PREROUTING chain. This - permits you to mark inbound traffic based on its destination address - when SNAT or Masquerading are in use. To determine if your kernel - has a FORWARD chain in the mangle table, use the - /sbin/shorewall show mangle - command; if a FORWARD chain is displayed then your kernel will - support this option. If this option is not specified or if it is - given the empty value (e.g., MARK_IN_FORWARD_CHAIN="") then - MARK_IN_FORWARD_CHAIN=No is assumed. - - - - - RFC1918_LOG_LEVEL - - - This parameter determines the level at which packets logged - under the norfc1918 - mechanism are logged. The value must be a valid syslog level and if no level is - given, then info is assumed. + This parameter should be set to the name of a file that the + firewall should create if it starts successfully and remove when it + stops. Creating and removing this file allows Shorewall to work with + your distribution's initscripts. For RedHat, this should be set to + /var/lock/subsys/shorewall. For Debian, the value is + /var/state/shorewall and in LEAF it is /var/run/shorwall. Example: + SUBSYSLOCK=/var/lock/subsys/shorewall. @@ -3550,333 +3827,40 @@ $FW chld ACCEPT - MACLIST_DISPOSITION + USE_ACTIONS (Added in version 3.4.0) - Determines the disposition of connections requests that fail - MAC Verification and must - have the value ACCEPT (accept the connection request anyway), REJECT - (reject the connection request) or DROP (ignore the connection - request). If not set or if set to the empty value (e.g., - MACLIST_DISPOSITION="") then MACLIST_DISPOSITION=REJECT is - assumed. + If set to 'Yes' (the default) then user-defined and standard + actions may be used. If set to 'No', only built-in actions may be + used. See the action documentation + for additional information. + + If this option is not set, or if it is set to the empty value, + then USE_ACTIONS=Yes is assumed. - MACLIST_LOG_LEVEL + VERBOSITY (Added in version 3.2.0) - Determines the syslog - level for logging connection requests that fail MAC Verification. The value must - be a valid syslogd log level. If you don't want to log these - connection requests, set to the empty value (e.g., - MACLIST_LOG_LEVEL=""). - - + Shorewall has traditionally been very noisy (produced lots of + output). You may now set the default level of verbosity using the + VERBOSITY OPTION. - - LOG_MARTIANS + Values are: - - If set to Yes or yes, sets - /proc/sys/net/ipv4/conf/all/log_martians and - /proc/sys/net/ipv4/conf/default/log_martians to - 1. Default is which sets both of the above to zero. If you do not - enable martian logging for all interfaces, you may still enable it - for individual interfaces using the logmartians interface option in /etc/shorewall/interfaces. - - + + 0 — Silent. You may make it more verbose using the -v + option - - DETECT_DNAT_ADDRS + 1 — Major progress messages displayed - - If set to Yes or yes, Shorewall - will detect the first IP address of the interface to the source zone - and will include this address in DNAT rules as the original - destination IP address. If set to No or - no, Shorewall will not detect this address and any - destination IP address will match the DNAT rule. If not specified or - empty, DETECT_DNAT_ADDRS=Yes is assumed. - - + 2 — All progress messages displayed (old default + behavior) + - - NAT_BEFORE_RULES - - - If set to No or no, port - forwarding rules can override the contents of the file. If set to Yes or - yes, port forwarding rules cannot override one-to-one - NAT. If not set or set to an empty value, Yes is - assumed. - - - - - SUBSYSLOCK - - - This parameter should be set to the name of a file that the - firewall should create if it starts successfully and remove when it - stops. Creating and removing this file allows Shorewall to work with - your distribution's initscripts. For RedHat, this should be set to - /var/lock/subsys/shorewall. For Debian, the value is - /var/state/shorewall and in LEAF it is /var/run/shorwall. Example: - SUBSYSLOCK=/var/lock/subsys/shorewall. - - - - - MODULESDIR - - - This parameter specifies the directory/directories where your - kernel netfilter modules may be found. If you leave the variable - empty, Shorewall will supply the value "/lib/modules/`uname - -r`/kernel/net/ipv4/netfilter" in versions of Shorewall prior to - 3.2.4 and "/lib/modules/`uname - -r`/kernel/net/ipv4/netfilter:/lib/modules/`uname - -r`/kernel/net/ipv4/netfilter" in later versions. - - - - - LOGRATE and LOGBURST - - - These parameters set the match rate and initial burst size for - logged packets. Please see the iptables man page for a description - of the behavior of these parameters (the iptables option --limit is - set by LOGRATE and --limit-burst is set by LOGBURST). If both - parameters are set empty, no rate-limiting will occur. - - - - - LOGRATE=10/minute -LOGBURST=5 - - 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 without matching a packet, 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. - - - - - - LOGFILE - - - This parameter tells the /sbin/shorewall program where to look - for Shorewall messages when processing the show log, - monitor, status and - hits commands. If not assigned or if assigned an - empty value, /var/log/messages is assumed. - - - - - IP_FORWARDING - - - This parameter determines whether Shorewall enables or - disables IPV4 Packet Forwarding (/proc/sys/net/ipv4/ip_forward). - Possible values are: - - - - On or on - - - packet forwarding will be enabled. - - - - - Off or off - - - packet forwarding will be disabled. - - - - - Keep or keep - - - Shorewall will neither enable nor disable packet - forwarding. - - - - - If this variable is not set or is given an empty value - (IP_FORWARD="") then IP_FORWARD=On is assumed. - - - - - ADD_IP_ALIASES - - - This parameter determines whether Shorewall automatically adds - the external address(es) in . If the variable is set to Yes or - yes then Shorewall automatically adds these aliases. - If it is set to No or no, you must add - these aliases yourself using your distribution's network - configuration tools. - - If this variable is not set or is given an empty value - (ADD_IP_ALIASES="") then ADD_IP_ALIASES=Yes is assumed. - - - Addresses added by ADD_IP_ALIASES=Yes are deleted and - re-added during shorewall restart. As a - consequence, connections using those addresses may be - severed. - - - - - - ADD_SNAT_ALIASES - - - This parameter determines whether Shorewall automatically adds - the SNAT ADDRESS in . If - the variable is set to Yes or yes then - Shorewall automatically adds these addresses. If it is set to - No or no, you must add these addresses - yourself using your distribution's network configuration - tools. - - If this variable is not set or is given an empty value - (ADD_SNAT_ALIASES="") then ADD_SNAT_ALIASES=No is assumed. - - - Addresses added by ADD_SNAT_ALIASES=Yes are deleted and - re-added during shorewall restart. As a - consequence, connections using those addresses may be - severed. - - - - - - RETAIN_ALIASES - - - During "shorewall start", IP addresses to be added as a - consequence of ADD_IP_ALIASES=Yes and ADD_SNAT_ALIASES=Yes are - quietly deleted when /etc/shorewall/nat - and /etc/shorewall/masq are processed - then are re-added later. This is done to help ensure that the - addresses can be added with the specified labels but can have the - undesirable side effect of causing routes to be quietly deleted. - When RETAIN_ALIASES is set to Yes, existing addresses will not be - deleted. Regardless of the setting of RETAIN_ALIASES, addresses - added during "shorewall start" are still deleted at a subsequent - "shorewall stop" or "shorewall restart". - - - - - LOGUNCLEAN - - - This parameter determines the logging level of mangled/invalid - packets controlled by the dropunclean" and - "logunclean interface options. If LOGUNCLEAN is empty - (LOGUNCLEAN=) then packets selected by dropclean are - dropped silently (logunclean packets are logged under - the info log level). Otherwise, these packets are - logged at the specified level (Example: LOGUNCLEAN=debug). - - - - - BLACKLIST_DISPOSITION - - - This parameter determines the disposition of packets from - blacklisted hosts. It may have the value DROP if the packets are to - be dropped or REJECT if the packets are to be replied with an ICMP - port unreachable reply or a TCP RST (tcp only). If you do not assign - a value or if you assign an empty value then DROP is assumed. - - - - - BLACKLIST_LOGLEVEL - - - This parameter determines if packets from blacklisted hosts - are logged and it determines the syslog level that they are to be - logged at. Its value is a syslog - level (Example: BLACKLIST_LOGLEVEL=debug). If you do not - assign a value or if you assign an empty value then packets from - blacklisted hosts are not logged. - - - - - DELAYBLACKLISTLOAD - - - Users with a large static black list - (/etc/shorewall/blacklist) may want to set the - DELAYBLACKLISTLOAD option to Yes. When DELAYBLACKLISTLOAD=Yes, - Shorewall will enable new connections before loading the blacklist - rules. While this may allow connections from blacklisted hosts to - slip by during construction of the blacklist, it can substantially - reduce the time that all new connections are disabled during - shorewall [re]start. - - - - - CLAMPMSS[=<value>] - - - This parameter enables the TCP Clamp MSS to PMTU feature of - Netfilter and is usually required when your internet connection is - through PPPoE or PPTP. If set to Yes or - yes, the feature is enabled. If left blank or set to - No or no, the feature is not - enabled. - - - This option requires CONFIG_IP_NF_TARGET_TCPMSS in your kernel. - - - You may also set CLAMPMSS to a numeric value (e.g., - CLAMPMSS=1400). This will set the MSS field in TCP SYN packets going - through the firewall to the value that you specify. - - - - - ROUTE_FILTER - - - If this parameter is given the value Yes or - yes then route filtering (anti-spoofing) is enabled - on all network interfaces which are brought up while Shorewall is in - the started state. The default value is no. + If not specified, then 2 is assumed.