<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Macros</title><link rel="stylesheet" href="html.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id257505"></a>Macros</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Eastep</span></h3></div><div class="author"><h3 class="author"><span class="firstname">Cristian</span> <span class="surname">Rodríguez</span></h3></div></div></div><div><p class="copyright">Copyright © 2005 Thomas M. Eastep</p></div><div><div class="legalnotice"><a id="id257922"></a><p>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
“<span class="quote"><a class="ulink" href="GnuCopyright.htm" target="_self">GNU Free Documentation
License</a></span>”.</p></div></div><div><p class="pubdate">2008/12/15</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#Overview">Overview of Shorewall Macros?</a></span></dt><dt><span class="section"><a href="#Default">Default Macros</a></span></dt><dt><span class="section"><a href="#Defining">Defining your own Macros</a></span></dt><dt><span class="section"><a href="#Logging">Macros and Logging</a></span></dt><dt><span class="section"><a href="#ActionOrMacro">How do I know if I should create an Action or a Macro?</a></span></dt></dl></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p><span class="bold"><strong>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.</strong></span></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Overview"></a>Overview of Shorewall Macros?</h2></div></div></div><p>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 <code class="filename"><a class="ulink" href="manpages/shorewall-rules.html" target="_self">/etc/shorewall/rules</a></code>
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.</p><p>Macros can be thought of as templates. When a macro is invoked in an
<code class="filename">/etc/shorewall/rules</code> 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.</p><p>There are two types of Shorewall macros:</p><div class="orderedlist"><ol type="1"><li><p>Standard Macros. These macros are released as part of Shorewall.
They are defined in macros.* files in <code class="filename">/usr/share/shorewall</code>. Each
<code class="filename">macros.*</code> 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 <em class="firstterm">SMB</em> standard
macro.</p><pre class="programlisting">#
# Shorewall 3.0 /usr/share/shorewall/macro.SMB
#
# Handle 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</pre><p>If you wish to modify one of the standard macros, do not modify
the definition in /usr/share/shorewall. Rather, copy the file to
<code class="filename">/etc/shorewall</code> (or somewhere
else on your CONFIG_PATH) and modify the copy.</p></li><li><p>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 <a class="ulink" href="manpages/shorewall.conf.html" target="_self">/etc/shorewall/shorewall.conf</a>).</p></li></ol></div><p>Most Standard Macros are <em class="firstterm">parameterized</em>. That
means that you specify what you want to do (ACCEPT, DROP, REJECT, etc.)
when you invoke the macro. The SMB macro shown above is parameterized
(note PARAM in the TARGET column).</p><p><span class="bold"><strong>Shorewall versions prior to 4.2.0:</strong></span>
When invoking a parameterized macro, you follow the name of the macro with
a slash ("/") and the action that you want to substitute for PARAM.</p><p>Example:</p><div class="blockquote"><blockquote class="blockquote"><p>/etc/shorewall/rules:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMB/ACCEPT loc fw </pre><p>The above is equivalent to coding the following series of
rules:</p><pre class="programlisting">#TARGET SOURCE DEST PROTO DEST PORT(s)
ACCEPT loc fw udp 135,445
ACCEPT loc fw udp 137:139
ACCEPT loc fw udp 1024: 137
ACCEPT loc fw tcp 135,139,445</pre></blockquote></div><p><span class="bold"><strong>Shorewall versions 4.2.0 and later:</strong></span>
When invoking a parameterized macro, you follow the name of the macro with
the action that you want to substitute for PARAM enclosed in parentheses.
The older syntax described above is still supported but is
deprecated.</p><p>Example:</p><div class="blockquote"><blockquote class="blockquote"><p>/etc/shorewall/rules:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMB(ACCEPT) loc fw </pre><p>The above is equivalent to coding the following series of
rules:</p><pre class="programlisting">#TARGET SOURCE DEST PROTO DEST PORT(s)
ACCEPT loc fw udp 135,445
ACCEPT loc fw udp 137:139
ACCEPT loc fw udp 1024: 137
ACCEPT loc fw tcp 135,139,445</pre></blockquote></div><p>Logging is covered in <a class="link" href="#Logging" title="Macros and Logging">a following
section</a>. The other columns are treated as follows:</p><div class="variablelist"><dl><dt><span class="term">SOURCE and DEST</span></dt><dd><p>If a value other than "-" appears in both the macro body and
in the invocation of the macro, then the value in the invocation is
examined and the appropriate action is taken (you will want to be
running Shorewall 3.0.1 or later). If the value in the invocation
appears to be an address (IP or MAC) or the name of an ipset, then
it is placed after the value in the macro body. Otherwise, it is
placed before the value in the macro body.</p><p>Example 1:</p><div class="blockquote"><blockquote class="blockquote"><p>/etc/shorewall/macro.SMTP</p><pre class="programlisting">#TARGET SOURCE DEST PROTO DEST PORT(S)
PARAM - loc tcp 25</pre><p>/etc/shorewall/rules (Shorewall 4.0):</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMTP/DNAT:info net 192.168.1.5</pre><p>/etc/shorewall/rules (Shorewall 4.2.0 and later):</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMTP(DNAT):info net 192.168.1.5</pre><p>This would be equivalent to coding the following directly in
/etc/shorewall/rules</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT:info net loc:192.168.1.5 tcp 25</pre></blockquote></div><p>Example 2:</p><div class="blockquote"><blockquote class="blockquote"><p>/etc/shorewall/macro.SMTP</p><pre class="programlisting">#TARGET SOURCE DEST PROTO DEST PORT(S)
PARAM - 192.168.1.5 tcp 25</pre><p>/etc/shorewall/rules (Shorewall 4.0)</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMTP/DNAT:info net loc</pre><p>/etc/shorewall/rules (Shorewall 4.2.0 and later)</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMTP(DNAT):info net loc</pre><p>This would be equivalent to coding the following directly in
/etc/shorewall/rules</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT:info net loc:192.168.1.5 tcp 25</pre></blockquote></div><p>Beginning with Shorewall 3.1, you may also specify SOURCE or
DEST in the SOURCE and DEST columns. This allows you to define
macros that work in both directions.</p><p>Example 3:</p><div class="blockquote"><blockquote class="blockquote"><p><code class="filename">/etc/shorewall/macro.SMBBI</code> (Note: there
is already a macro like this released as part of Shorewall 3.1 and
later):</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/
# PORT PORT(S) DEST LIMIT GROUP
PARAM - - udp 135,445
PARAM - - udp 137:139
PARAM - - udp 1024: 137
PARAM - - tcp 135,139,445
PARAM DEST SOURCE udp 135,445
PARAM DEST SOURCE udp 137:139
PARAM DEST SOURCE udp 1024: 137
PARAM DEST SOURCE tcp 135,139,445
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</pre><p>/etc/shorewall/rules (Shorewall 4.0):</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMBBI/ACCEPT loc fw</pre><p>/etc/shorewall/rules (Shorewall 4.2.0 and later):</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
SMBBI(ACCEPT) loc fw</pre><p>This would be equivalent to coding the following directly in
/etc/shorewall/rules</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT loc fw udp 135,445
ACCEPT loc fw udp 137:139
ACCEPT loc fw udp 1024: 137
ACCEPT loc fw tcp 135,139,445
ACCEPT fw loc udp 135,445
ACCEPT fw loc udp 137:139
ACCEPT fw loc udp 1024: 137
ACCEPT fw loc tcp 135,139,445</pre></blockquote></div></dd><dt><span class="term">Remaining columns</span></dt><dd><p>Any value in the invocation replaces the value in the rule in
the macro.</p></dd></dl></div><p>One remaining restriction should be noted: macros that are invoked
from actions cannot themselves invoke other actions.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Default"></a>Default Macros</h2></div></div></div><p>Beginning with Shorewall release 3.4, Shorewall supports
<em class="firstterm">default macros</em>; default macros perform the same
function as <a class="ulink" href="???" target="_self">default actions</a>. The DEFAULT_ACCEPT,
DEFAULT_REJECT, DEFAULT_DROP and DEFAULT_QUEUE options in
<code class="filename">/etc/shorewall/shorewall.conf</code> may specify the name of
a macro. In that case, the rules in the macro will be traversed before the
associated policy is applied.</p><p>The value of the …_DEFAULT settings is interpreted as follows. If
USE_ACTIONS=Yes in shorewall.conf, then the value is treated like the name
of an action -- if that action is not found, then the value is treated
like the name of a macro. If USE_ACTIONS=No, then the value is treated
like the name of a macro. The special value "none" is always interpreted
as "no default rules should be applied".</p><p>Shorewall versions 3.4 and later include standard 'Reject' and
'Drop' macros that are equivalent to the 'Reject' and 'Drop'
actions.</p><p>Default Macros are not supported by Shorewall-perl.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Defining"></a>Defining your own Macros</h2></div></div></div><p>To define a new macro:</p><div class="orderedlist"><ol type="1"><li><p>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.</p></li><li><p>Copy /usr/share/shorewall/macro.template to
<code class="filename">/etc/shorewall/macro.MacroName</code> (for example, if
your new macro name is “<span class="quote">Foo</span>” then copy
<code class="filename">/usr/share/shorewall/macro.template</code> to
<code class="filename">/etc/shorewall/macro.Foo</code>).</p></li><li><p>Now modify the new file to define the new macro.</p></li></ol></div><p>Columns in the macro.template file are as follows:</p><div class="itemizedlist"><ul type="disc"><li><p>ACTION - ACCEPT, DROP, REJECT, DNAT, DNAT-, REDIRECT, CONTINUE,
LOG, QUEUE, PARAM or an action name. Note that a macro may not invoke
another macro.</p><table class="simplelist" border="0" summary="Simple list"><tr><td>ACCEPT - allow the connection request</td></tr><tr><td>ACCEPT+ - like ACCEPT but also excludes the connection from
any subsequent DNAT[-] or REDIRECT[-] rules.</td></tr><tr><td>NONAT - Excludes the connection from any subsequent DNAT[-]
or REDIRECT[-] rules but doesn't generate a rule to accept the
traffic.</td></tr><tr><td>DROP - ignore the request</td></tr><tr><td>REJECT - disallow the request and return an icmp unreachable
or an RST packet.</td></tr><tr><td>DNAT - Forward the request to another address (and
optionally another port).</td></tr><tr><td>DNAT- - Advanced users only. Like DNAT but only generates
the DNAT iptables rule and not the companion ACCEPT rule.</td></tr><tr><td>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.</td></tr><tr><td>SAME- - Advanced users only. Like SAME but only generates
the SAME iptables rule and not the companion ACCEPT rule.</td></tr><tr><td>REDIRECT - Redirect the request to a local port on the
firewall.</td></tr><tr><td>REDIRECT- - Advanced users only. Like REDIRECT but only
generates the REDIRECT iptables rule and not the companion ACCEPT
rule.</td></tr><tr><td>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).</td></tr><tr><td>LOG - Simply log the packet and continue.</td></tr><tr><td>QUEUE - Queue the packet to a user-space application such as
ftwall (http://p2pwall.sf.net).</td></tr></table><p>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.</p></li><li><p>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 “<span class="quote">~</span>”
and must use “<span class="quote">-</span>” as a separator.</p><p>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
(“<span class="quote">:</span>”) and an IP/MAC/subnet address as described above
(e.g. eth1:192.168.1.5).</p><p>May also contain 'DEST' as described above.</p></li><li><p>DEST - Location of Server. Same as above with the exception that
MAC addresses are not allowed.</p><p>Unlike in the SOURCE column, you may specify a range of up to
256 IP addresses using the syntax <<span class="emphasis"><em>first
ip</em></span>>-<<span class="emphasis"><em>last ip</em></span>>.</p><p>May also contain 'SOURCE' as described above.</p></li><li><p>PROTO - Protocol - Must be “<span class="quote">tcp</span>”,
“<span class="quote">udp</span>”, “<span class="quote">icmp</span>”, a number, or
“<span class="quote">all</span>”.</p></li><li><p>DEST PORT(S) - Destination Ports. A comma-separated list of Port
names (from <code class="filename">/etc/services</code>), port numbers or port
ranges; if the protocol is “<span class="quote">icmp</span>”, this column is
interpreted as the destination icmp-type(s).</p><p>A port range is expressed as <<span class="emphasis"><em>low
port</em></span>>:<<span class="emphasis"><em>high port</em></span>>.</p><p>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 “<span class="quote">-</span>”.</p><p>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:</p><div class="orderedlist"><ol type="1"><li><p>There are 15 or less ports listed.</p></li><li><p>No port ranges are included.</p></li></ol></div><p>Otherwise, a separate rule will be generated for each
port.</p></li><li><p>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.</p><p>If you don't want to restrict client ports but need to specify
an ADDRESS in the next column, then place "-" in this column.</p><p>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:</p><div class="orderedlist"><ol type="1"><li><p>There are 15 or less ports listed.</p></li><li><p>No port ranges are included.</p></li></ol></div><p>Otherwise, a separate rule will be generated for each
port.</p></li><li><p>RATE LIMIT - You may rate-limit the rule by placing a value in
this column:</p><pre class="programlisting"> <<span class="emphasis"><em>rate</em></span>>/<<span class="emphasis"><em>interval</em></span>>[:<<span class="emphasis"><em>burst</em></span>>]</pre><p>where
<<span class="emphasis"><em>rate</em></span>> is the number of connections per
<<span class="emphasis"><em>interval</em></span>> (“<span class="quote">sec</span>” or
“<span class="quote">min</span>”) and <<span class="emphasis"><em>burst</em></span>> is the
largest burst permitted. If no <<span class="emphasis"><em>burst</em></span>> is
given, a value of 5 is assumed. There may be no whitespace embedded in
the specification.</p><pre class="programlisting"> Example: 10/sec:20</pre></li><li><p>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:</p><table class="simplelist" border="0" summary="Simple list"><tr><td>[!]<<span class="emphasis"><em>user number</em></span>>[:]</td></tr><tr><td>[!]<<span class="emphasis"><em>user name</em></span>>[:]</td></tr><tr><td>[!]:<<span class="emphasis"><em>group number</em></span>></td></tr><tr><td>[!]:<<span class="emphasis"><em>group name</em></span>></td></tr><tr><td>[!]<<span class="emphasis"><em>user
number</em></span>>:<<span class="emphasis"><em>group
number</em></span>></td></tr><tr><td>[!]<<span class="emphasis"><em>user
name</em></span>>:<<span class="emphasis"><em>group
number</em></span>></td></tr><tr><td>[!]<<span class="emphasis"><em>user
inumber</em></span>>:<<span class="emphasis"><em>group
name</em></span>></td></tr><tr><td>[!]<<span class="emphasis"><em>user
name</em></span>>:<<span class="emphasis"><em>group name</em></span>></td></tr><tr><td>[!]+<<span class="emphasis"><em>program name</em></span>> (Note: support
for this form was removed from Netfilter in kernel version
2.6.14).</td></tr></table></li></ul></div><p>Omitted column entries should be entered using a dash ("-:).</p><p>Example:</p><p><span><code class="filename">/etc/shorewall/macro.LogAndAccept</code></span></p><pre class="programlisting"> LOG:info
ACCEPT</pre><p>To use your macro, in <code class="filename">/etc/shorewall/rules</code> you
might do something like:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
LogAndAccept loc $FW tcp 22</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Logging"></a>Macros and Logging</h2></div></div></div><p>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).</p><p>The extent to which logging of macro rules occur is governed by the
following:</p><div class="orderedlist"><ol type="1"><li><p>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.</p><p>Example:</p><p>/etc/shorewall/macro.foo</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT - - tcp 22
bar:info</pre><p>/etc/shorewall/rules:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
foo:debug $FW net</pre><p>Logging in the invoked 'foo' macro will be as if foo had been
defined as:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT:debug - - tcp 22
bar:info</pre></li><li><p>If you follow the log level with "!" then logging will be at
that level for all rules recursively invoked by the macro.</p><p>Example:</p><p>/etc/shorewall/macro.foo</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT - - tcp 22
bar:info</pre><p>/etc/shorewall/rules:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
foo:debug! $FW net</pre><p>Logging in the invoked 'foo' macro will be as if foo had been
defined as:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT:debug - - tcp 22
bar:debug</pre></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="ActionOrMacro"></a>How do I know if I should create an Action or a Macro?</h2></div></div></div><p>While actions and macros perform similar functions, in any given
case you will generally find that one is more appropriate than the
other.</p><div class="orderedlist"><ol type="1"><li><p>You can not associate an Extension Script with a macro <a class="ulink" href="Actions.html#Extension" target="_self">the way that you can with an
Action</a>. So if you need access to iptables features not
directly supported by Shorewall then you must use an action.</p></li><li><p>Macros are expanded in-line while each action is its own chain.
So if there are a lot of rules involved in your new action/macro then
it is generally better to use an action than a macro. Only the packets
selected when you invoke the action are directed to the corresponding
chain. On the other hand, if there are only one or two rules involved
in what you want to do then a macro is more efficient.</p></li></ol></div></div></div></body></html>
