From 61299557a9f99a09062661d5983533b648ca522d Mon Sep 17 00:00:00 2001 From: teastep Date: Sat, 17 Jan 2009 17:13:54 +0000 Subject: [PATCH] Update the Shorewall-perl and Shorewall-4 docs with more IPv6 info git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9299 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- docs/Shorewall-4.xml | 64 +++++++++++++--------- docs/Shorewall-perl.xml | 88 ++++++++++++++++++++++-------- docs/configuration_file_basics.xml | 8 +-- 3 files changed, 106 insertions(+), 54 deletions(-) diff --git a/docs/Shorewall-4.xml b/docs/Shorewall-4.xml index 514482b47..b9ccd78a3 100644 --- a/docs/Shorewall-4.xml +++ b/docs/Shorewall-4.xml @@ -99,33 +99,36 @@ - Shorewall-shell - the old shell-based compiler and related - components. + Shorewall-shell - the old + shell-based compiler and related components. - Shorewall-perl - the new Perl-based compiler. + Shorewall-perl - the new + Perl-based compiler. - Shorewall-common - the part of Shorewall common to both - compilers. + Shorewall-common - the part of + Shorewall common to both compilers. - Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can - run scripts generated by either Shorewall-perl or - Shorewall-shell. + Shorewall-lite- same as the 3.4 + version of Shorewall Lite. Can run scripts generated by either + Shorewall-perl or Shorewall-shell. - Shorewall6 - The utilities for creating and operating an Ipv6 - firewall. Requires Shorewall-perl. + Shorewall6 - The utilities for + creating and operating an Ipv6 firewall. Requires Shorewall-perl and + Shorewall-common. - Shorewall6-lite - Ipv6 equivalent of Shorewall Lite. Can run - scripts generated by Shoreall-perl 4.2.4 and later. + Shorewall6-lite - Ipv6 + equivalent of Shorewall Lite. Can run scripts generated by + Shoreall-perl 4.2.4 and later. @@ -143,32 +146,43 @@ - Perl (I use Perl 5.8.8 but other 5.8 versions should work - fine) + Perl (I use Perl 5.8.8 but other 5.8 versions should work fine). + + If you want to be able to use DNS names in your Shorewall6 + configuration files, then Perl 5.10 is required together with the + Perl Socket6 module. + - Perl Cwd Module + Perl Cwd Module - Perl File::Basename Module + Perl File::Basename + Module - Perl File::Temp Module + Perl File::Temp Module - Perl Getopt::Long Module + Perl Getopt::Long Module - Perl Carp Module + Perl Carp Module - Perl FindBin Module (Shorewall 4.0.3 and later) + Perl FindBin Module (Shorewall + 4.0.3 and later) + + + + Perl Scalar::Util Module + (Shorewall 4.0.6 and later) @@ -188,8 +202,8 @@ If you only install one compiler, then that compiler will be used. - If you install both compilers, then the compiler actually used - depends on the SHOREWALL_COMPILER setting in + If you install both compilers, then the compiler actually used for + IPv4 depends on the SHOREWALL_COMPILER setting in shorewall.conf. The value of this new option can be either 'perl' or 'shell'. @@ -204,8 +218,8 @@ If you only install one compiler, it is suggested that you do not set SHOREWALL_COMPILER. - You can select the compiler to use on the command line using the 'C - option: + If both compilers are installed, you can select the compiler to use + on the command line using the 'C option: '-C shell' means use the shell compiler '-C perl' means use the perl compiler @@ -215,7 +229,7 @@ Example:shorewall restart -C perl When the Shorewall-perl compiler has been selected, the - params file is processed using the + params file is processed using the shell option which causes all variables set within the file to be exported automatically by the shell. The Shorewall-perl compiler uses the current environmental variables to perform variable expansion diff --git a/docs/Shorewall-perl.xml b/docs/Shorewall-perl.xml index a4863e745..b2004b526 100644 --- a/docs/Shorewall-perl.xml +++ b/docs/Shorewall-perl.xml @@ -53,7 +53,8 @@ The script generated by the compiler uses iptables-restore to instantiate the Netfilter configuration. So it runs much faster than the script generated by the - Shorewall-shell compiler. + Shorewall-shell compiler and doesn't stop new connections during + shorewall restart. @@ -78,8 +79,8 @@
Shorewall-perl - The down side - While there are advantages to using Shorewall-perl, there are also - disadvantages. + While there are significant advantages to using Shorewall-perl, + there are also disadvantages.
Incompatibilities @@ -112,10 +113,12 @@ 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. + the ugliness required to do that for source port lists. The new + compiler just generates an error if your source list is too long + (beginning with Shorewall 4.0.5, the compiler will break rules with + a long destination port list into multiple rules).. It will also + produce an error if you insert a port range into a port list and you + don't have extended multiport support. @@ -164,7 +167,7 @@ extension scripts from earlier versions will no longer work. The following table summarizes when the various extension - scripts are run: + scripts are run: @@ -228,8 +231,8 @@ 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. + returns a 'true' value; otherwise, the Shorweall-perl compiler will + assume that the script failed and will abort the compilation. When a script is invoked, the $chainref scalar variable will usually hold a @@ -385,12 +388,18 @@ fi The file /etc/shorewall/ipsets will normally be produced using the ipset -S - command. + command. I have this in my + /etc/shorewall/stop file: - 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). + if ipset -S > /etc/shorewall/ipsets.tmp; then + mv -f /etc/shorewall/ipsets /etc/shorewall/ipsets.bak + mv /etc/shorewall/ipsets.tmp /etc/shorewall/ipsets +fi + + The above extension scripts 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). @@ -424,7 +433,8 @@ fi 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. + consequence, Default Macros are not supported by + Shorewall-perl. @@ -452,8 +462,8 @@ fi 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. + all rule-oriented files. This implementation enforces consistency of + syntax between files. With shorewall-shell, there is a special syntax in the SOURCE column of /etc/shorewall/masq to designate "all traffic entering the @@ -489,6 +499,10 @@ eth0 eth1:!192.168.4.9 ... #SOURCE DEST POLICY LOG LEVEL all all REJECT info loc net ACCEPT + + Shorewall-shell silently accepts the above even though the + loc->net policy is useless. Shorewall-perl generates a fatal + compilation error. @@ -533,17 +547,19 @@ ACCEPT loc:eth0:192.168.1.3,eth0:192.168.1.5 $fw tcp 22 DNAT- net loc:192.168.1.3 tcp 21 you instead want:#ACTION SOURCE DEST PROTO DEST PORT(S) -DNAT- net 192.168.1.3 tcp 21 +DNAT- net 192.168.1.3 tcp 21
- Dependence on Perl + Dependence on Perl 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. + an embedded environment. The best way to work around this limitation is + to install Shorewall-perl on an administrative system and employ + Shorewall-lite on your embedded systems.
@@ -554,6 +570,12 @@ DNAT- net 192.168.1.3 tcp 21 Perl (I use Perl 5.8.8 but other 5.8 or later versions should work fine) + + + If you want to be able to use DNS names in your Shorewall6 + configuration files, then Perl 5.10 is required together with the + Perl Socket6 module. + @@ -715,6 +737,13 @@ DNAT- net 192.168.1.3 tcp 21Added in Shorewall 4.1. If given, controls the verbosity of logging to the log specified by the --log parameter. + + --family=4|6 + + + Added in Shorewall 4.2.4. Specifies whether an IPv4 or an IPv6 + firewall is to be created. + Example (compiles the configuration in the current directory generating a script named 'firewall' and using VERBOSITY 2)./usr/share/shorewall-perl/compiler.pl -v 2 -d . firewall @@ -891,6 +920,14 @@ set +a Log Verbosity; range -1 to 2. + + + family + + + Address family: 4 or 6 + + Those parameters that are supplied must have defined values. @@ -912,6 +949,8 @@ set +a log '' log_verbosity -1 + + family 4 Example: use lib '/usr/share/shorewall-perl/'; @@ -957,8 +996,9 @@ my $chainref7 = $filter_table{$name};Shorewall::Chains is Reference to the 'nat' portion of the table - ($chain_table{nat}). This is a hash whose key is the chain - name. + ($chain_table{nat}). This is a hash whose key is the chain name. + This variable is not set when an IPv6 firewall is being + created. @@ -1172,7 +1212,7 @@ progress_message "This will only be seen if VERBOSITY >= 2"; progress_message2 "This will only be seen if VERBOSITY >= 1"; progress_message3 "This will be seen unless VERBOSITY < 0"; The shorewall() function may - be optionally included.use lib '/usr/share/shorewall-perl'; + be optionally included:use lib '/usr/share/shorewall-perl'; use Shorewall::Config qw/shorewall/; shorewall $config_file_entry;The Shorewall::Config module diff --git a/docs/configuration_file_basics.xml b/docs/configuration_file_basics.xml index 2be565353..0cf191165 100644 --- a/docs/configuration_file_basics.xml +++ b/docs/configuration_file_basics.xml @@ -989,11 +989,9 @@ DNAT net loc:192.168.1.3 tcp 4000:4100 Shorewall-perl requires multiport match in order to accept port lists in Shorewall configuration files. It further requires Extended multiport - match in order to accept port ranges in port lists. Shorewall-perl will - never break a list longer than 15 ports (with each range counting as two - ports) into smaller lists. So you must be sure that your port lists can - be handled directly by the Netfilter/iptables capabilities - available. + match in order to accept port ranges in port lists. Shorewall-perl + versions earlier than 4.0.5 will never break a list longer than 15 ports + (with each range counting as two ports) into smaller lists.