forked from extern/shorewall_code
aa991fcf45
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6773 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
498 lines
20 KiB
XML
498 lines
20 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
<article>
|
|
<!--$Id$-->
|
|
|
|
<articleinfo>
|
|
<title>Extension Scripts and Default Actions</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2001-2007</year>
|
|
|
|
<holder>Thomas M. Eastep</holder>
|
|
</copyright>
|
|
|
|
<legalnotice>
|
|
<para>Permission is granted to copy, distribute and/or modify this
|
|
document under the terms of the GNU Free Documentation License, Version
|
|
1.2 or any later version published by the Free Software Foundation; with
|
|
no Invariant Sections, with no Front-Cover, and with no Back-Cover
|
|
Texts. A copy of the license is included in the section entitled
|
|
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
|
|
License</ulink></quote>.</para>
|
|
</legalnotice>
|
|
</articleinfo>
|
|
|
|
<caution>
|
|
<para><emphasis role="bold">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.</emphasis></para>
|
|
</caution>
|
|
|
|
<para>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
|
|
<quote>source</quote> mechanism.</para>
|
|
|
|
<caution>
|
|
<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>
|
|
<para>init -- invoked early in <quote>shorewall start</quote> and
|
|
<quote>shorewall restart</quote></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>initdone -- invoked after Shorewall has flushed all existing rules
|
|
but before any rules have been added to the builtin chains.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>start -- invoked after the firewall has been started or
|
|
restarted.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>started -- invoked after the firewall has been marked as
|
|
'running'.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>stop -- invoked as a first step when the firewall is being
|
|
stopped.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>stopped -- invoked after the firewall has been stopped.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>clear -- invoked after the firewall has been cleared.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>refresh -- invoked while the firewall is being refreshed but
|
|
before the blacklst chains have been rebuilt.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>refreshed -- invoked after the firewall has been refreshed.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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 <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>
|
|
<para>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).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para><emphasis role="bold">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.</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>
|
|
|
|
<para>There are a couple of special considerations for commands in extension
|
|
scripts:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>When you want to run <command>iptables</command>, use the command
|
|
<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>
|
|
<para>If you wish to generate a log message, use <emphasis
|
|
role="bold">log_rule_limit</emphasis>. Parameters are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Log Level</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Chain to insert the rule into</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Chain name to display in the message (this can be different
|
|
from the preceding argument — see the <ulink
|
|
url="PortKnocking.html">Port Knocking article</ulink> for an example
|
|
of how to use this).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Disposition to report in the message (ACCEPT, DROP,
|
|
etc)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Rate Limit (if passed as "" then $LOGLIMIT is assumed — see
|
|
the LOGLIMIT option in <ulink
|
|
url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Log Tag ("" if none)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall versions 3.0.x and earlier
|
|
only.</emphasis> If you run commands other than
|
|
<command>iptables</command> that must be re-run in order to restore the
|
|
firewall to its current state then you must save the commands to the
|
|
<firstterm>restore file</firstterm>. The restore file is a temporary
|
|
file in <filename 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
|
|
<command>iptables-save</command> to produce the
|
|
<filename>/var/lib/shorewall/restore</filename> script.</para>
|
|
|
|
<para>Here are three functions that are useful when running commands
|
|
other than <command>iptables</command>:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">save_command() </emphasis>-- saves the
|
|
passed command to the restore file.</para>
|
|
|
|
<para>Example: <programlisting>save_command echo Operation Complete</programlisting></para>
|
|
|
|
<para>That command would simply write "echo Operation Complete" to
|
|
the restore file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">run_and_save_command()</emphasis> --
|
|
saves the passed command to the restore file then executes it. The
|
|
return value is the exit status of the command. Example:
|
|
<programlisting>run_and_save_command "echo 1 > /proc/sys/net/ipv4/icmp_echo_ignore_all"</programlisting></para>
|
|
|
|
<para>Note that as in this example, when the command involves file
|
|
redirection then the entire command must be enclosed in quotes. This
|
|
applies to all of the functions described here.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">ensure_and_save_command()</emphasis> --
|
|
runs the passed command. If the command fails, the firewall is
|
|
restored to its prior saved state and the operation is terminated.
|
|
If the command succeeds, the command is written to the restore
|
|
file</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall version 3.2.0 - 3.2.8
|
|
only.</emphasis> 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.</para>
|
|
|
|
<note>
|
|
<para>The <filename>/etc/shorewall/params</filename> script is
|
|
processed during compilation <emphasis role="bold">and</emphasis>
|
|
copied into the compiled script as just described. So shell variables
|
|
set during compilation may be used in Shorewall configuration files
|
|
while those set at run-time are available to your other extension
|
|
scripts. Note that if you assign dynamic values to variables, there is
|
|
no guarantee that the value calculated at compile time will be the
|
|
same as what is calculated at run time. This is particularly true if
|
|
you use the <command>shorewall compile</command> command to compile a
|
|
program then run that program at a later time.</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>Extension scripts associated with a particular chain or action
|
|
are not copied into the compiled script; they are rather processed
|
|
directly by the compiler using the Bourne shell "." command. For
|
|
example, if A is an action then if <filename
|
|
class="directory">/etc/shorewall/A</filename> exists then it will be
|
|
processed by the compiler rather than copied into the compiled
|
|
script.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall version 3.2.9 (3.4.0 RC2) and
|
|
later (Shorewall-shell).</emphasis> 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.</para>
|
|
|
|
<note>
|
|
<para>The <filename>/etc/shorewall/params</filename> script is
|
|
processed only during compilation if EXPORTPARAMS=No in
|
|
<filename>shorewall.conf</filename>. So shell variables set in that
|
|
file may be used in Shorewall configuration files only. Any variables
|
|
that your extension scripts require at run-time on the firewall system
|
|
should be set in the <filename>init</filename> extension script (if
|
|
you need variable values in the <filename>stop</filename> or
|
|
<filename>stopped</filename> scripts, you will need to set their value
|
|
in <filename>stop</filename> since <filename>init</filename> is not
|
|
invoked when processing the <command>stop</command> and
|
|
<command>clear</command> commands).</para>
|
|
|
|
<para>When EXPORTPARAMS=Yes (the default), the
|
|
<filename>/etc/shorewall/params</filename> script is processed during
|
|
compilation <emphasis role="bold">and</emphasis> copied into the
|
|
compiled script as described above. So shell variables set during
|
|
compilation may be used in Shorewall configuration files while those
|
|
set at run-time are available to your other extension scripts.Note
|
|
that if you assign dynamic values to variables, there is no guarantee
|
|
that the value calculated at compile time will be the same as what is
|
|
calculated at run time. This is particularly true if you use the
|
|
<command>shorewall compile</command> command to compile a program then
|
|
run that program at a later time or if you use Shorewall Lite.</para>
|
|
</note>
|
|
|
|
<note>
|
|
<para>Extension scripts associated with a particular chain or action
|
|
are not copied into the compiled script; they are rather processed
|
|
directly by the compiler using the Bourne shell "." command. For
|
|
example, if A is an action then if <filename
|
|
class="directory">/etc/shorewall/A</filename> exists then it will be
|
|
processed by the compiler rather than copied into the compiled
|
|
script.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall-perl</emphasis>. 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.</para>
|
|
|
|
<para>The following table summarizes when the various extension scripts
|
|
are run:<informaltable frame="all">
|
|
<tgroup cols="3">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role="bold">Compile-time</emphasis></entry>
|
|
|
|
<entry><emphasis role="bold">Run-time</emphasis></entry>
|
|
|
|
<entry><emphasis role="bold">Eliminated</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>initdone</entry>
|
|
|
|
<entry>clear</entry>
|
|
|
|
<entry>continue</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>maclog</entry>
|
|
|
|
<entry>initdone</entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Per-chain (including those associated with
|
|
actions)</entry>
|
|
|
|
<entry>start</entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>started</entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>stop</entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>stopped</entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>tcclear</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>refresh</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry></entry>
|
|
|
|
<entry>refreshed</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable></para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>All scripts will need to begin with the following
|
|
line:<programlisting>use Shorewall::Chains;</programlisting>For more
|
|
complex scripts, you may need to 'use' other Shorewall Perl modules --
|
|
browse <filename
|
|
class="directory">/usr/share/shorewall-perl/Shorewall/</filename> to see
|
|
what's available.</para>
|
|
|
|
<para>When a script is invoked, the $chainref scalar variable will hold
|
|
a reference to a chain table entry.<simplelist>
|
|
<member>$chainref->{name} contains the name of the chain</member>
|
|
|
|
<member>$chainref->{table} holds the table name</member>
|
|
</simplelist>To add a rule to the chain:<programlisting>add_rule( $chainref, <the rule> );</programlisting>Where<simplelist>
|
|
<member><the rule> is a scalar argument holding the rule text.
|
|
Do not include "-A <chain name>"</member>
|
|
</simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting>To
|
|
insert a rule into the chain:<programlisting> insert_rule( $chainref, <rulenum>, <the rule> );</programlisting>The
|
|
log_rule_limit function works like it does in the shell compiler with
|
|
two exceptions:<itemizedlist>
|
|
<listitem>
|
|
<para>You pass the chain reference rather than the name of the
|
|
chain.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The commands are 'add' and 'insert' rather than '-A' and
|
|
'-I'.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>There is only a single "pass as-is to iptables" argument (so
|
|
you must quote that part).</para>
|
|
</listitem>
|
|
</itemizedlist>Example:<programlisting>log_rule_limit(
|
|
'info' ,
|
|
$chainref ,
|
|
$chainref->{name},
|
|
'DROP' ,
|
|
'', #Limit
|
|
'' , #Log tag
|
|
'add', #Command
|
|
'-p tcp' #Pass as-is
|
|
);</programlisting>Some run-time scripts have been converted to
|
|
compile time scripts:<simplelist>
|
|
<member>initdone</member>
|
|
|
|
<member>maclog</member>
|
|
</simplelist>Note that in the 'initdone' script, there is no default
|
|
chain ($chainref). You can obtain a reference to a standard chain
|
|
by:<programlisting>my $chainref = $chain_table{<table>}{<chain name>};</programlisting>Example:<programlisting>my $chainref = $chain_table{filter}{INPUT};</programlisting></para>
|
|
|
|
<para>You can also use the hash references $filter_table, $mangle_table
|
|
and $nat_table to access chain references.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<programlisting>my $chainref = $filter_table->{INPUT}; #Same as above with a few less keystrokes; runs faster too</programlisting>
|
|
|
|
<para>The continue script has been eliminated because it no longer make
|
|
any sense under Shorewall-perl. This script was designed to allow you to
|
|
add special temporary rules during [re]start. Shorewall-perl doesn't
|
|
need such rules.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</article> |