Actions

Actions
Tom Eastep
Copyright 2005, 2007, 2008, 2009, 2010, 2012, 2013 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.
2013/02/14
Table of Contents
What are Shorewall Actions?
Default Actions (Formerly Common Actions)
Defining your own Actions
Shorewall 4.4.16 and Later.
Shorewall 4.4.15 and Earlier.
Actions and Logging
Using Embedded Perl in an Action
Creating an Action using an Extension Script (deprecated in favor of BEGIN PERL ... END PERL)
Limiting Per-IP Connection Rate using the Limit Action
How Limit is Implemented

Caution
This article applies to Shorewall 4.3 and later. If you are running a version of
Shorewall earlier than Shorewall 4.3.5 then please see the documentation for
that release.

What are Shorewall Actions?

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 /etc/shorewall/rules entry, in a macro
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.
Actions can be thought of as templates. When an action is invoked in an /etc/shorewall/rules 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.
For readers familiar with iptables, actions are the way in which you can create your own filter-table
chains.
There are three types of Shorewall actions:
1. Built-in Actions. These actions are known by the Shorewall code itself. They are listed in the
comments at the top of the file /usr/share/shorewall/actions.std.
2. Standard Actions. These actions are released as part of Shorewall. They are listed in the file
http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

/usr/share/shorewall/actions.std and are defined in the corresponding action.*

/usr/share/shorewall . Each action.* file has a comment at the beginning of the

files in
file that describes
what the action does. As an example, here is the definition of the AllowSMB standard action from
Shorewall version 2.2.
#
# Shorewall 2.2 /usr/share/shorewall/action.AllowSMB
#
#
Allow Microsoft SMB traffic. You need to invoke this action in
#
both directions.
#
######################################################################################
#TARGET SOURCE
DEST
PROTO
DEST
SOURCE
RATE
USER/
#
PORT
PORT(S)
LIMIT
GROUP
ACCEPT
udp
135,445
ACCEPT
udp
137:139
ACCEPT
udp
1024:
137
ACCEPT
tcp
135,139,445
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE

If you wish to modify one of the standard actions, do not modify the definition in
/usr/share/shorewall . Rather, copy the file to /etc/shorewall (or somewhere else on your
CONFIG_PATH) and modify the copy.
Standard Actions have been largely replaced by macros .
3. User-defined Actions. These actions are created by end-users. They are listed in the file
/etc/shorewall/actions and are defined in action.* files in /etc/shorewall or in another directory
listed in your CONFIG_PATH (defined in /etc/shorewall/shorewall.conf ).

Default Actions (Formerly Common Actions)

Shorewall allows the association of a default action 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:
1. Relieve log congestion. Default actions typically include rules to silently drop or reject traffic that
would otherwise be logged when the policy is enforced.
2. 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 [1].
Shorewall supports default actions for the ACCEPT, REJECT, DROP, QUEUE and NFQUEUE policies.
These default actions are specified in the /etc/shorewall/shorewall.conf 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 none have no default action.
In addition, the default specified in /etc/shorewall/shorewall.conf may be overridden by specifying a
different action in the POLICY column of /etc/shorewall/policy.

Important
Entries in the DROP and REJECT default actions ARE NOT THE CAUSE OF
CONNECTION PROBLEMS. Remember default actions are only invoked immediately
before the packet is going to be dropped or rejected anyway!!!
Beginning with Shorewall 4.4.21, the standard Drop and Reject options are parameterized. Each has five
parameters as follows:
ACTION PARAMETER VALUE
DEFAULT
Either '-' or 'audit'. 'audit' causes auditing by the
http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

Drop

Drop

Determines what to do with Auth requests

Drop

Determines what to do with SMB

Reject

Reject

Reject

Both

Both

