When compiling your firewall configuration, Shorewall copies most extension scripts directly into the "compiled" program where they are executed in-line during processing of the start, restart and restore commands. When copying a script, Shorewall indents the script to match the surrounding code; if you have 'awk' installed on the system where the configuration is being compiled, Shorewall can correctly handle line continuation in your script ("\" as the last character on a line). If you do not have awk, you may not use line continuation in your scripts. Also beware that quoted strings continued from one line to another will have extra whitespace inserted as a result of indentation.

Because the 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 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.

Beginning with Shorewall version 4.0.6, each compile-time script is implicitly prefaced with:

package Shorewall::User;

Most scripts will need to begin with the following line:

use Shorewall::Chains;

For more complex scripts, you may need to 'use' other Shorewall Perl modules -- browse /usr/share/shorewall-perl/Shorewall/ to see what's available.

When a script is invoked, the $chainref scalar variable will hold a reference to a chain table entry.

To add a rule to the chain:

add_rule( $chainref, <the rule> );

Where

Example:

add_rule( $chainref, '-j ACCEPT' );

Beginning with Shorewall 4.0.5, add_rule() accepts an optional third argument; If that argument evaluates to true and the passed rule contains a --dports list with more than 15 ports (a port range counts as two ports), the rule will be split into multiple rules where each resulting rule has 15 or fewer ports in its --dports list.

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 three exceptions:

Example:

log_rule_limit(
               'info' , 
               $chainref ,            
               $chainref->{name},
               'DROP' , 
               '',      #Limit
               '' ,     #Log tag
               'add',   #Command
               '-p tcp' #Pass as-is
               );

Note that in the 'initdone' script, there is no default chain ($chainref). You can obtain a reference to a standard chain by:

my $chainref = $chain_table{<table>}{<chain name>};

Example:

my $chainref = $chain_table{filter}{INPUT};

You can also use the hash references $filter_table, $mangle_table and $nat_table to access chain references in the three main tables.

Example:

my $chainref = $filter_table->{INPUT}; #Same as above with a few less keystrokes; runs faster too

The 'continue' script has been eliminated because it no longer make any sense under Shorewall-perl. That script was designed to allow you to add special temporary rules during [re]start. Shorewall-perl doesn't need such rules since the ruleset is instantianted atomically by table.