forked from extern/shorewall_code
4033e6051b
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@3521 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
272 lines
10 KiB
XML
272 lines
10 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 Common Actions</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate>2005-10-31</pubdate>
|
|
|
|
<copyright>
|
|
<year>2001-2005</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 as a first step when the firewall is being
|
|
started</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 common and/or blacklst chains have been rebuilt.</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.</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.</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>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 it's 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>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>
|
|
</itemizedlist>
|
|
|
|
<para>You can also define a <emphasis>common action</emphasis> to be
|
|
performed immediately before a policy of ACCEPT, DROP or REJECT is applied.
|
|
Separate <ulink url="Actions.html">actions</ulink> can be assigned to each
|
|
policy type so for example you can have a different common action for DROP
|
|
and REJECT policies. The most common usage of common actions is to silently
|
|
drop traffic that you don't wish to have logged by the policy.</para>
|
|
|
|
<para>As released, Shorewall defines a number of actions which are cataloged
|
|
in the <filename>/usr/share/shorewall/actions.std</filename> file. That file
|
|
is processed before /etc/shorewall/actions. Among the entries in
|
|
<filename>/usr/share/shorewall/actions.std</filename> are:</para>
|
|
|
|
<programlisting>Drop:DROP
|
|
Reject:REJECT</programlisting>
|
|
|
|
<para>So the action named <quote>Drop</quote> is performed immediately
|
|
before DROP policies are applied and the action called <quote>Reject</quote>
|
|
is performed before REJECT policies are applied. These actions are defined
|
|
in the files <filename>/usr/share/shorewall/action.Drop</filename> and
|
|
<filename>/usr/share/shorewall/action.Reject</filename> respectively.</para>
|
|
|
|
<para>You can override these defaults with entries in your
|
|
/etc/shorewall/actions file. For example, if that file were to contain
|
|
<quote>MyDrop:DROP</quote> then the common action for DROP policies would
|
|
become <quote>MyDrop</quote>.</para>
|
|
|
|
<para>One final note. The chain created to perform an action has the same
|
|
name as the action. You can use an extension script by that name to add
|
|
rules to the action's chain in the same way as you can any other chain. So
|
|
if you create the new action <quote>Dagger</quote> and define it in
|
|
<filename>/etc/shorewall/action.Dagger</filename>, you can also have an
|
|
extension script named <filename>/etc/shorewall/Dagger</filename> that can
|
|
add rules to the <quote>Dagger</quote> chain that can't be created using
|
|
<filename>/etc/shorewall/action.Dagger</filename>.</para>
|
|
</article> |