Either '-' or 'audit'. 'audit' causes auditing by the builtin actions invoked by Drop
REJECT or A_REJECT
Determines what to do with Auth requests
depending on the setting of
parameter 1
REJECT or A_REJECT
Determines what to do with SMB
depending on the setting of
parameter 1
ACCEPT or A_ACCEPT
Determines what to do with accepted critical
depending on the setting of
ICMP packets.
parameter 1
Determines what to do with late-arriving DNS
DROP or A_DROP depending on
replies (source port 53) or UPnP (udp port
the setting of parameter 1.
1900).

builtin actions invoked by Drop

REJECT or A_REJECT
depending on the setting of
parameter 1
DROP or A_DROP depending on
the setting of parameter 1

The parameters may be specified in either shorewall.conf (e.g., DROP_DEFAULT=Drop(-,DROP) or in

the POLICY column of shorewall-policy(5) (e.g., DROP:Drop(audit):audit).

Defining your own Actions

Before defining a new action, you should evaluate whether your goal can be best accomplished using an
action or a macro. See this article for details.
To define a new action:
1. Add a line to /etc/shorewall/actions 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.
Normally. the rules in an action are placed in a separate chain. Beginning with Shorewall 4.5.10,
the action rules can be expanded inline in a manner similar to a macro by specifying inline in the
OPTIONS column of /etc/shorewall/actions.
Beginning in Shorewall 4.5.11, the nolog option may be specified; see the logging section below
for details.
Shorewall includes pre-defined actions for DROP and REJECT -- see above.
2. 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 ).
3. Now modify the new file to define the new action.

Shorewall 4.4.16 and Later.

Beginning with Shorewall 4.4.16, the columns in action.template are the same as those in shorewallhttp://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

rules (5). The first non-commentary line in the template must be

FORMAT 2

Beginning with Shorewall 4.5.11, the preferred format is as shown below, and the above format is
deprecated.
?FORMAT 2

When using Shorewall 4.4.16 or later, there are no restrictions regarding which targets can be used
within your action.
The SOURCE and DEST columns in the action file may not include zone names; those are given when
the action is invoked.
Additionally, it is possible to pass parameters to an action, when it is invoked in the rules file or in
another action.
Here's a trivial example:
/etc/shorewall/action.A:
#TARGET
#
FORMAT 2
$1

SOURCE

DEST

PROTO

DEST
SOURCE ORIGINAL
PORT(S) PORT(S) DEST

tcp

80

PROTO

DEST
SOURCE ORIGINAL
PORT(S) PORT(S) DEST

1.2.3.4

/etc/shorewall/rules:
#TARGET
#

SOURCE

DEST

A(REDIRECT)

net

fw

The above is equivalent to this rule:

#TARGET
#
REDIRECT

SOURCE

DEST

PROTO

net

tcp

DEST
SOURCE ORIGINAL
PORT(S) PORT(S) DEST
80
1.2.3.4

You can 'omit' parameters by using '-'.

Example: ACTION(REDIRECT,-,info)
In the above example, $2 would expand to nothing.
Beginning with Shorewall 4.5.13, completely omitting a arameter is equivalent to passing '-'.
Example: ACTION(REDIRECT,,info)
This example behaves the same as the one shown above.
If you refer to a parameter $n in the body of the action, then the nth paramer must either be passed to
all action invocations or it's default value must be established via a DEFAULTS line.
If you want to make '-' a parameter value, use '--' (e.g., ACTION(REDIRECT,--.info)).
Beginning with Shorewall 4.4.21, you can specify the default values of your FORMAT-2 actions:
DEFAULTS def1,def2,...

where def1 is the default value for the first parameter, def2 is the default value for the second
parameter and so on. You can specify an empty default using '-' (e.g. DEFAULTS DROP,-,audit).

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

For additional information about actions, see the Action Variables section of the Configuration Basics
article.

Shorewall 4.4.15 and Earlier.

