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.
+