shorewall_code/docs/Actions-4.5.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Actions in Shorewall 4.5.0 and Later</title>

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

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

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

    <copyright>
      <year>2012</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 id="Intro">
    <title>What are Shorewall Actions?</title>

    <para>Shorewall actions allow a symbolic name to be associated with a
    series of one or more iptables rules. The symbolic name may appear in the
    ACTION column of an <filename><ulink
    url="manpages/shorewall-rules.html">/etc/shorewall/rules</ulink></filename>
    entry, in a <ulink url="Macros.html">macro</ulink> body and within another
    action, in which case the traffic matching that rules file entry will be
    passed to the series of iptables rules named by the action.</para>

    <para>Actions can be thought of as templates. When an action is invoked in
    an <filename>/etc/shorewall/rules</filename> entry, it may be qualified by
    a logging specification (log level and optionally a log tag). The presence
    of the log level/tag causes a modified series of rules to be generated in
    which each packet/rule match within the action causes a log message to be
    generated.</para>

    <para>For readers familiar with iptables, actions are the way in which you
    can create your own filter-table chains.</para>

    <para>There are three types of Shorewall actions:</para>

    <orderedlist>
      <listitem>
        <para>Built-in Actions. These actions are known by the Shorewall code
        itself. They are listed in the comments at the top of the file
        <filename>/usr/share/shorewall/actions.std</filename>.</para>
      </listitem>

      <listitem>
        <para>Standard Actions. These actions are released as part of
        Shorewall. They are listed in the file
        <filename>/usr/share/shorewall/actions.std</filename> and are defined
        in the corresponding action.* files in <filename
        class="directory">/usr/share/shorewall</filename>. Each
        <filename>action.*</filename> file has a comment at the beginning of
        the file that describes what the action does. Here is an
        example:</para>

        <programlisting>
# Shorewall version 4 - Drop Action
#
# /usr/share/shorewall/action.Drop
#
#	The default DROP common rules
#
#	This action is invoked before a DROP policy is enforced. The purpose
#	of the action is:
#
#	a) Avoid logging lots of useless cruft.
#	b) Ensure that 'auth' requests are rejected, even if the policy is
#	   DROP. Otherwise, you may experience problems establishing
#	   connections with servers that use auth.
#	c) Ensure that certain ICMP packets that are necessary for successful
#	   internet operation are always ACCEPTed.
#
#  The action accepts five optional parameters:
#
#	1 - 'audit' or '-'. Default is '-' which means don't audit in builtin
#           actions.
#       2 - Action to take with Auth requests. Default is REJECT or A_REJECT,
#           depending on the setting of the first parameter.
#	3 - Action to take with SMB requests. Default is DROP or A_DROP,
#           depending on the setting of the first parameter.
#       4 - Action to take with required ICMP packets. Default is ACCEPT or
#           A_ACCEPT depending on the first parameter.
#       5 - Action to take with late UDP replies (UDP source port 53). Default
#           is DROP or A_DROP depending on the first parameter.
#
# IF YOU ARE HAVING CONNECTION PROBLEMS, CHANGING THIS FILE WON'T HELP!!!!!!!!!
#
###############################################################################
FORMAT 2
#
# The following magic provides different defaults for $2 thru $5, when $1 is
# 'audit'.
#
?BEGIN PERL;
use Shorewall::Config;

my ( $p1, $p2, $p3 , $p4, $p5 ) = get_action_params( 5 );

if ( defined $p1 ) {
    if ( $p1 eq 'audit' ) {
	set_action_param( 2, 'A_REJECT')   unless supplied $p2;
	set_action_param( 3, 'A_DROP')     unless supplied $p3;
	set_action_param( 4, 'A_ACCEPT' )  unless supplied $p4;
	set_action_param( 5, 'A_DROP' )    unless supplied $p5;
    } else {
	fatal_error "Invalid value ($p1) for first Drop parameter" if supplied $p1;
    }
}

1;

?END PERL;

DEFAULTS -,REJECT,DROP,ACCEPT,DROP