Prior to 4.4.16, columns in the action.template file were as follows:
TARGET - Must be ACCEPT, DROP, REJECT, LOG, CONTINUE, QUEUE or an <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).
You may also use a macro in your action provided that the macro's expansion only results in the
ACTIONs ACCEPT, DROP, REJECT, LOG, CONTINUE, or QUEUE. See
/usr/share/shorewall/action.Drop for an example of an action that users macros extensively.
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.
PROTO - Protocol - Must be tcp, udp, icmp, a protocol 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 PROTO = all, but must be entered if any of the following fields are
supplied. In that case, it is suggested that this field contain -.
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 any of the subsequent fields, then
place - in this column.
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:
http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

[!]< user number >[:]

[!]< user name >[:]
[!]:<group number >
[!]:<group name >
[!]< user number >:<group number >
[!]< user name >:<group number >
[!]< user inumber>:<group name >
[!]< user name >:<group name >
[!]+<program name > (Note: support for this form was removed from Netfilter in kernel version
2.6.14).
MARK
[!]< value >[/<mask>][:C]
Defines a test on the existing packet or connection mark. The rule will match only if the test
returns true.
If you dont want to define a test but need to specify anything in the subsequent columns, place a
- in this field.
! Inverts the test (not equal)
<value > Value of the packet or connection mark.
<mask> A mask to be applied to the mark before testing.
:C Designates a connection mark. If omitted, the packet marks value is tested. This option is
only supported by Shorewall-perl
Omitted column entries should be entered using a dash (-).
Example:
/etc/shorewall/actions :
#ACTION
#
LogAndAccept

COMMENT (place '# ' below the 'C' in comment followed by

v
a comment describing the action)
# LOG and ACCEPT a connection

Note: If your /etc/shorewall/actions file doesn't have an indication where to place the comment, put
the # in column 21.
/etc/shorewall/action.LogAndAccept
LOG:info
ACCEPT

Placing a comment on the line causes the comment to appear in the output of the shorewall show
actions command.
To use your action, in /etc/shorewall/rules you might do something like:
#ACTION
SOURCE
LogAndAccept loc

DEST
$FW

PROTO
tcp

DEST PORT(S)
22

Actions and Logging

Specifying a log level in a rule that specifies a user-defined or Shorewall-defined action will cause each
rule in the action to be logged with the specified level (and tag), unless the nolog option is specified in

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

the action's entry in /etc/shorewall/actions.

The extent to which logging of action rules occur is governed by the following:
1. 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
ACCEPT
bar:info

SOURCE
-

DEST
-

PROTO
tcp

DEST PORT(S)
22

DEST
net

PROTO

DEST PORT(S)

/etc/shorewall/rules:
#ACTION
foo:debug

SOURCE
$FW

Logging in the invoke foo action will be as if foo had been defined as:
#TARGET
SOURCE
ACCEPT:debug bar:info

DEST
-

PROTO
tcp

DEST PORT(S)
22

2. If you follow the log level with ! then logging will be set at that level for all rules recursively
invoked by the action.
Example:
/etc/shorewall/action.foo
#TARGET
ACCEPT
bar:info

SOURCE
-

DEST
-

PROTO
tcp

DEST PORT(S)
22

DEST
net

PROTO

DEST PORT(S)

/etc/shorewall/rules:
#ACTION
foo:debug!

SOURCE
$FW

Logging in the invoke foo action will be as if foo had been defined as:
#TARGET
SOURCE
ACCEPT:debug bar:debug

DEST
-

PROTO
tcp

DEST PORT(S)
22

Using Embedded Perl in an Action

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 . Such rules can be constructed using Embedded Perl. For those
who are comfortable using Perl, embedded Perl is more efficient that using complicated conditional
entries. The Perl compiler is invoked only once for a BEGIN PERL...END PERL block; it is invoked most
times that an expression is evaluated in an ?IF, ?ELSEIF or ?SET directive.
The Shorewall compiler provides a set of services that are available to Perl code embedded in an action
file. These services are not available in in-line actions when running Shorewall 4.5.12 or earlier.
Shorewall::Config::get_action_params( $howmany )
This function returns an array containing the functions parameters. The scalar argument $howmany
is the number of parameters that you expect to be passed. You can ensure that at least this many
http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

