shorewall_code/docs/User_defined_Actions.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>User-defined Actions</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2003</year>

      <year>2004</year>

      <year>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>

  <section>
    <title>Creating a New Action</title>

    <para>Prior to Shorewall version 1.4.9, rules in
    <filename>/etc/shorewall/rules</filename> were limited to those defined by
    Netfilter (ACCEPT, DROP, REJECT, etc.). Beginning with Shorewall version
    1.4.9, users may use sequences of these elementary operations to define
    more complex actions.</para>

    <para>To define a new action:</para>

    <orderedlist>
      <listitem>
        <para>Add a line to
        <filename><filename>/etc/shorewall/actions</filename></filename> that
        names your new action. Action names must be valid shell variable names
        ((must begin with a letter and be composed of letters, digits and
        underscore characters) as well as valid Netfilter chain names. If you
        intend to log from the action, the name must have a maximum of 11
        characters. It is recommended that the name you select for a new
        action begins with a capital letter; that way, the name won't conflict
        with a Shorewall-defined chain name.</para>

        <para>Beginning with Shorewall-2.0.0-Beta1, the name of the action may
        be optionally followed by a colon (<quote>:</quote>) and ACCEPT, DROP
        or REJECT. When this is done, the named action will become the
        <emphasis>common action </emphasis>for policies of type ACCEPT, DROP
        or REJECT respectively. The common action is applied immediately
        before the policy is enforced (before any logging is done under that
        policy) and is used mainly to suppress logging of uninteresting
        traffic which would otherwise clog your logs. The same policy name can
        appear in multiple actions; the last such action for each policy name
        is the one which Shorewall will use.</para>

        <para>Shorewall includes pre-defined actions for DROP and REJECT --
        see below.</para>
      </listitem>

      <listitem>
        <para>Once you have defined your new action name (ActionName), then
        copy /usr/share/shorewall/action.template to
        <filename>/etc/shorewall/action.ActionName</filename> (for example, if
        your new action name is <quote>Foo</quote> then copy
        <filename>/usr/share/shorewall/action.template</filename> to
        <filename>/etc/shorewall/action.Foo</filename>).</para>
      </listitem>

      <listitem>
        <para>Now modify the new file to define the new action.</para>
      </listitem>
    </orderedlist>

    <para>Columns in the action.template file are as follows:</para>

    <itemizedlist>
      <listitem>
        <para>TARGET - Must be ACCEPT, DROP, REJECT, LOG, CONTINUE, QUEUE or
        &lt;<emphasis>action</emphasis>&gt; where
        &lt;<emphasis>action</emphasis>&gt; is a previously-defined action
        (that is, it must precede the action being defined in this file in
        your <filename>/etc/shorewall/actions</filename> file). These actions
        have the same meaning as they do in the
        <filename>/etc/shorewall/rules</filename> file (CONTINUE terminates
        processing of the current action and returns to the point where that
        action was invoked). The TARGET may optionally be followed by a colon
        (<quote>:</quote>) and a syslog log level (e.g, REJECT:info or
        ACCEPT:debugging). This causes the packet to be logged at the
        specified level. You may also specify ULOG (must be in upper case) as
        a log level.This will log to the ULOG target for routing to a separate
        log through use of ulogd (<ulink
        url="http://www.gnumonks.org/projects/ulogd">http://www.gnumonks.org/projects/ulogd</ulink>).</para>
      </listitem>

      <listitem>
        <para>SOURCE - Source hosts to which the rule applies. A
        comma-separated list of subnets and/or hosts. Hosts may be specified
        by IP or MAC address; mac addresses must begin with <quote>~</quote>
        and must use <quote>-</quote> as a separator.</para>

        <para>Alternatively, clients may be specified by interface name. For
        example, eth1 specifies a client that communicates with the firewall
        system through eth1. This may be optionally followed by another colon
        (<quote>:</quote>) and an IP/MAC/subnet address as described above
        (e.g., eth1:192.168.1.5).</para>
      </listitem>

      <listitem>
        <para>DEST - Location of Server. Same as above with the exception that
        MAC addresses are not allowed.</para>

        <para>Unlike in the SOURCE column, you may specify a range of up to
        256 IP addresses using the syntax &lt;<emphasis>first
        ip</emphasis>&gt;-&lt;<emphasis>last ip</emphasis>&gt;.</para>
      </listitem>

      <listitem>
        <para>PROTO - Protocol - Must be <quote>tcp</quote>,
        <quote>udp</quote>, <quote>icmp</quote>, a number, or
        <quote>all</quote>.</para>
      </listitem>

      <listitem>
        <para>DEST PORT(S) - Destination Ports. A comma-separated list of Port
        names (from <filename>/etc/services</filename>), port numbers or port
        ranges; if the protocol is <quote>icmp</quote>, this column is
        interpreted as the destination icmp-type(s).</para>

        <para>A port range is expressed as &lt;<emphasis>low
        port</emphasis>&gt;:&lt;<emphasis>high port</emphasis>&gt;.</para>

        <para>This column is ignored if PROTOCOL = all but must be entered if
        any of the following fields are supplied. In that case, it is
        suggested that this field contain <quote>-</quote>.</para>

        <para>If your kernel contains multi-port match support, then only a
        single Netfilter rule will be generated if in this list and in the
        CLIENT PORT(S) list below:</para>

        <orderedlist>
          <listitem>
            <para>There are 15 or less ports listed.</para>
          </listitem>

          <listitem>
            <para>No port ranges are included.</para>
          </listitem>
        </orderedlist>

        <para>Otherwise, a separate rule will be generated for each
        port.</para>
      </listitem>

      <listitem>
        <para>SOURCE PORT(S) - Port(s) used by the client. If omitted, any
        source port is acceptable. Specified as a comma-separated list of port
        names, port numbers or port ranges.</para>

        <para>If you don't want to restrict client ports but need to specify
        an ADDRESS in the next column, then place "-" in this column.</para>

        <para>If your kernel contains multi-port match support, then only a
        single Netfilter rule will be generated if in this list and in the
        DEST PORT(S) list above:</para>

        <orderedlist>
          <listitem>
            <para>There are 15 or less ports listed.</para>
          </listitem>

          <listitem>
            <para>No port ranges are included.</para>
          </listitem>
        </orderedlist>

        <para>Otherwise, a separate rule will be generated for each
        port.</para>
      </listitem>

      <listitem>
        <para>RATE LIMIT - You may rate-limit the rule by placing a value in
        this column:</para>

        <para><programlisting>     &lt;<emphasis>rate</emphasis>&gt;/&lt;<emphasis>interval</emphasis>&gt;[:&lt;<emphasis>burst</emphasis>&gt;]</programlisting>where
        &lt;<emphasis>rate</emphasis>&gt; is the number of connections per
        &lt;<emphasis>interval</emphasis>&gt; (<quote>sec</quote> or
        <quote>min</quote>) and &lt;<emphasis>burst</emphasis>&gt; is the
        largest burst permitted. If no &lt;<emphasis>burst</emphasis>&gt; is
        given, a value of 5 is assumed. There may be no whitespace embedded in
        the specification.</para>

        <para><programlisting>     Example: 10/sec:20</programlisting></para>
      </listitem>

      <listitem>
        <para>USER/GROUP - For output rules (those with the firewall as their
        source), you may control connections based on the effective UID and/or
        GID of the process requesting the connection. This column can contain
        any of the following:</para>

        <simplelist>
          <member>[!]&lt;<emphasis>user number</emphasis>&gt;[:]</member>

          <member>[!]&lt;<emphasis>user name</emphasis>&gt;[:]</member>

          <member>[!]:&lt;<emphasis>group number</emphasis>&gt;</member>

          <member>[!]:&lt;<emphasis>group name</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          number</emphasis>&gt;:&lt;<emphasis>group
          number</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          name</emphasis>&gt;:&lt;<emphasis>group
          number</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          inumber</emphasis>&gt;:&lt;<emphasis>group
          name</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          name</emphasis>&gt;:&lt;<emphasis>group name</emphasis>&gt;</member>
        </simplelist>
      </listitem>
    </itemizedlist>

    <para>Omitted column entries should be entered using a dash ("-:).</para>

    <para>Example:</para>

    <para><filename>/etc/shorewall/actions</filename>:</para>

    <para><programlisting>     LogAndAccept</programlisting><phrase><filename>/etc/shorewall/action.LogAndAccept</filename></phrase><programlisting>     LOG:info
     ACCEPT</programlisting></para>

    <para>To use your action, in <filename>/etc/shorewall/rules</filename> you
    might do something like:</para>

    <programlisting>#ACTION      SOURCE      DEST        PROTO    DEST PORT(S)
LogAndAccept loc         $FW         tcp      22</programlisting>

    <para>Prior to Shorewall 2.1.2, specifying a log level (and optionally a
    log tag) on a rule that specified a user-defined (or Shorewall-defined)
    action would log all traffic passed to the action. Beginning with
    Shorewall 2.1.2, specifying a log level in a rule that specifies a user-
    or Shorewall-defined action will cause each rule in the action to be
    logged with the specified level (and tag).</para>

    <para>The extent to which logging of action rules occur is governed by the
    following:</para>

    <orderedlist>
      <listitem>
        <para>When you invoke an action and specify a log level, only those
        rules in the action that have no log level will be changed to log at
        the level specified at the action invocation.</para>

        <para>Example:</para>

        <para>/etc/shorewall/action.foo</para>

        <programlisting>#TARGET      SOURCE     DEST     PROTO    DEST PORT(S)
ACCEPT       -          -        tcp      22
bar:info</programlisting>

        <para>/etc/shorewall/rules:</para>

        <programlisting>#ACTION      SOURCE     DEST     PROTO    DEST PORT(S)
foo:debug    $FW        net</programlisting>

        <para>Logging in the invoke 'foo' action will be as if foo had been
        defined as:</para>

        <programlisting>#TARGET      SOURCE     DEST     PROTO    DEST PORT(S)
ACCEPT:debug -          -        tcp      22
bar:info</programlisting>
      </listitem>

      <listitem>
        <para>If you follow the log level with "!" then logging will be at
        that level for all rules recursively invoked by the action.</para>

        <para>Example:</para>

        <para>/etc/shorewall/action.foo</para>

        <programlisting>#TARGET      SOURCE     DEST     PROTO    DEST PORT(S)
ACCEPT       -          -        tcp      22
bar:info</programlisting>

        <para>/etc/shorewall/rules:</para>

        <programlisting>#ACTION      SOURCE     DEST     PROTO    DEST PORT(S)
foo:debug!    $FW        net</programlisting>

        <para>Logging in the invoke 'foo' action will be as if foo had been
        defined as:</para>

        <programlisting>#TARGET      SOURCE     DEST     PROTO    DEST PORT(S)
ACCEPT:debug -          -        tcp      22
bar:debug</programlisting>
      </listitem>
    </orderedlist>

    <para>The change in Shorewall 2.1.2 has an effect on extension scripts
    used with user-defined actions. If you define an action 'acton' and you
    have an <filename>/etc/shorewall/acton</filename> script then when that
    script is invoked, the following three variables will be set for use by
    the script:</para>

    <itemizedlist>
      <listitem>
        <para>$CHAIN = the name of the chain where your rules are to be
        placed. When logging is used on an action invocation, Shorewall
        creates a chain with a slightly different name from the action
        itself.</para>
      </listitem>

      <listitem>
        <para>$LEVEL = Log level. If empty, no logging was specified.</para>
      </listitem>

      <listitem>
        <para>$TAG = Log Tag.</para>
      </listitem>
    </itemizedlist>

    <para>Example:</para>

    <para><filename>/etc/shorewall/rules</filename>:</para>

    <programlisting>#ACTION          SOURCE           DEST
acton:info:test  $FW              net</programlisting>

    <para>Your /etc/shorewall/acton file will be run with:</para>

    <itemizedlist>
      <listitem>
        <para>$CHAIN="%acton1"</para>
      </listitem>

      <listitem>
        <para>$LEVEL="info"</para>
      </listitem>

      <listitem>
        <para>$TAG="test"</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Standard Actions In Shorewall 2.0</title>

    <para>Beginning with Shorewall 2.0.0-Beta1, Shorewall includes a number of
    pre-defined actions. These defined actions are listed in
    <filename>/usr/share/shorewall/actions.std</filename>.</para>

    <example>
      <title>Example of Using a Standard Action</title>

      <para>Suppose that you wish to enable ftp from your local network to
      your firewall. In <filename>/etc/shorewall/rules</filename>:</para>

      <programlisting>#ACTION   SOURCE      DEST        PROTO    ...
AllowFTP  loc         $FW</programlisting>
    </example>

    <para><filename>/usr/share/shorewall/actions.std</filename> is processed
    before <filename>/etc/shorewall/actions</filename> and if you have any
    actions defined with the same name as one in
    <filename>/usr/share/shorewall/actions.std</filename>, your version in
    <filename class="directory">/etc/shorewall</filename> will be the one
    used. So if you wish to modify a standard action, simply copy the
    associated action file from <filename
    class="directory">/usr/share/shorewall </filename>to <filename
    class="directory">/etc/shorewall and modify</filename> it to suit your
    needs. The next <command>shorewall restart</command> will cause your
    action to be installed in place of the standard one. In particular, if you
    want to modify the common actions <quote>Drop</quote> or
    <quote>Reject</quote>, simply copy <filename>action.Drop</filename> or
    <filename>Action.Reject</filename> to <filename
    class="directory">/etc/shorewall</filename> and modify that copy as
    desired.</para>

    <note>
      <para>Some of the standard actions are <firstterm>built-in</firstterm>s.
      This means that there is no corresponding action.* file and that
      Shorewall constructs the rules for the actions using direct
      <command>iptables</command> commands. If you need to modify one of these
      built-in actions, you will need to use the <link
      linkend="Extension">Extension Script mechanism</link> described below
      and you will need to give the action a different name.</para>
    </note>
  </section>

  <section id="Common">
    <title>Common Actions</title>

    <para>Also beginning with Shorewall version 2.2.0-Beta1, when an ACCEPT,
    DROP or REJECT policy is about to be enforced, a <firstterm>common
    action</firstterm> can first be invoked. In /etc/shorewall/actions.std are
    found these two entries:</para>

    <programlisting>Drop:DROP       #Common Action for DROP policy
Reject:REJECT   #Common Action for REJECT policy</programlisting>

    <para>These entries designate the action named <firstterm>Drop</firstterm>
    as the common action for DROP policies and the common action
    <firstterm>Reject</firstterm> as the common action for REJECT
    policies.</para>

    <para>The purpose of common actions is:</para>

    <itemizedlist>
      <listitem>
        <para>To avoid filling your log with useless clutter. For example, one
        of the things that the Drop action does is to silently drop SMB
        traffic by invoking the <firstterm>DropSMB</firstterm> action.</para>
      </listitem>

      <listitem>
        <para>To ensure proper behavior. For example, both the Drop and Reject
        actions invoke the <firstterm>RejectAuth</firstterm> action to REJECT
        connection requests on TCP port 113. If these requests are simply
        dropped, connection timeouts can occur when you connect to a server
        that uses AUTH identification.</para>
      </listitem>
    </itemizedlist>

    <para>It should be stressed that <emphasis role="bold">the common actions
    do not cause any traffic to be dropped or rejected that isn't about to be
    dropped or rejected anyway</emphasis> (remember that these actions are
    invoked just before the connection request is going to be dropped or
    rejected by policy anyway). Their main function is to avoid log
    clutter.</para>
  </section>

  <section id="Extension">
    <title>Creating an Action using an Extension Script</title>

    <para>There may be cases where you wish to create a chain with rules that
    can't be constructed using the tools defined in the action.template. In
    that case, you can use an extension script.<note>
        <para>If you actually need an action to drop broadcast packets, use
        the <command>dropBcast</command> standard action rather than create
        one like this.</para>
      </note></para>

    <example>
      <title>An action to drop all broadcast packets</title>

      <para>/etc/shorewall/actions<programlisting>DropBcasts</programlisting></para>

      <para>/etc/shorewall/action.DropBcasts<programlisting># This file is empty</programlisting></para>

      <para>/etc/shorewall/DropBcasts<programlisting>run_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP</programlisting></para>
    </example>
  </section>
</article>