forked from extern/shorewall_code
4033e6051b
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@3521 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
480 lines
19 KiB
XML
Executable File
480 lines
19 KiB
XML
Executable File
<?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>2005-09-12</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
|
|
<<emphasis>action</emphasis>> where
|
|
<<emphasis>action</emphasis>> 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 <<emphasis>first
|
|
ip</emphasis>>-<<emphasis>last ip</emphasis>>.</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 <<emphasis>low
|
|
port</emphasis>>:<<emphasis>high port</emphasis>>.</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> <<emphasis>rate</emphasis>>/<<emphasis>interval</emphasis>>[:<<emphasis>burst</emphasis>>]</programlisting>where
|
|
<<emphasis>rate</emphasis>> is the number of connections per
|
|
<<emphasis>interval</emphasis>> (<quote>sec</quote> or
|
|
<quote>min</quote>) and <<emphasis>burst</emphasis>> is the
|
|
largest burst permitted. If no <<emphasis>burst</emphasis>> 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>[!]<<emphasis>user number</emphasis>>[:]</member>
|
|
|
|
<member>[!]<<emphasis>user name</emphasis>>[:]</member>
|
|
|
|
<member>[!]:<<emphasis>group number</emphasis>></member>
|
|
|
|
<member>[!]:<<emphasis>group name</emphasis>></member>
|
|
|
|
<member>[!]<<emphasis>user
|
|
number</emphasis>>:<<emphasis>group
|
|
number</emphasis>></member>
|
|
|
|
<member>[!]<<emphasis>user
|
|
name</emphasis>>:<<emphasis>group
|
|
number</emphasis>></member>
|
|
|
|
<member>[!]<<emphasis>user
|
|
inumber</emphasis>>:<<emphasis>group
|
|
name</emphasis>></member>
|
|
|
|
<member>[!]<<emphasis>user
|
|
name</emphasis>>:<<emphasis>group name</emphasis>></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> |