parameters are passed by including a DEFAULTS line prior to the embedded Perl.
Shorewall::Config::set_action_param( $ordinal , $value )
Set the value of parameter $ordinal to $value. Care must be take when using this function such
that for a given set of parameters actually passed to the action, the same rules are created. That is
because the compiler assumes that all invocations of an action with the same parameters, log level
and log tag can share the same action chain.
Shorewall::Config::get_action_chain()
This function returns a reference to the chain table entry for the current action chain.
Shorewall::Config::get_action_logging()
Returns a two-element list containing the the log level and log tag specified when the action was
invoked. Note that you must use this function rather than @loglevel and @logtag within embedded
Perl, as the compiler does not expand Shorewall Variables within embedded Perl (or embedded
shell).
Shorewall::Chains::add_rule( $chainre f, $rule [, $expandports ] )
This function adds a rule to a chain. As of Shoreall 4.5.13, it is deprecated in favor of
Shorewall::Rules::perl_action_helper(). Arguments are:
$chainref

Normally, you get this from get_action_chain() described above.

$rule

The matches and target for the rule that you want added.
$expandports

(optional)

This optional argument is for compiler-internal use only. Either omit it or pass a false value.

Warning
Do not call this function in a inline action. Use perl_action_helper() instead (see
below).
Shorewall::Chains::log_rule_limit( $level, $chainref , $chain, $disposition, $limit, $tag , $command ,
$matches )
This function adds a logging rule to a chain. As of Shoreall 4.5.13, it is deprecated in favor of
Shorewall::Rules::perl_action_helper(). Arguments are:
$level

Either a syslog level or a ULOG or NFLOG target expression (e.g., "NFLOG(1,0,1)"). Specifies
how you want the logging done.
$chainref

Normally, you get this from get_action_chain() described above.

$chain

The value you want substituted for the first %s formatting directive in the LOGFORMAT
setting in /etc/shorewall/shorewall.conf .
$disposition

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

This is the value substituted for the second '%s' formatting directive in the LOGFORMAT
setting in /etc/shorewall/shorewall.conf .
$limit

If you want to use the default limit set in LOGLIMIT ( /etc/shorewall/shorewall.conf ), you
can specify your own '-limit' match. Otherwise, if you want to use the default, pass 0 or "". If
you want the rule to be unlimited, pass '-'.
$tag

Log tag.
$command

Pass 'add' here, unless you want the rule to be inserted at the front of the chain.

