diff --git a/docs/Shorewall-4.xml b/docs/Shorewall-4.xml index 5e31e1ce4..15b6e4a7f 100644 --- a/docs/Shorewall-4.xml +++ b/docs/Shorewall-4.xml @@ -49,7 +49,7 @@ - Shorewall ran the iptables utility to add + Shorewall has run the iptables utility to add each Netfilter rule. @@ -73,6 +73,15 @@ iptables-restore; so the script is very fast. + + + generates better and more consistent error messages. + + + + does a much more thorough job of checking the configuration to + avoid run-time errors. + Both compilers may be installed on your system and you can use @@ -157,375 +166,8 @@ Compiler The Shorewall-perl compiler is not 100% compatible with the - Shorewall-shell version. - - - - The Perl-based compiler requires the following capabilities in - your kernel and iptables. - - - - addrtype match (may be relaxed later) - - - - multiport match (will not be relaxed) - - - - These capabilities are in current distributions. - - - - Now that Netfilter has features to deal reasonably with port - lists, I see no reason to duplicate those features in Shorewall. The - Shorewall-shell compiler goes to great pain (in some cases) to break - very long port lists ( > 15 where port ranges in lists count as two - ports) into individual rules. In the new compiler, I'm avoiding the - ugliness required to do that. The new compiler just generates an error - if your list is too long. It will also produce an error if you insert - a port range into a port list and you don't have extended multiport - support. - - - - BRIDGING=Yes is not supported. The kernel code necessary to - support this option was removed in Linux kernel 2.6.20. - - - - The BROADCAST column in the interfaces file is essentially - unused; if you enter anything in this column but '-' or 'detect', you - will receive a warning. This will be relaxed if and when the addrtype - match requirement is relaxed. - - - - The 'refresh' command is now synonymous with 'restart'. - - - - With the shell-based compiler, extension scripts were copied - into the compiled script and executed at run-time. In many cases, this - approach doesn't work with Shorewall Perl because (almost) the entire - ruleset is built by the compiler. As a result, Shorewall-perl runs - many extension scripts at compile-time rather than at run-time. - Because the compiler is written in Perl, your extension scripts from - earlier versions will no longer work. - - The following table summarizes when the various extension - scripts are run: - - - - Compile-time - - Run-time - - Eliminated - - - - initdone - - clear - - continue - - - - maclog - - initdone - - refresh - - - - Per-chain (including those associated with - actions) - - start - - - - - - - - started - - - - - - - - stop - - - - - - - - stopped - - - - - - - - tcclear - - - - - - - - Compile-time extension scripts are executed using the Perl 'eval - `cat <file>`' mechanism. Be sure that each script returns a - 'true' value; otherwise, the compiler will assume that the script - failed and will abort the compilation. - - When a script is invoked, the $chainref scalar variable will hold a reference - to a chain table entry. - - - $chainref->{name} - contains the name of the chain - - $chainref->{table} holds - the table name - - - To add a rule to the chain: - - - add_rule $chainref, <the - rule> - - - Where - - - <the rule> is a scalar - argument holding the rule text. Do not include "-A - <chain name>" - - - Example: - - - add_rule $chainref, '-j ACCEPT'; - - - To insert a rule into the chain: - - - insert_rule $chainref, - <rulenum>, <the - rule> - - - The log_rule_limit function works like it does in the shell - compiler with two exceptions: - - - - You pass the chain reference rather than the name of the - chain. - - - - The commands are 'add' and 'insert' rather than '-A' and - '-I'. - - - - There is only a single "pass as-is to iptables" argument (so - you must quote that part - - - - Example: - - log_rule_limit - 'info' , - $chainref , - $chainref->{name}, - 'DROP' , - '', #Limit - '' , #Log tag - 'add' - '-p tcp '; - - Here is an example of an actual initdone script used with - Shorewall 3.4:run_iptables -t mangle -I PREROUTING -p esp -j MARK --set-mark 0x50 -run_iptables -t filter -I INPUT -p udp --dport 1701 -m mark --mark 0x50 -j ACCEPT -run_iptables -t filter -I OUTPUT -p udp --sport 1701 -j ACCEPT - - - Here is the corresponding script used with - Shorewall-perl:use Shorewall::Chains; - -insert_rule $mangle_table->{PREROUTING}, 1, "-p esp -j MARK --set-mark 0x50"; -insert_rule $filter_table->{INPUT}, 1, "-p udp --dport 1701 -m mark --mark 0x50 -j ACCEPT"; -insert_rule $filter_table->{OUTPUT}, 1, "-p udp --sport 1701 -j ACCEPT"; - -1; - - The initdone script is unique because the $chainref variable is - not set before the script is called. The above script illustrates how - the $mangle_table, $filter_table, and $nat_table references can be - used to add or insert rules in arbitrary chains. - - - - The /etc/shorewall/tos file now has - zone-independent SOURCE and DEST columns as do all other files except - the rules and policy files. - - The SOURCE column may be one of the following: - - - [all:]<address>[,...] - - [all:]<interface>[:<address>[,...]] - - $FW[:<address>[,...]] - - - The DEST column may be one of the following: - - - [all:]<address>[,...] - - [all:]<interface>[:<address>[,...]] - - - This is a permanent change. The old zone-based rules have never - worked right and this is a good time to replace them. I've tried to - make the new syntax cover the most common cases without requiring - change to existing files. In particular, it will handle the tos file - released with Shorewall 1.4 and earlier. - - - - Currently, support for ipsets is lightly tested. That will - change with future pre-releases but one thing is certain -- Shorewall - is now out of the ipset load/reload business. With scripts generated - by the Perl-based Compiler, the Netfilter ruleset is never cleared. - That means that there is no opportunity for Shorewall to load/reload - your ipsets since that cannot be done while there are any current - rules using ipsets. - - So: - - - - Your ipsets must be loaded before Shorewall starts. You are - free to try to do that with the following code in - /etc/shorewall/start: - - if [ "$COMMAND" = start ]; then - ipset -U :all: :all: - ipset -F - ipset -X - ipset -R < /etc/shorewall/ipsets -fi - - The file /etc/shorewall/ipsets will - normally be produced using the ipset -S - command. - - The above will work most of the time but will fail in a - shorewall stop - shorewall - start sequence if you use ipsets in your routestopped - file (see below). - - - - Your ipsets may not be reloaded until Shorewall is stopped - or cleared. - - - - If you specify ipsets in your routestopped file then - Shorewall must be cleared in order to reload your ipsets. - - - - As a consequence, scripts generated by the Perl-based compiler - will ignore /etc/shorewall/ipsets and will issue - a warning if you set SAVE_IPSETS=Yes in - shorewall.conf. - - - - Because the configuration files (with the exception of - /etc/shorewall/params) are now processed by the - Shorewall-perl compiler rather than by the shell, only the basic forms - of Shell expansion ($variable and ${variable}) are supported. The more - exotic forms such as ${variable:=default} are not supported. Both - variables defined in /etc/shorewall/params and environmental variables - (exported by the shell) can be used in configuration files. - - - - USE_ACTIONS=No is not supported. That option is intended to - minimize Shorewall's footprint in embedded applications. As a - consequence, Default Macros are not supported. - - - - DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset is - atomically loaded with one execution of - iptables-restore. - - - - MAPOLDACTIONS=Yes is not supported. People should have converted - to using macros by now. - - - - The pre Shorewall-3.0 format of the zones file is not supported; - neither is the /etc/shorewall/ipsec file. - - - - BLACKLISTNEWONLY=No is not permitted with FASTACCEPT=Yes. This - combination doesn't work in previous versions of Shorewall so the - Perl-based compiler simply rejects it. - - - - Shorewall-perl has a single rule generator that is used for all - rule-oriented files. So it is important that the syntax is consistent - between files. - - With shorewall-shell, there is a special syntax in the SOURCE - column of /etc/shorewall/masq to designate "all traffic entering the - firewall on this interface except...". - - Example:#INTERFACE SOURCE ADDRESSES -eth0 eth1!192.168.4.9 ...Shorewall-perl - uses syntax that is consistent with the rest of - Shorewall:#INTERFACE SOURCE ADDRESSES -eth0 eth1:!192.168.4.9 ... - - - - The 'allowoutUPnP' built-in action is no longer supported. In - kernel 2.6.14, the Netfilter team have removed support for '-m owner - --owner-cmd' which that action depended on. - - + Shorewall-shell version. See this + document for details.
diff --git a/docs/Shorewall-perl.xml b/docs/Shorewall-perl.xml index b1fa99e48..5e3ad9985 100644 --- a/docs/Shorewall-perl.xml +++ b/docs/Shorewall-perl.xml @@ -409,10 +409,9 @@ fi the Shorewall-perl compiler rather than by the shell, only the basic forms of Shell expansion ($variable and ${variable}) are supported. The more exotic forms such as ${variable:=default} are - not supported. Both variables defined in - /etc/shorewall/params and environmental - variables (exported by the shell) can be used in configuration - files. + not supported. Both variables defined in /etc/shorewall/params and + environmental variables (exported by the shell) can be used in + configuration files. @@ -423,8 +422,8 @@ fi DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset - (with the exception of the dynamic blacklist) is atomically loaded - with one execution of iptables-restore. + is atomically loaded with one execution of + iptables-restore. @@ -446,7 +445,7 @@ fi Shorewall-perl has a single rule generator that is used for - all rule-oriented files. So it is important that the syntax be + all rule-oriented files. So it is important that the syntax is consistent between files. With shorewall-shell, there is a special syntax in the @@ -467,6 +466,12 @@ eth0 eth1:!192.168.4.9 ... + + + Shorewall-perl is dependent on Perl (see the next section) which + has a large disk footprint. This makes Shorewall-perl less desirable + in an embedded environment. +