shorewall_code/Shorewall-docs2/shorewall_extension_scripts.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 &lt; 2.0.2 Beta 1 or there is no
      <filename>/var/lib/shorewall/restore</filename> file) or restored
      (Shorewall version &gt;= 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 &gt; /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>