From bf390fe11e803eb073807f2cf4f3f0e75e18244b Mon Sep 17 00:00:00 2001 From: teastep Date: Mon, 25 Jun 2007 20:11:24 +0000 Subject: [PATCH] More Shorewall-4 Documentation Updates git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6673 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb --- docs/Shorewall-4.xml | 128 +++++++++++++++++--- docs/Shorewall-perl.xml | 142 ++++++++++++++++++++--- docs/shorewall_extension_scripts.xml | 84 +++++++++++++- docs/starting_and_stopping_shorewall.xml | 8 +- 4 files changed, 323 insertions(+), 39 deletions(-) diff --git a/docs/Shorewall-4.xml b/docs/Shorewall-4.xml index 3d8fd686d..5e31e1ce4 100644 --- a/docs/Shorewall-4.xml +++ b/docs/Shorewall-4.xml @@ -145,6 +145,10 @@ Perl Getopt::Long Module + + + Perl Carp Module + @@ -202,12 +206,90 @@ - Because the compiler is now written in Perl, your compile-time - extension scripts from earlier versions will no longer work. - 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. + 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 @@ -281,6 +363,26 @@ '' , #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. @@ -314,13 +416,13 @@ - Currently, support for ipsets is untested. 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. + 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: diff --git a/docs/Shorewall-perl.xml b/docs/Shorewall-perl.xml index 5e16ed487..b1fa99e48 100644 --- a/docs/Shorewall-perl.xml +++ b/docs/Shorewall-perl.xml @@ -137,21 +137,104 @@ - Because the compiler is now written in Perl, your - compile-time extension scripts from earlier versions will no - longer work. Compile-time extension scripts are executed using the - Perl 'eval `cat <file>`' mechanism. Be sure that each script + 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. + 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->{name} + contains the name of the chain - $chainref->{table} holds the table name + $chainref->{table} + holds the table name To add a rule to the chain: @@ -199,21 +282,42 @@ There is only a single "pass as-is to iptables" argument - (so you must quote that part). + (so you must quote that part Example: - log_rule_limit( - 'info' , - $chainref , - $chainref->{name}, - 'DROP' , - '', #Limit - '' , #Log tag - 'add', #Command - '-p tcp'); #Added 'as-is' to the generated rule + 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. diff --git a/docs/shorewall_extension_scripts.xml b/docs/shorewall_extension_scripts.xml index 098b4752f..f69c794ce 100644 --- a/docs/shorewall_extension_scripts.xml +++ b/docs/shorewall_extension_scripts.xml @@ -337,12 +337,84 @@ Shorewall-perl. Because the - compiler is now written in Perl, your compile-time extension scripts - from earlier versions will no longer work. 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. + compiler is written in Perl, some of your extension scripts from earlier + versions will no longer work because Shorewall-perl runs those extension + scripts at compile-time rather than at run-time. + + 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. All scripts will need to begin with the following line:use Shorewall::Chains; For more diff --git a/docs/starting_and_stopping_shorewall.xml b/docs/starting_and_stopping_shorewall.xml index c0b70493e..12887a8ba 100644 --- a/docs/starting_and_stopping_shorewall.xml +++ b/docs/starting_and_stopping_shorewall.xml @@ -187,7 +187,13 @@ To trace the execution of shorewall start and write the trace to the file /tmp/trace, you would - enter:shorewall trace start 2> /tmp/trace + enter:shorewall trace start 2> /tmp/trace + If you are running Shorewall-perl, the trace keyword does not result in a trace of + the execution of the Shorewall-perl compiler. It rather causes + additional diagnostic information to be included in warning and + error messages generated by the compiler. +