#TARGET		SOURCE	DEST	PROTO	DPORT	SPORT
#
# Count packets that come through here
#
COUNT
#
# Reject 'auth'
#
Auth($2)
#
# Don't log broadcasts
#
Broadcast(DROP,$1)
#
# ACCEPT critical ICMP types
#
AllowICMPs($4)	-	-	icmp
#
# Drop packets that are in the INVALID state -- these are usually ICMP packets
# and just confuse people when they appear in the log.
#
Invalid(DROP,$1)
#
# Drop Microsoft noise so that it doesn't clutter up the log.
#
SMB($3)
DropUPnP($5)
#
# Drop 'newnotsyn' traffic so that it doesn't get logged.
#
NotSyn(DROP,$1)	-	-	tcp
#
# Drop late-arriving DNS replies. These are just a nuisance and clutter up
# the log.
#
DropDNSrep($5)
</programlisting>

        <para>Most of the standard actions use ?BEGIN PERL...?END PERL to
        perform special processing. See the Using Perl in Action files section
        for additional information.</para>

        <para>If you wish to modify one of the standard actions, do not modify
        the definition in <filename
        class="directory">/usr/share/shorewall</filename>. Rather, copy the
        file to <filename class="directory">/etc/shorewall</filename> (or
        somewhere else on your CONFIG_PATH) and modify the copy.</para>
      </listitem>

      <listitem>
        <para>User-defined Actions. These actions are created by end-users.
        They are listed in the file
        <filename>/etc/shorewall/actions</filename> and are defined in
        <filename>action.*</filename> files in <filename
        class="directory">/etc/shorewall</filename> or in another directory
        listed in your CONFIG_PATH (defined in <filename><ulink
        url="manpages/shorewall.conf.html">/etc/shorewall/shorewall.conf</ulink></filename>).</para>
      </listitem>
    </orderedlist>
  </section>

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

    <para>Shorewall allows the association of a <firstterm>default
    action</firstterm> with policies. A separate default action may be
    associated with ACCEPT, DROP, REJECT, QUEUE and NFQUEUE policies. Default
    actions provide a way to invoke a set of common rules just before the
    policy is enforced. Default actions accomplish two goals:</para>

    <orderedlist>
      <listitem>
        <para>Relieve log congestion. Default actions typically include rules
        to silently drop or reject traffic that would otherwise be logged when
        the policy is enforced.</para>
      </listitem>

      <listitem>
        <para>Ensure correct operation. Default actions can also avoid common
        pitfalls like dropping connection requests on port TCP port 113. If
        these connections are dropped (rather than rejected) then you may
        encounter problems connecting to Internet services that utilize the
        AUTH protocol of client authentication<footnote>
            <para>AUTH is actually pretty silly on today's Internet but it's
            amazing how many servers still employ it.</para>
          </footnote>.</para>
      </listitem>
    </orderedlist>

    <para>Shorewall supports default actions for the ACCEPT, REJECT, DROP,
    QUEUE and NFQUEUE policies. These default actions are specified in the
    <filename>/etc/shorewall/shorewall.conf</filename> file using the
    ACCEPT_DEFAULT, REJECT_DEFAULT, DROP_DEFAULT, QUEUE_DEFAULT and
    NFQUEUE_DEFAULT options respectively. Policies whose default is set to a
    value of <quote>none</quote> have no default action.</para>

    <para>In addition, the default specified in
    <filename>/etc/shorewall/shorewall.conf</filename> may be overridden by
    specifying a different action in the POLICY column of <filename><ulink
    url="manpages/shorewall-policy.html">/etc/shorewall/policy</ulink></filename>.</para>

    <important>
      <para>Entries in the DROP and REJECT default actions <emphasis
      role="bold">ARE NOT THE CAUSE OF CONNECTION PROBLEMS</emphasis>.
      Remember — default actions are only invoked immediately before the
      packet is going to be dropped or rejected anyway!!!</para>
    </important>

    <para>The standard Drop (see above) and Reject options are parameterized.
    Each has five parameters as follows:</para>

    <informaltable>
      <tgroup cols="4">
        <tbody>
          <row>
            <entry>ACTION</entry>

            <entry>PARAMETER</entry>

            <entry>VALUE</entry>

            <entry>DEFAULT</entry>
          </row>

          <row>
            <entry>Drop</entry>

            <entry>1</entry>

            <entry>Either '-' or 'audit'. 'audit' causes auditing by the
            builtin actions invoked by Drop</entry>

            <entry>-</entry>
          </row>

          <row>
            <entry>Drop</entry>

            <entry>2</entry>

            <entry>Determines what to do with Auth requests</entry>

            <entry>REJECT or A_REJECT depending on the setting of parameter
            1</entry>
          </row>

          <row>
            <entry>Drop</entry>

            <entry>3</entry>

            <entry>Determines what to do with SMB</entry>

            <entry>DROP or A_DROP depending on the setting of parameter
            1</entry>
          </row>

          <row>
            <entry>Reject</entry>

            <entry>1</entry>

            <entry>Either '-' or 'audit'. 'audit' causes auditing by the
            builtin actions invoked by Drop</entry>

            <entry>-</entry>
          </row>

          <row>
            <entry>Reject</entry>

            <entry>2</entry>

            <entry>Determines what to do with Auth requests</entry>

            <entry>REJECT or A_REJECT depending on the setting of parameter
            1</entry>
          </row>

          <row>
            <entry>Reject</entry>

            <entry>3</entry>

            <entry>Determines what to do with SMB</entry>

            <entry>REJECT or A_REJECT depending on the setting of parameter
            1</entry>
          </row>

          <row>
            <entry>Both</entry>

            <entry>4</entry>

            <entry>Determines what to do with accepted critical ICMP
            packets.</entry>

            <entry>ACCEPT or A_ACCEPT depending on the setting of parameter
            1</entry>
          </row>

          <row>
            <entry>Both</entry>

            <entry>5</entry>

            <entry>Determines what to do with late-arriving DNS replies
            (source port 53) or UPnP (udp port 1900).</entry>

            <entry>DROP or A_DROP depending on the setting of parameter
            1.</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>The parameters may be specified in either shorewall.conf (e.g.,
    DROP_DEFAULT=<emphasis role="bold">Drop(-,DROP)</emphasis> or in the
    POLICY column of <ulink
    url="manpages/shorewall-policy.html">shorewall-policy</ulink>(5) (e.g.,
    DROP:<emphasis role="bold">Drop(audit)</emphasis>:audit).</para>
  </section>

  <section>
    <title>Inline Actions</title>

    <para>Beginning with Shorewall 4.5.10, you may specify the inline option
    in <filename>/etc/shorewall/actions</filename>. As decribed above, </para>
  </section>
</article>