1
0
shorewall_code/docs/Actions-4.5.xml
Tom Eastep 56d7b6248b Begin Action Documentaiton Update
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2012-12-05 19:07:42 -08:00

368 lines
12 KiB
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>