diff --git a/docs/shorewall_extension_scripts.xml b/docs/shorewall_extension_scripts.xml index a8164bef3..fec5bad05 100644 --- a/docs/shorewall_extension_scripts.xml +++ b/docs/shorewall_extension_scripts.xml @@ -5,7 +5,7 @@ - Extension Scripts and Default Actions + Extension Scripts @@ -34,182 +34,185 @@ - - This article applies to Shorewall 3.0 and - later. If you are running a version of Shorewall earlier than Shorewall - 3.0.0 then please see the documentation for that - release. - +
+ Extension Scripts - Extension scripts are user-provided scripts that are invoked at - various points during firewall start, restart, stop and clear. The scripts - are placed in /etc/shorewall and are processed using the Bourne shell - source mechanism. + Extension scripts are user-provided scripts that are invoked at + various points during firewall start, restart, stop and clear. The scripts + are placed in /etc/shorewall and are processed using the Bourne shell + source mechanism. - - + + + + Be sure that you actually need to use an extension script to + do what you want. Shorewall has a wide range of features that cover + most requirements. + + + + DO NOT SIMPLY COPY RULES THAT YOU FIND ON THE NET INTO AN + EXTENSION SCRIPT AND EXPECT THEM TO WORK AND TO NOT BREAK SHOREWALL. + TO USE SHOREWALL EXTENSION SCRIPTS YOU MUST KNOW WHAT YOU ARE DOING + WITH RESPECT TO iptables/Netfilter AND SHOREWALL. + + + + + The following scripts can be supplied: + + - Be sure that you actually need to use an extension script to do - what you want. Shorewall has a wide range of features that cover most - requirements. + init -- invoked early in shorewall start and + shorewall restart - DO NOT SIMPLY COPY RULES THAT YOU FIND ON THE NET INTO AN - EXTENSION SCRIPT AND EXPECT THEM TO WORK AND TO NOT BREAK SHOREWALL. - TO USE SHOREWALL EXTENSION SCRIPTS YOU MUST KNOW WHAT YOU ARE DOING - WITH RESPECT TO iptables/Netfilter AND SHOREWALL. + initdone -- invoked after Shorewall has flushed all existing + rules but before any rules have been added to the builtin + chains. - - - The following scripts can be supplied: + + start -- invoked after the firewall has been started or + restarted. + - - - init -- invoked early in shorewall start and - shorewall restart - + + started -- invoked after the firewall has been marked as + 'running'. + - - initdone -- invoked after Shorewall has flushed all existing rules - but before any rules have been added to the builtin chains. - + + stop -- invoked as a first step when the firewall is being + stopped. + - - start -- invoked after the firewall has been started or - restarted. - + + stopped -- invoked after the firewall has been stopped. + - - started -- invoked after the firewall has been marked as - 'running'. - + + clear -- invoked after the firewall has been cleared. + - - stop -- invoked as a first step when the firewall is being - stopped. - + + refresh -- invoked while the firewall is being refreshed but + before the blacklst chains have been rebuilt. + - - stopped -- invoked after the firewall has been stopped. - + + refreshed -- invoked after the firewall has been + refreshed. + - - clear -- invoked after the firewall has been cleared. - + + continue -- invoked to allow you to insert special rules to + allow traffic while Shorewall is [re]starting. Any rules added in this + script should be deleted in your start script. + This script is invoked earlier in the [re]start process than is the + initdone script described above (Not used by + Shorewall Perl). + - - refresh -- invoked while the firewall is being refreshed but - before the blacklst chains have been rebuilt. - + + maclog -- (Added in Shorewall version 3.2.5) invoked while mac + filtering rules are being created. It is invoked once for each + interface having 'maclist' specified and it is invoked just before the + logging rule is added to the current chain (the name of that chain + will be in $CHAIN). + + - - refreshed -- invoked after the firewall has been refreshed. - + If your version of Shorewall doesn't have the + file that you want to use from the above list, you can simply create the + file yourself. You can also supply a script with the same name + as any of the filter chains in the firewall and the script will be invoked + after the /etc/shorewall/rules file has been processed but before the + /etc/shorewall/policy file has been processed. - - continue -- invoked to allow you to insert special rules to allow - traffic while Shorewall is [re]starting. Any rules added in this script - should be deleted in your start script. This script - is invoked earlier in the [re]start process than is the - initdone script described above (Not used by - Shorewall Perl). - + There are a couple of special considerations for commands in + extension scripts: - - maclog -- (Added in Shorewall version 3.2.5) invoked while mac - filtering rules are being created. It is invoked once for each interface - having 'maclist' specified and it is invoked just before the logging - rule is added to the current chain (the name of that chain will be in - $CHAIN). - - + + + When you want to run iptables, use the + command run_iptables instead. + run_iptables will run the iptables utility passing + the arguments to run_iptables and if the command + fails, the firewall will be stopped (or restored from the last + save command, if any). + - If your version of Shorewall doesn't have the - file that you want to use from the above list, you can simply create the - file yourself. You can also supply a script with the same name as - any of the filter chains in the firewall and the script will be invoked - after the /etc/shorewall/rules file has been processed but before the - /etc/shorewall/policy file has been processed. + + If you wish to generate a log message, use log_rule_limit. Parameters are: - There are a couple of special considerations for commands in extension - scripts: + + + Log Level + - - - When you want to run iptables, use the command - run_iptables instead. run_iptables - will run the iptables utility passing the arguments to - run_iptables and if the command fails, the firewall - will be stopped (or restored from the last save - command, if any). - + + Chain to insert the rule into + - - If you wish to generate a log message, use log_rule_limit. Parameters are: + + Chain name to display in the message (this can be different + from the preceding argument — see the Port Knocking article for an + example of how to use this). + - - - Log Level - + + Disposition to report in the message (ACCEPT, DROP, + etc) + - - Chain to insert the rule into - + + Rate Limit (if passed as "" then $LOGLIMIT is assumed — see + the LOGLIMIT option in /etc/shorewall/shorewall.conf) + - - Chain name to display in the message (this can be different - from the preceding argument — see the Port Knocking article for an example - of how to use this). - + + Log Tag ("" if none) + - - Disposition to report in the message (ACCEPT, DROP, - etc) - + + Command (-A or -I for append or insert). + - - Rate Limit (if passed as "" then $LOGLIMIT is assumed — see - the LOGLIMIT option in /etc/shorewall/shorewall.conf) - + + The remaining arguments are passed "as is" to + iptables + + + - - Log Tag ("" if none) - + + Many of the extension scripts get executed for both the + shorewall start and shorewall restart commands. You can determine + which command is being executed using the contents of $COMMAND. - - Command (-A or -I for append or insert). - - - - The remaining arguments are passed "as is" to iptables - - - - - - Many of the extension scripts get executed for both the shorewall - start and shorewall restart commands. You can determine which command is - being executed using the contents of $COMMAND. - - if [ $COMMAND = start ]; then + if [ $COMMAND = start ]; then ... - + + - - Shorewall versions 3.0.x and earlier - only. If you run commands other than - iptables that must be re-run in order to restore the - firewall to its current state then you must save the commands to the - restore file. The restore file is a temporary - file in /var/lib/shorewall that - will be renamed /var/lib/shorewall/restore-base at - the successful completion of the Shorewall command. The - shorewall save command combines + + +
+ Shorewall versions 3.0.x and earlier + + If you run commands other than iptables that + must be re-run in order to restore the firewall to its current state + then you must save the commands to the restore + file. The restore file is a temporary file in /var/lib/shorewall that will be renamed + /var/lib/shorewall/restore-base at the successful + completion of the Shorewall command. The shorewall + save command combines /var/lib/shorewall/restore-base with the output of iptables-save to produce the /var/lib/shorewall/restore script. @@ -247,21 +250,21 @@ file - +
- - Shorewall version 3.2.0 - 3.2.8 - only. 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. +
+ Shorewall version 3.2.0 - 3.2.8 + + 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. The /etc/shorewall/params script is @@ -285,21 +288,22 @@ processed by the compiler rather than copied into the compiled script. - +
- - Shorewall version 3.2.9 (3.4.0 RC2) and - later (Shorewall-shell). 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. +
+ Shorewall version 3.2.9 (3.4.0 RC2) and later + (Shorewall-shell) + + 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. The /etc/shorewall/params script is @@ -336,13 +340,15 @@ processed by the compiler rather than copied into the compiled script. - +
- - Shorewall-perl. 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. +
+ Shorewall-perl (Version 4.0.0 and later) + + 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: @@ -443,7 +449,9 @@ $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 + + + 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 @@ -490,6 +498,6 @@ add special temporary rules during [re]start. Shorewall-perl doesn't need such rules since the ruleset is instantianted atomically by table. - - +
+
\ No newline at end of file