Copyright © 2003, 2004, 2005 Thomas M. Eastep
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 “GNU Free Documentation License”.
2007/02/09
Table of Contents
Prior to Shorewall version 1.4.9, rules in
/etc/shorewall/rules
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.
To define a new action:
Add a line to
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./etc/shorewall/actions
Beginning with Shorewall-2.0.0-Beta1, the name of the action may be optionally followed by a colon (“:”) and ACCEPT, DROP or REJECT. When this is done, the named action will become the default action for policies of type ACCEPT, DROP or REJECT respectively. The default 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.
Shorewall includes pre-defined actions for DROP and REJECT -- see below.
Once you have defined your new action name (ActionName), then
copy /usr/share/shorewall/action.template to
/etc/shorewall/action.ActionName
(for example, if
your new action name is “Foo” then copy
/usr/share/shorewall/action.template
to
/etc/shorewall/action.Foo
).
Now modify the new file to define the new action.
Columns in the action.template file are as follows:
TARGET - Must be ACCEPT, DROP, REJECT, LOG, CONTINUE, QUEUE or
<action> where
<action> is a previously-defined action
(that is, it must precede the action being defined in this file in
your /etc/shorewall/actions
file). These actions
have the same meaning as they do in the
/etc/shorewall/rules
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
(“:”) 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 (http://www.netfilter.org/projects/ulogd/index.html).
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 “~” and must use “-” as a separator.
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 (“:”) and an IP/MAC/subnet address as described above (e.g., eth1:192.168.1.5).
DEST - Location of Server. Same as above with the exception that MAC addresses are not allowed.
Unlike in the SOURCE column, you may specify a range of up to 256 IP addresses using the syntax <first ip>-<last ip>.
PROTO - Protocol - Must be “tcp”, “udp”, “icmp”, a number, or “all”.
DEST PORT(S) - Destination Ports. A comma-separated list of Port
names (from /etc/services
), port numbers or port
ranges; if the protocol is “icmp”, this column is
interpreted as the destination icmp-type(s).
A port range is expressed as <low port>:<high port>.
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 “-”.
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:
There are 15 or less ports listed.
No port ranges are included.
Otherwise, a separate rule will be generated for each port.
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.
If you don't want to restrict client ports but need to specify an ADDRESS in the next column, then place "-" in this column.
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:
There are 15 or less ports listed.
No port ranges are included.
Otherwise, a separate rule will be generated for each port.
RATE LIMIT - You may rate-limit the rule by placing a value in this column:
<rate>/<interval>[:<burst>]
where <rate> is the number of connections per <interval> (“sec” or “min”) and <burst> is the largest burst permitted. If no <burst> is given, a value of 5 is assumed. There may be no whitespace embedded in the specification.
Example: 10/sec:20
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:
[!]<user number>[:] |
[!]<user name>[:] |
[!]:<group number> |
[!]:<group name> |
[!]<user number>:<group number> |
[!]<user name>:<group number> |
[!]<user inumber>:<group name> |
[!]<user name>:<group name> |
Omitted column entries should be entered using a dash ("-:).
Example:
/etc/shorewall/actions
:
LogAndAccept
/etc/shorewall/action.LogAndAccept
LOG:info ACCEPT
To use your action, in /etc/shorewall/rules
you
might do something like:
#ACTION SOURCE DEST PROTO DEST PORT(S) LogAndAccept loc $FW tcp 22
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).
The extent to which logging of action rules occur is governed by the following:
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.
Example:
/etc/shorewall/action.foo
#TARGET SOURCE DEST PROTO DEST PORT(S) ACCEPT - - tcp 22 bar:info
/etc/shorewall/rules:
#ACTION SOURCE DEST PROTO DEST PORT(S) foo:debug $FW net
Logging in the invoke 'foo' action will be as if foo had been defined as:
#TARGET SOURCE DEST PROTO DEST PORT(S) ACCEPT:debug - - tcp 22 bar:info
If you follow the log level with "!" then logging will be at that level for all rules recursively invoked by the action.
Example:
/etc/shorewall/action.foo
#TARGET SOURCE DEST PROTO DEST PORT(S) ACCEPT - - tcp 22 bar:info
/etc/shorewall/rules:
#ACTION SOURCE DEST PROTO DEST PORT(S) foo:debug! $FW net
Logging in the invoke 'foo' action will be as if foo had been defined as:
#TARGET SOURCE DEST PROTO DEST PORT(S) ACCEPT:debug - - tcp 22 bar:debug
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 /etc/shorewall/acton
script then when that
script is invoked, the following three variables will be set for use by
the script:
$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.
$LEVEL = Log level. If empty, no logging was specified.
$TAG = Log Tag.
Example:
/etc/shorewall/rules
:
#ACTION SOURCE DEST acton:info:test $FW net
Your /etc/shorewall/acton file will be run with:
$CHAIN="%acton1"
$LEVEL="info"
$TAG="test"
Beginning with Shorewall 2.0.0-Beta1, Shorewall includes a number of
pre-defined actions. These defined actions are listed in
/usr/share/shorewall/actions.std
.
Example 1. Example of Using a Standard Action
Suppose that you wish to enable ftp from your local network to
your firewall. In /etc/shorewall/rules
:
#ACTION SOURCE DEST PROTO ... AllowFTP loc $FW
/usr/share/shorewall/actions.std
is processed
before /etc/shorewall/actions
and if you have any
actions defined with the same name as one in
/usr/share/shorewall/actions.std
, your version in
/etc/shorewall
will be the one
used. So if you wish to modify a standard action, simply copy the
associated action file from /usr/share/shorewall
to /etc/shorewall and modify
it to suit your
needs. The next shorewall restart will cause your
action to be installed in place of the standard one. In particular, if you
want to modify the default actions “Drop” or
“Reject”, simply copy action.Drop
or
Action.Reject
to /etc/shorewall
and modify that copy as
desired.
Some of the standard actions are built-ins. This means that there is no corresponding action.* file and that Shorewall constructs the rules for the actions using direct iptables commands. If you need to modify one of these built-in actions, you will need to use the Extension Script mechanism described below and you will need to give the action a different name.
Also beginning with Shorewall version 2.2.0-Beta1, when an ACCEPT, DROP or REJECT policy is about to be enforced, a default action can first be invoked. In /etc/shorewall/actions.std are found these two entries:
Drop:DROP #Default Action for DROP policy Reject:REJECT #Default Action for REJECT policy
These entries designate the action named Drop as the default action for DROP policies and the default action Reject as the default action for REJECT policies.
The purpose of default actions is:
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 DropSMB action.
To ensure proper behavior. For example, both the Drop and Reject actions invoke the RejectAuth 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.
It should be stressed that the default actions do not cause any traffic to be dropped or rejected that isn't about to be dropped or rejected anyway (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.
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.
If you actually need an action to drop broadcast packets, use the dropBcast standard action rather than create one like this.
Example 2. An action to drop all broadcast packets
/etc/shorewall/actions
DropBcasts
/etc/shorewall/action.DropBcasts
# This file is empty
/etc/shorewall/DropBcasts
run_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP