extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-12-22 14:20:40 +01:00
Code Issues Packages Projects Releases Wiki Activity

Break the extension script doc into sections

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6789 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2007-07-05 14:22:08 +00:00
parent e6f307d686
commit 783f9fe64f
1 changed files with 190 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

372
docs/shorewall_extension_scripts.xml
View File

@ -5,7 +5,7 @@
<!--$Id$--> <!--$Id$-->
<articleinfo> <articleinfo>
<title>Extension Scripts and Default Actions</title> <title>Extension Scripts</title>
<authorgroup> <authorgroup>
<author> <author>
@ -34,182 +34,185 @@
</legalnotice> </legalnotice>
</articleinfo> </articleinfo>
<caution> <section id="Scripts">
<para><emphasis role="bold">This article applies to Shorewall 3.0 and <title>Extension Scripts</title>
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.</emphasis></para>
</caution>
<para>Extension scripts are user-provided scripts that are invoked at <para>Extension scripts are user-provided scripts that are invoked at
various points during firewall start, restart, stop and clear. The scripts various points during firewall start, restart, stop and clear. The scripts
are placed in /etc/shorewall and are processed using the Bourne shell are placed in /etc/shorewall and are processed using the Bourne shell
<quote>source</quote> mechanism.</para> <quote>source</quote> mechanism.</para>
<caution> <caution>
<orderedlist> <orderedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>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.</para>
</listitem>
</orderedlist>
</caution>
<para>The following scripts can be supplied:</para>
<itemizedlist>
<listitem> <listitem>
<para>Be sure that you actually need to use an extension script to do <para>init -- invoked early in <quote>shorewall start</quote> and
what you want. Shorewall has a wide range of features that cover most <quote>shorewall restart</quote></para>
requirements.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>DO NOT SIMPLY COPY RULES THAT YOU FIND ON THE NET INTO AN <para>initdone -- invoked after Shorewall has flushed all existing
EXTENSION SCRIPT AND EXPECT THEM TO WORK AND TO NOT BREAK SHOREWALL. rules but before any rules have been added to the builtin
TO USE SHOREWALL EXTENSION SCRIPTS YOU MUST KNOW WHAT YOU ARE DOING chains.</para>
WITH RESPECT TO iptables/Netfilter AND SHOREWALL.</para>
</listitem> </listitem>
</orderedlist>
</caution>
<para>The following scripts can be supplied:</para> <listitem>
<para>start -- invoked after the firewall has been started or
restarted.</para>
</listitem>
<itemizedlist> <listitem>
<listitem> <para>started -- invoked after the firewall has been marked as
<para>init -- invoked early in <quote>shorewall start</quote> and 'running'.</para>
<quote>shorewall restart</quote></para> </listitem>
</listitem>
<listitem> <listitem>
<para>initdone -- invoked after Shorewall has flushed all existing rules <para>stop -- invoked as a first step when the firewall is being
but before any rules have been added to the builtin chains.</para> stopped.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>start -- invoked after the firewall has been started or <para>stopped -- invoked after the firewall has been stopped.</para>
restarted.</para> </listitem>
</listitem>
<listitem> <listitem>
<para>started -- invoked after the firewall has been marked as <para>clear -- invoked after the firewall has been cleared.</para>
'running'.</para> </listitem>
</listitem>
<listitem> <listitem>
<para>stop -- invoked as a first step when the firewall is being <para>refresh -- invoked while the firewall is being refreshed but
stopped.</para> before the blacklst chains have been rebuilt.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>stopped -- invoked after the firewall has been stopped.</para> <para>refreshed -- invoked after the firewall has been
</listitem> refreshed.</para>
</listitem>
<listitem> <listitem>
<para>clear -- invoked after the firewall has been cleared.</para> <para>continue -- invoked to allow you to insert special rules to
</listitem> allow traffic while Shorewall is [re]starting. Any rules added in this
script should be deleted in your <emphasis>start</emphasis> script.
This script is invoked earlier in the [re]start process than is the
<emphasis>initdone</emphasis> script described above (Not used by
Shorewall Perl).</para>
</listitem>
<listitem> <listitem>
<para>refresh -- invoked while the firewall is being refreshed but <para>maclog -- (Added in Shorewall version 3.2.5) invoked while mac
before the blacklst chains have been rebuilt.</para> filtering rules are being created. It is invoked once for each
</listitem> 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).</para>
</listitem>
</itemizedlist>
<listitem> <para><emphasis role="bold">If your version of Shorewall doesn't have the
<para>refreshed -- invoked after the firewall has been refreshed.</para> file that you want to use from the above list, you can simply create the
</listitem> file yourself.</emphasis> 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.</para>
<listitem> <para>There are a couple of special considerations for commands in
<para>continue -- invoked to allow you to insert special rules to allow extension scripts:</para>
traffic while Shorewall is [re]starting. Any rules added in this script
should be deleted in your <emphasis>start</emphasis> script. This script
is invoked earlier in the [re]start process than is the
<emphasis>initdone</emphasis> script described above (Not used by
Shorewall Perl).</para>
</listitem>
<listitem> <itemizedlist>
<para>maclog -- (Added in Shorewall version 3.2.5) invoked while mac <listitem>
filtering rules are being created. It is invoked once for each interface <para>When you want to run <command>iptables</command>, use the
having 'maclist' specified and it is invoked just before the logging command <command>run_iptables</command> instead.
rule is added to the current chain (the name of that chain will be in <command>run_iptables</command> will run the iptables utility passing
$CHAIN).</para> the arguments to <command>run_iptables</command> and if the command
</listitem> fails, the firewall will be stopped (or restored from the last
</itemizedlist> <command>save</command> command, if any).</para>
</listitem>
<para><emphasis role="bold">If your version of Shorewall doesn't have the <listitem>
file that you want to use from the above list, you can simply create the <para>If you wish to generate a log message, use <emphasis
file yourself.</emphasis> You can also supply a script with the same name as role="bold">log_rule_limit</emphasis>. Parameters are:</para>
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.</para>
<para>There are a couple of special considerations for commands in extension <itemizedlist>
scripts:</para> <listitem>
<para>Log Level</para>
</listitem>
<itemizedlist> <listitem>
<listitem> <para>Chain to insert the rule into</para>
<para>When you want to run <command>iptables</command>, use the command </listitem>
<command>run_iptables</command> instead. <command>run_iptables</command>
will run the iptables utility passing the arguments to
<command>run_iptables</command> and if the command fails, the firewall
will be stopped (or restored from the last <command>save</command>
command, if any).</para>
</listitem>
<listitem> <listitem>
<para>If you wish to generate a log message, use <emphasis <para>Chain name to display in the message (this can be different
role="bold">log_rule_limit</emphasis>. Parameters are:</para> from the preceding argument — see the <ulink
url="PortKnocking.html">Port Knocking article</ulink> for an
example of how to use this).</para>
</listitem>
<itemizedlist> <listitem>
<listitem> <para>Disposition to report in the message (ACCEPT, DROP,
<para>Log Level</para> etc)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Chain to insert the rule into</para> <para>Rate Limit (if passed as "" then $LOGLIMIT is assumed — see
</listitem> the LOGLIMIT option in <ulink
url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>)</para>
</listitem>
<listitem> <listitem>
<para>Chain name to display in the message (this can be different <para>Log Tag ("" if none)</para>
from the preceding argument — see the <ulink </listitem>
url="PortKnocking.html">Port Knocking article</ulink> for an example
of how to use this).</para>
</listitem>
<listitem> <listitem>
<para>Disposition to report in the message (ACCEPT, DROP, <para>Command (-A or -I for append or insert).</para>
etc)</para> </listitem>
</listitem>
<listitem> <listitem>
<para>Rate Limit (if passed as "" then $LOGLIMIT is assumed — see <para>The remaining arguments are passed "as is" to
the LOGLIMIT option in <ulink iptables</para>
url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>)</para> </listitem>
</listitem> </itemizedlist>
</listitem>
<listitem> <listitem>
<para>Log Tag ("" if none)</para> <para>Many of the extension scripts get executed for both the
</listitem> shorewall start and shorewall restart commands. You can determine
which command is being executed using the contents of $COMMAND.</para>
<listitem> <programlisting>if [ $COMMAND = start ]; then
<para>Command (-A or -I for append or insert).</para>
</listitem>
<listitem>
<para>The remaining arguments are passed "as is" to iptables</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>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.</para>
<programlisting>if [ $COMMAND = start ]; then
...</programlisting> ...</programlisting>
</listitem> </listitem>
</itemizedlist>
<listitem> <para></para>
<para><emphasis role="bold">Shorewall versions 3.0.x and earlier
only.</emphasis> If you run commands other than <section id="v3.0">
<command>iptables</command> that must be re-run in order to restore the <title>Shorewall versions 3.0.x and earlier</title>
firewall to its current state then you must save the commands to the
<firstterm>restore file</firstterm>. The restore file is a temporary <para>If you run commands other than <command>iptables</command> that
file in <filename class="directory">/var/lib/shorewall</filename> that must be re-run in order to restore the firewall to its current state
will be renamed <filename>/var/lib/shorewall/restore-base</filename> at then you must save the commands to the <firstterm>restore
the successful completion of the Shorewall command. The file</firstterm>. The restore file is a temporary file in <filename
<command>shorewall save</command> command combines class="directory">/var/lib/shorewall</filename> that will be renamed
<filename>/var/lib/shorewall/restore-base</filename> at the successful
completion of the Shorewall command. The <command>shorewall
save</command> command combines
<filename>/var/lib/shorewall/restore-base</filename> with the output of <filename>/var/lib/shorewall/restore-base</filename> with the output of
<command>iptables-save</command> to produce the <command>iptables-save</command> to produce the
<filename>/var/lib/shorewall/restore</filename> script.</para> <filename>/var/lib/shorewall/restore</filename> script.</para>
@ -247,21 +250,21 @@
file</para> file</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</listitem> </section>
<listitem> <section id="v3.2">
<para><emphasis role="bold">Shorewall version 3.2.0 - 3.2.8 <title>Shorewall version 3.2.0 - 3.2.8</title>
only.</emphasis> When compiling your firewall configuration, Shorewall
copies most extension scripts directly into the "compiled" program where <para>When compiling your firewall configuration, Shorewall copies most
they are executed in-line during processing of the start, restart and extension scripts directly into the "compiled" program where they are
restore commands. When copying a script, Shorewall indents the script to executed in-line during processing of the start, restart and restore
match the surrounding code; if you have 'awk' installed on the system commands. When copying a script, Shorewall indents the script to match
where the configuration is being compiled, Shorewall can correctly the surrounding code; if you have 'awk' installed on the system where
handle line continuation in your script ("\" as the last character on a the configuration is being compiled, Shorewall can correctly handle line
line). If you do not have awk, you may not use line continuation in your continuation in your script ("\" as the last character on a line). If
scripts. Also beware that quoted strings continued from one line to you do not have awk, you may not use line continuation in your scripts.
another will have extra whitespace inserted as a result of Also beware that quoted strings continued from one line to another will
indentation.</para> have extra whitespace inserted as a result of indentation.</para>
<note> <note>
<para>The <filename>/etc/shorewall/params</filename> script is <para>The <filename>/etc/shorewall/params</filename> script is
@ -285,21 +288,22 @@
processed by the compiler rather than copied into the compiled processed by the compiler rather than copied into the compiled
script.</para> script.</para>
</note> </note>
</listitem> </section>
<listitem> <section id="v3.2.9">
<para><emphasis role="bold">Shorewall version 3.2.9 (3.4.0 RC2) and <title>Shorewall version 3.2.9 (3.4.0 RC2) and later
later (Shorewall-shell).</emphasis> When compiling your firewall (Shorewall-shell)</title>
configuration, Shorewall copies most extension scripts directly into the
"compiled" program where they are executed in-line during processing of <para>When compiling your firewall configuration, Shorewall copies most
the start, restart and restore commands. When copying a script, extension scripts directly into the "compiled" program where they are
Shorewall indents the script to match the surrounding code; if you have executed in-line during processing of the start, restart and restore
'awk' installed on the system where the configuration is being compiled, commands. When copying a script, Shorewall indents the script to match
Shorewall can correctly handle line continuation in your script ("\" as the surrounding code; if you have 'awk' installed on the system where
the last character on a line). If you do not have awk, you may not use the configuration is being compiled, Shorewall can correctly handle line
line continuation in your scripts. Also beware that quoted strings continuation in your script ("\" as the last character on a line). If
continued from one line to another will have extra whitespace inserted you do not have awk, you may not use line continuation in your scripts.
as a result of indentation.</para> Also beware that quoted strings continued from one line to another will
have extra whitespace inserted as a result of indentation.</para>
<note> <note>
<para>The <filename>/etc/shorewall/params</filename> script is <para>The <filename>/etc/shorewall/params</filename> script is
@ -336,13 +340,15 @@
processed by the compiler rather than copied into the compiled processed by the compiler rather than copied into the compiled
script.</para> script.</para>
</note> </note>
</listitem> </section>
<listitem> <section id="Perl">
<para><emphasis role="bold">Shorewall-perl</emphasis>. Because the <title>Shorewall-perl (Version 4.0.0 and later)</title>
compiler is written in Perl, some of your extension scripts from earlier
versions will no longer work because Shorewall-perl runs those extension <para>Because the compiler is written in Perl, some of your extension
scripts at compile-time rather than at run-time.</para> scripts from earlier versions will no longer work because Shorewall-perl
runs those extension scripts at compile-time rather than at
run-time.</para>
<para>The following table summarizes when the various extension scripts <para>The following table summarizes when the various extension scripts
are run:<informaltable frame="all"> are run:<informaltable frame="all">
@ -443,7 +449,9 @@
<member>$chainref-&gt;{name} contains the name of the chain</member> <member>$chainref-&gt;{name} contains the name of the chain</member>
<member>$chainref-&gt;{table} holds the table name</member> <member>$chainref-&gt;{table} holds the table name</member>
</simplelist>To add a rule to the chain:<programlisting>add_rule( $chainref, &lt;the rule&gt; );</programlisting>Where<simplelist> </simplelist></para>
<para>To add a rule to the chain:<programlisting>add_rule( $chainref, &lt;the rule&gt; );</programlisting>Where<simplelist>
<member>&lt;the rule&gt; is a scalar argument holding the rule text. <member>&lt;the rule&gt; is a scalar argument holding the rule text.
Do not include "-A &lt;chain name&gt;"</member> Do not include "-A &lt;chain name&gt;"</member>
</simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting>To </simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting>To
@ -490,6 +498,6 @@
add special temporary rules during [re]start. Shorewall-perl doesn't add special temporary rules during [re]start. Shorewall-perl doesn't
need such rules since the ruleset is instantianted atomically by need such rules since the ruleset is instantianted atomically by
table.</para> table.</para>
</listitem> </section>
</itemizedlist> </section>
</article> </article>