Macros
Tom
Eastep
Cristian
RodrÃguez
2005-09-12
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
.
This article applies to Shorewall 3.0 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.
What are Shorewall Macros?
Shorewall macros 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 file
entry and in the TARGET column of an action in which case, the traffic
matching that rules file entry will be passed to the series of iptables
rules named by the macro.
Macros can be thought of as templates. When a macro 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 macro causes a log message to be
generated.
There are two types of Shorewall macros:
Standard Macros. These macros are released as part of Shorewall.
They are defined in macros.* files in /usr/share/shorewall. Each
macros.* file has a comment at the beginning of
the file that describes what the macro does. As an example, here is
the definition of the SMB standard
macro.
#
# Shorewall 2.2 /usr/share/shorewall/macro.AllowSMB
#
# Allow Microsoft SMB traffic. You need to invoke this macro in
# both directions.
#
######################################################################################
#TARGET SOURCE DEST PROTO DEST SOURCE RATE USER/
# PORT PORT(S) LIMIT GROUP
PARAM - - udp 135,445
PARAM - - udp 137:139
PARAM - - udp 1024: 137
PARAM - - tcp 135,139,445
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
If you wish to modify one of the standard macros, 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.
User-defined Macros. These macros are created by end-users. They
are defined in macros.* files in /etc/shorewall or in another
directory listed in your CONFIG_PATH (defined in /etc/shorewall/shorewall.conf).
Defining your own Macros
To define a new macro:
Macro 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.
Copy /usr/share/shorewall/macro.template to
/etc/shorewall/macro.ActionName (for example, if
your new macro name is Foo
then copy
/usr/share/shorewall/macro.template to
/etc/shorewall/macro.Foo).
Now modify the new file to define the new macro.
Columns in the macro.template file are as follows:
ACTION - ACCEPT, DROP, REJECT, DNAT, DNAT-, REDIRECT, CONTINUE,
LOG, QUEUE, PARAM or an action name.
ACCEPT - allow the connection request
ACCEPT+ - like ACCEPT but also excludes the connection from
any subsequent DNAT[-] or REDIRECT[-] rules.
NONAT - Excludes the connection from any subsequent DNAT[-]
or REDIRECT[-] rules but doesn't generate a rule to accept the
traffic.
DROP - ignore the request
REJECT - disallow the request and return an icmp unreachable
or an RST packet.
DNAT - Forward the request to another address (and
optionally another port).
DNAT- - Advanced users only. Like DNAT but only generates
the DNAT iptables rule and not the companion ACCEPT rule.
SAME - Similar to DNAT except that the port may not be
remapped and when multiple server addresses are listed, all requests
from a given remote system go to the same server.
SAME- - Advanced users only. Like SAME but only generates
the SAME iptables rule and not the companion ACCEPT rule.
REDIRECT - Redirect the request to a local port on the
firewall.
REDIRECT- - Advanced users only. Like REDIRET but only
generates the REDIRECT iptables rule and not the companion ACCEPT
rule.
CONTINUE - (For experts only). Do not process any of the
following rules for this (source zone,destination zone). If The
source and/or destination If the address falls into a zone defined
later in /etc/shorewall/zones, this connection request will be
passed to the rules defined for that (those) zone(s).
LOG - Simply log the packet and continue.
QUEUE - Queue the packet to a user-space application such as
ftwall (http://p2pwall.sf.net).
The ACTION may optionally be followed by ":" and a syslog log
level (e.g, REJECT:info or DNAT:debug). This causes the packet to be
logged at the specified level.
(http://www.gnumonks.org/projects/ulogd).
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/macro.LogAndAccept LOG:info
ACCEPT
To use your macro, in /etc/shorewall/rules you
might do something like:
#ACTION SOURCE DEST PROTO DEST PORT(S)
LogAndAccept loc $FW tcp 22
Macros and Logging
Specifying a log level in a rule that invokes a user- or
Shorewall-defined action will cause each rule in the macro to be logged
with the specified level (and tag).
The extent to which logging of macro rules occur is governed by the
following:
When you invoke a macro and specify a log level, only those
rules in the macro that have no log level will be changed to log at
the level specified at the action invocation.
Example:
/etc/shorewall/macro.foo
#ACTION 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 invokeD 'foo' macro will be as if foo had been
defined as:
#ACTION 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 macro.
Example:
/etc/shorewall/macro.foo
#ACTION 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 invoked 'foo' macro will be as if foo had been
defined as:
#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT:debug - - tcp 22
bar:debug