mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-09 01:04:06 +01:00
9350da941e
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@2109 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
266 lines
10 KiB
XML
266 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-05-13</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>
|
|
|
|
<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 (added in Shorewall 2.0.2 RC1) -- 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>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>newnotsyn (added in version 1.3.6) -- invoked after the
|
|
<quote>newnotsyn</quote> chain has been created but before any rules
|
|
have been added to it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>continue (added in version 2.2.3) -- 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 (Shorewall version < 2.0.2 Beta 1 or there is no
|
|
<filename>/var/lib/shorewall/restore</filename> file) or restored
|
|
(Shorewall version >= 2.0.2 Beta 1 and
|
|
<filename>/var/lib/shorewall/restore</filename> exists).</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). This argument applies
|
|
to Shorewall 2.2.0 and later only.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The remaining arguments are passed "as is" to iptables</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>With Shorewall 2.0.2 Beta 1 and later versions, 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>
|
|
</itemizedlist>
|
|
|
|
<para>Beginning with Shorewall 2.0.0, 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> |