shorewall_code/Shorewall-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>2003-01-29</pubdate>

    <copyright>
      <year>2003-2004</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>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 as well as valid Netfilter chain names. It is recommended that the
      name you select for a new action begins with with a capital letter; that
      way, the name won&#39;t conflict with a Shorewall-defined chain name.</para>
    </listitem>

    <listitem>
      <para>Once you have defined your new action name (ActionName), then copy
      /etc/shorewall/action.template to <filename>/etc/shorewall/action.ActionName</filename>
      (for example, if your new action name is <quote>Foo</quote> then copy
      <filename>/etc/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, QUEUE or
      &#60;action&#62; where &#60;action&#62; 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). 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 &#60;<emphasis>first ip</emphasis>&#62;-&#60;<emphasis>last
      ip</emphasis>&#62;.</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 &#60;<emphasis>low port</emphasis>&#62;:&#60;<emphasis>high
      port</emphasis>&#62;.</para>

      <para>This column is ignored if PROTOCOL = all but must be entered if
      any of the following ields 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&#39;t want to restrict client ports but need to specify
      an ADDRESS in the next column, then place &#34;-&#34; 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>     &#60;<emphasis>rate</emphasis>&#62;/&#60;<emphasis>interval</emphasis>&#62;[:&#60;<emphasis>burst</emphasis>&#62;]</programlisting>where
      &#60;<emphasis>rate</emphasis>&#62; is the number of connections per
      &#60;<emphasis>interval</emphasis>&#62; (<quote>sec</quote> or
      <quote>min</quote>) and &#60;<emphasis>burst</emphasis>&#62; is the
      largest burst permitted. If no &#60;<emphasis>burst</emphasis>&#62; 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>
  </itemizedlist>

  <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>
</article>