$matches
Zero or more iptables matches that limit when logging will occur. If this parameter is other
than the empty string, the last character must be a space.
Shorewall::Chains::allow::optimize( $chainref )
This allows the passed action chain to be optimized away (jumps to the chain are replaced by the
chain's rule(s)). The chainref argument is usually obtained from get_action_chain() described
above.
Shorewall::Rules::perl_action_helper( $target, $matches )
This function adds a rule to the current chain. For a regular action, the chain will be an action
chain; for an inline action, the chain is determined by the invoking rule.
To use this function, you must include:
use Shorewall::Rules;
Arguments are:
$target
The target of the rule. Legal values are anything that can appear in the TARGET column of in
an action body and may include log level, tag, and parameters.
$matches
ip[6]tables matches to be included in the rule. When called in an inline action, these matches
are augmented by matches generated by the invoking rule.

Note
This function has additional optional arguments which are used internally by
Shorewall standard actions. Their number and behavior is likely to change in future
Shorewall releases.
For an example of using these services, look at the standard action
/usr/share/shorewall/action.TCPFlags.

Creating an Action using an Extension Script (deprecated in

favor of BEGIN PERL ... END PERL)
http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

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
If you actually need an action to drop broadcast packets, use the dropBcast standard
action rather than create one like this.
Example1.An action to drop all broadcast packets
If you define an action acton and you have an /etc/shorewall/acton script, the rules compiler sets
lexical variables as follows:
$chainref is a reference to the chain-table entry for the chain where your rules are to be placed.
$level is the log level. If false, no logging was specified.
$tag is the log tag.
@params is the list of parameter values (Shorewall 4.4.16 and later). 'Omitted' parameters
contain '-'.
Example:
/etc/shorewall/actions
DropBcasts

/etc/shorewall/action.DropBcasts
# This file is empty

/etc/shorewall/DropBcasts
use Shorewall::Chains;
if ( $level ne '' ) {
log_rule_limit $level, $chainref, 'dropBcast' , 'DROP', '', $tag, 'add', ' -m addrtype -dst-type BROADCAST ';
log_rule_limit $level, $chainref, 'dropBcast' , 'DROP', '', $tag, 'add', ' -d 224.0.0.0/4
';
}
add_rule $chainref, '-m addrtype --dst-type BROADCAST -j DROP';
add_rule $chainref, '-d 224.0.0.0/4 -j DROP';
1;

For a richer example, see the next section.

Limiting Per-IP Connection Rate using the Limit Action

Shorewall supports a Limit built-in action. Prior to Shorewall 4.4.16, Limit is invoked with a commaseparated list in place of a logging tag. Beginning in Shorewall 4.4.16, it may also be invoked with a list
of three parameters enclosed in parentheses. The list has three elements:
1. The name of a recent list. You select the list name which must conform to the rules for a valid
chain name. Different rules that specify the same list name will use the same set of counters.
2. The number of connections permitted in a specified time period.

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

3. The time period, expressed in seconds.

Connections that exceed the specified rate are dropped.
For example, to use a recent list name of SSHA, and to limit SSH connections to 3 per minute, use this
entry in /etc/shorewall/rules :
#ACTION
Limit:none:SSHA,3,60

SOURCE
net

DEST
$FW

PROTO
tcp

DEST PORT(S)
22

Using Shorewall 4.4.16 or later, you can also invoke the action this way:
#ACTION
Limit(SSHA,3,60):none

SOURCE
net

DEST
$FW

PROTO
tcp

DEST PORT(S)
22

If you want dropped connections to be logged at the info level, use this rule instead:
#ACTION
Limit:info:SSHA,3,60

SOURCE
net

DEST
$FW

PROTO
tcp

DEST PORT(S)
22

DEST
$FW

PROTO
tcp

DEST PORT(S)
22

Shorewall 4.4.16 and later:

#ACTION
Limit(SSH,3,60):info

SOURCE
net

To summarize, you pass four pieces of information to the Limit action:

The log level. If you don't want to log, specify none.
The name of the recent list that you want to use (SSHA in this example).
The maximum number of connections to accept (3 in this example).
The number of seconds over which you are willing to accept that many connections (60 in this
example).

How Limit is Implemented

For those who are curious, the Limit action in Shorewall 4.4.16 is implemented as follows:
use Shorewall::Chains;
@params = split( /,/, $tag ), $tag='' unless @params;
fatal_error 'Limit rules must include <list name>,<max connections>,<interval> as the log tag
or params' unless @params == 3;
my $list = $params[0];
for ( @params[1,2] ) {
fatal_error 'Max connections and interval in Limit rules must be numeric (' . $_ . ')'
unless /^\d+$/
}
my $count = $params[1] + 1;
add_rule $chainref, "-m recent --name $list --set";
if ( $level ) {
my $xchainref = new_chain 'filter' , "$chainref->{name}%";
log_rule_limit $level, $xchainref, $params[0], 'DROP', $tag, '', 'add', '';
add_rule $xchainref, '-j DROP';
add_rule $chainref, "-m recent --name $list --update --seconds $params[2] --hitcount
$count -j $xchainref->{name}";
} else {
add_rule $chainref, "-m recent --update --name $list --seconds $params[2] --hitcount
$count -j DROP";
}
add_rule $chainref, '-j ACCEPT';

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]

Actions

1;

[1]

AUTH is actually pretty silly on today's Internet but it's amazing how many servers still employ it.

http://shorewall.net/Actions.html[2013-03-15 12:31:07 ]