mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-22 23:53:30 +01:00
822 lines
32 KiB
XML
822 lines
32 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
<article lang="en" status="">
|
|
<!--$Id$-->
|
|
|
|
<articleinfo>
|
|
<title>Macros</title>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Tom</firstname>
|
|
|
|
<surname>Eastep</surname>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Cristian</firstname>
|
|
|
|
<surname>Rodríguez</surname>
|
|
</author>
|
|
</authorgroup>
|
|
|
|
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2005</year>
|
|
|
|
<year>2016</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>
|
|
|
|
<caution>
|
|
<para><emphasis role="bold">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.</emphasis></para>
|
|
</caution>
|
|
|
|
<section id="Overview">
|
|
<title>Overview of Shorewall Macros?</title>
|
|
|
|
<para>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 <filename><ulink
|
|
url="manpages/shorewall-rules.html">/etc/shorewall/rules</ulink></filename>
|
|
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.</para>
|
|
|
|
<para>Macros can be thought of as templates. When a macro is invoked in an
|
|
<filename>/etc/shorewall/rules</filename> 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.</para>
|
|
|
|
<para>There are two types of Shorewall macros:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Standard Macros. These macros are released as part of Shorewall.
|
|
They are defined in macro.* files in <filename
|
|
class="directory">/usr/share/shorewall</filename>. Each
|
|
<filename>macro.*</filename> 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 <firstterm>SMB</firstterm> standard
|
|
macro.</para>
|
|
|
|
<programlisting>#
|
|
# Shorewall -- /usr/share/shorewall/macro.SMB
|
|
#
|
|
# This macro handles Microsoft SMB traffic. You need to invoke
|
|
# this macro in both directions. Beware! This rule opens a lot
|
|
# of ports, and could possibly be used to compromise your firewall
|
|
# if not used with care. You should only allow SMB traffic
|
|
# between hosts you fully trust.
|
|
#
|
|
######################################################################################
|
|
#TARGET SOURCE DEST PROTO DPORT SPORT ORIGDEST RATE USER
|
|
PARAM - - udp 135,445
|
|
PARAM - - udp 137:139
|
|
PARAM - - udp 1024: 137
|
|
PARAM - - tcp 135,139,445</programlisting>
|
|
|
|
<para>If you wish to modify one of the standard macros, do not modify
|
|
the definition in <filename
|
|
class="directory">/usr/share/shorewal</filename>l. Rather, copy the
|
|
file to <filename class="directory">/etc/shorewall</filename> (or
|
|
somewhere else on your CONFIG_PATH) and modify the copy.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>User-defined Macros. These macros are created by end-users. They
|
|
are defined in macro.* files in /etc/shorewall or in another directory
|
|
listed in your CONFIG_PATH (defined in <ulink
|
|
url="manpages/shorewall.conf.html">/etc/shorewall/shorewall.conf</ulink>).</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Most Standard Macros are <firstterm>parameterized</firstterm>. 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).</para>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<blockquote>
|
|
<para>/etc/shorewall/rules:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
|
|
SMB(ACCEPT) loc $FW</programlisting>
|
|
|
|
<para>The above is equivalent to coding the following series of
|
|
rules:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT SPORT
|
|
|
|
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</programlisting>
|
|
</blockquote>
|
|
|
|
<para>Logging is covered in <link linkend="Logging">a following
|
|
section</link>. The other columns are treated as follows:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>SOURCE and DEST</term>
|
|
|
|
<listitem>
|
|
<para>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. 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.</para>
|
|
|
|
<para>Example 1:</para>
|
|
|
|
<blockquote>
|
|
<para>/etc/shorewall/macro.SMTP</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
PARAM - loc tcp 25</programlisting>
|
|
|
|
<para>/etc/shorewall/rules (Shorewall 4.0):</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
SMTP(DNAT):info net 192.168.1.5</programlisting>
|
|
|
|
<para>/etc/shorewall/rules (Shorewall 4.2.0 and later):</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
SMTP(DNAT):info net 192.168.1.5</programlisting>
|
|
|
|
<para>This would be equivalent to coding the following directly in
|
|
/etc/shorewall/rules</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
DNAT:info net loc:192.168.1.5 tcp 25</programlisting>
|
|
</blockquote>
|
|
|
|
<para>Example 2:</para>
|
|
|
|
<blockquote>
|
|
<para>/etc/shorewall/macro.SMTP</para>
|
|
|
|
<programlisting>
|
|
#ACTION SOURCE DEST PROTO DPORT
|
|
PARAM - 192.168.1.5 tcp 25</programlisting>
|
|
|
|
<para>/etc/shorewall/rules</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
SMTP(DNAT):info net loc</programlisting>
|
|
|
|
<para>This would be equivalent to coding the following directly in
|
|
/etc/shorewall/rules</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
DNAT:info net loc:192.168.1.5 tcp 25</programlisting>
|
|
</blockquote>
|
|
|
|
<para>You may also specify SOURCE or DEST in the SOURCE and DEST
|
|
columns. This allows you to define macros that work in both
|
|
directions.</para>
|
|
|
|
<para>Example 3:</para>
|
|
|
|
<blockquote>
|
|
<para><filename>/etc/shorewall/macro.SMBBI</filename> (Note: there
|
|
is already a standard macro like this released as part of
|
|
Shorewall):</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT SPORT ORIGDEST RATE USER
|
|
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</programlisting>
|
|
|
|
<para>/etc/shorewall/rules:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
|
|
SMBBI(ACCEPT) loc $FW</programlisting>
|
|
|
|
<para>This would be equivalent to coding the following directly in
|
|
/etc/shorewall/rules</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT SPORT
|
|
|
|
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</programlisting>
|
|
</blockquote>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>Remaining columns</term>
|
|
|
|
<listitem>
|
|
<para>Any value in the invocation replaces the value in the rule in
|
|
the macro.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="Defining">
|
|
<title>Defining your own Macros</title>
|
|
|
|
<para>To define a new macro:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Copy /usr/share/shorewall/macro.template to
|
|
<filename>/etc/shorewall/macro.MacroName</filename> (for example, if
|
|
your new macro name is <quote>Foo</quote> then copy
|
|
<filename>/usr/share/shorewall/macro.template</filename> to
|
|
<filename>/etc/shorewall/macro.Foo</filename>).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Now modify the new file to define the new macro.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<section>
|
|
<title>Shorewall 5.0.0 and Later</title>
|
|
|
|
<para>The columns in a macro file are the same as those in <ulink
|
|
url="manpages/shorewall-rules.html">shorewall-rules(5)</ulink>.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Shorewall 4.4.16 and Later</title>
|
|
|
|
<para>Beginning with Shorewall 4.4.16, the columns in macro.template are
|
|
the same as those in shorewall-rules (5). The first non-commentary line
|
|
in the template must be</para>
|
|
|
|
<programlisting>FORMAT 2</programlisting>
|
|
|
|
<para>Beginning with Shorewall 4.5.11, the preferred format is as shown
|
|
below, and the above format is deprecated.</para>
|
|
|
|
<programlisting>?FORMAT 2</programlisting>
|
|
|
|
<para>There are no restrictions regarding the ACTIONs that can be
|
|
performed in a macro.</para>
|
|
|
|
<para>Beginning with Shorewall 4.5.10, macros may also be used as <ulink
|
|
url="Actions.html#Default">default actions</ulink>.</para>
|
|
|
|
<programlisting>DEFAULT <replaceable>def</replaceable></programlisting>
|
|
|
|
<para>where <replaceable>def</replaceable> is the default value for
|
|
PARAM</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Shorewall 4.4.15 and Earlier</title>
|
|
|
|
<para>Before 4.4.16, columns in the macro.template file were as
|
|
follows:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>ACTION - ACCEPT, DROP, REJECT, DNAT, DNAT-, REDIRECT,
|
|
CONTINUE, LOG, QUEUE, PARAM or an action name. Note that a macro may
|
|
not invoke another macro.</para>
|
|
|
|
<simplelist>
|
|
<member>ACCEPT - allow the connection request</member>
|
|
|
|
<member>ACCEPT+ - like ACCEPT but also excludes the connection
|
|
from any subsequent DNAT[-] or REDIRECT[-] rules.</member>
|
|
|
|
<member>NONAT - Excludes the connection from any subsequent
|
|
DNAT[-] or REDIRECT[-] rules but doesn't generate a rule to accept
|
|
the traffic.</member>
|
|
|
|
<member>DROP - ignore the request</member>
|
|
|
|
<member>REJECT - disallow the request and return an icmp
|
|
unreachable or an RST packet.</member>
|
|
|
|
<member>DNAT - Forward the request to another address (and
|
|
optionally another port).</member>
|
|
|
|
<member>DNAT- - Advanced users only. Like DNAT but only generates
|
|
the DNAT iptables rule and not the companion ACCEPT rule.</member>
|
|
|
|
<member>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.</member>
|
|
|
|
<member>SAME- - Advanced users only. Like SAME but only generates
|
|
the SAME iptables rule and not the companion ACCEPT rule.</member>
|
|
|
|
<member>REDIRECT - Redirect the request to a local port on the
|
|
firewall.</member>
|
|
|
|
<member>REDIRECT- - Advanced users only. Like REDIRECT but only
|
|
generates the REDIRECT iptables rule and not the companion ACCEPT
|
|
rule.</member>
|
|
|
|
<member>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).</member>
|
|
|
|
<member>LOG - Simply log the packet and continue.</member>
|
|
|
|
<member>QUEUE - Queue the packet to a user-space application such
|
|
as ftwall (http://p2pwall.sf.net).</member>
|
|
</simplelist>
|
|
|
|
<para>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.</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>
|
|
|
|
<para>May also contain 'DEST' as described above.</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>
|
|
|
|
<para>May also contain 'SOURCE' as described above.</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>ORIGINAL DEST (Shorewall-perl 4.2.0 and later)</para>
|
|
|
|
<para>To use this column, you must include 'FORMAT 2' as the first
|
|
non-comment line in your macro file.</para>
|
|
|
|
<para>If ACTION is DNAT[-] or REDIRECT[-] then if this column is
|
|
included and is different from the IP address given in the DEST
|
|
column, then connections destined for that address will be forwarded
|
|
to the IP and port specified in the DEST column.</para>
|
|
|
|
<para>A comma-separated list of addresses may also be used. This is
|
|
most useful with the REDIRECT target where you want to redirect
|
|
traffic destined for particular set of hosts. Finally, if the list
|
|
of addresses begins with "!" (exclusion) then the rule will be
|
|
followed only if the original destination address in the connection
|
|
request does not match any of the addresses listed.</para>
|
|
|
|
<para>For other actions, this column may be included and may contain
|
|
one or more addresses (host or network) separated by commas. Address
|
|
ranges are not allowed. When this column is supplied, rules are
|
|
generated that require that the original destination address matches
|
|
one of the listed addresses. This feature is most useful when you
|
|
want to generate a filter rule that corresponds to a DNAT- or
|
|
REDIRECT- rule. In this usage, the list of addresses should not
|
|
begin with "!".</para>
|
|
|
|
<para>It is also possible to specify a set of addresses then exclude
|
|
part of those addresses. For example, 192.168.1.0/24!192.168.1.16/28
|
|
specifies the addresses 192.168.1.0-182.168.1.15 and
|
|
192.168.1.32-192.168.1.255. See <ulink
|
|
url="manpages/shorewall_exclusion.html">shorewall-exclusion</ulink>(5).</para>
|
|
|
|
<para>See <ulink
|
|
url="http://shorewall.net/PortKnocking.html">http://shorewall.net/PortKnocking.html</ulink>
|
|
for an example of using an entry in this column with a user-defined
|
|
action rule.</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>
|
|
|
|
<member>[!]+<<emphasis>program name</emphasis>> (Note:
|
|
support for this form was removed from Netfilter in kernel version
|
|
2.6.14).</member>
|
|
</simplelist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>MARK - (Added in Shorewall-4.4.2) Defines a test on the
|
|
existing packet or connection mark. The rule will match only if the
|
|
test returns true. Must be empty or '-' if the macro is to be used
|
|
within an action.</para>
|
|
|
|
<programlisting> [!]<replaceable>value</replaceable>[/<replaceable>mask</replaceable>][:C]</programlisting>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>!</term>
|
|
|
|
<listitem>
|
|
<para>Inverts the test (not equal)</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>value</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>Value of the packet or connection mark.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><replaceable>mask</replaceable></term>
|
|
|
|
<listitem>
|
|
<para>A mask to be applied to the mark before testing.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>:C</term>
|
|
|
|
<listitem>
|
|
<para>Designates a connection mark. If omitted, the # packet
|
|
mark's value is tested.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>CONNLIMIT - (Added in Shorewall-4.4.2) Must be empty or '-' if
|
|
the macro is to be used within an action.</para>
|
|
|
|
<programlisting> [!]<replaceable>limit</replaceable>[:<replaceable>mask</replaceable>]</programlisting>
|
|
|
|
<para>May be used to limit the number of simultaneous connections
|
|
from each individual host to limit connections. Requires connlimit
|
|
match in your kernel and iptables. While the limit is only checked
|
|
on rules specifying CONNLIMIT, the number of current connections is
|
|
calculated over all current connections from the SOURCE host. By
|
|
default, the <replaceable>limit</replaceable> is applied to each
|
|
host but can be made to apply to networks of hosts by specifying a
|
|
<replaceable>mask</replaceable>. The mask specifies the width of a
|
|
VLSM mask to be applied to the source address; the number of current
|
|
connections is then taken over all hosts in the subnet
|
|
<replaceable>source-address</replaceable>/<replaceable>mask</replaceable>.
|
|
When ! is specified, the rule matches when the number of connection
|
|
exceeds the limit.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>TIME - (Added in Shorewall-4.4.2) Must be empty or '-' if the
|
|
macro is to be used within an action.</para>
|
|
|
|
<programlisting> <timeelement>[&...]</programlisting>
|
|
|
|
<para><replaceable>timeelement</replaceable> may be:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>timestart=<replaceable>hh</replaceable>:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]</term>
|
|
|
|
<listitem>
|
|
<para>Defines the starting time of day.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>timestop=<replaceable>hh</replaceable>:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]</term>
|
|
|
|
<listitem>
|
|
<para>Defines the ending time of day.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>utc</term>
|
|
|
|
<listitem>
|
|
<para>Times are expressed in Greenwich Mean Time.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>localtz</term>
|
|
|
|
<listitem>
|
|
<para>Times are expressed in Local Civil Time
|
|
(default).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>weekdays=ddd[,ddd]...</term>
|
|
|
|
<listitem>
|
|
<para>where <replaceable>ddd</replaceable> is one of
|
|
<option>Mon</option>, <option>Tue</option>,
|
|
<option>Wed</option>, <option>Thu</option>,
|
|
<option>Fri</option>, <option>Sat</option> or
|
|
<option>Sun</option></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>monthdays=dd[,dd],...</term>
|
|
|
|
<listitem>
|
|
<para>where <replaceable>dd</replaceable> is an ordinal day of
|
|
the month</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>datestart=<replaceable>yyyy</replaceable>[-<replaceable>mm</replaceable>[-<replaceable>dd</replaceable>[<option>T</option><replaceable>hh</replaceable>[:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]]]]]</term>
|
|
|
|
<listitem>
|
|
<para>Defines the starting date and time.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>datestop=<replaceable>yyyy</replaceable>[-<replaceable>mm</replaceable>[-<replaceable>dd</replaceable>[<option>T</option><replaceable>hh</replaceable>[:<replaceable>mm</replaceable>[:<replaceable>ss</replaceable>]]]]]</term>
|
|
|
|
<listitem>
|
|
<para>Defines the ending date and time.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Omitted column entries should be entered using a dash
|
|
("-").</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<para><phrase><filename>/etc/shorewall/macro.LogAndAccept</filename></phrase><programlisting> LOG:info
|
|
ACCEPT</programlisting></para>
|
|
|
|
<para>To use your macro, in <filename>/etc/shorewall/rules</filename>
|
|
you might do something like:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
|
|
LogAndAccept loc $FW tcp 22</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Logging">
|
|
<title>Macros and Logging</title>
|
|
|
|
<para>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).</para>
|
|
|
|
<para>The extent to which logging of macro rules occur is governed by the
|
|
following:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>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.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<para>/etc/shorewall/macro.foo</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
ACCEPT - - tcp 22
|
|
bar:info</programlisting>
|
|
|
|
<para>/etc/shorewall/rules:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
foo:debug $FW net</programlisting>
|
|
|
|
<para>Logging in the invoked 'foo' macro will be as if foo had been
|
|
defined as:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
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 macro.</para>
|
|
|
|
<para>Example:</para>
|
|
|
|
<para>/etc/shorewall/macro.foo</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
ACCEPT - - tcp 22
|
|
bar:info</programlisting>
|
|
|
|
<para>/etc/shorewall/rules:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
foo:debug! $FW net</programlisting>
|
|
|
|
<para>Logging in the invoked 'foo' macro will be as if foo had been
|
|
defined as:</para>
|
|
|
|
<programlisting>#ACTION SOURCE DEST PROTO DPORT
|
|
ACCEPT:debug - - tcp 22
|
|
bar:debug</programlisting>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="ActionOrMacro">
|
|
<title>How do I know if I should create an Action or a Macro?</title>
|
|
|
|
<para>While actions and macros perform similar functions, in any given
|
|
case you will generally find that one is more appropriate than the
|
|
other.</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>You can not associate an Extension Script with a macro <ulink
|
|
url="Actions.html#Extension">the way that you can with an
|
|
Action</ulink>. So if you need access to iptables features not
|
|
directly supported by Shorewall then you must use an action.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>In-line actions, introduced in Shorewall 4.5.10, are very similar to
|
|
macros. The advantage of in-line actions is that they may have parameters
|
|
and can use the other <ulink
|
|
url="configuration_file_basics.htm#ActionVariables">action
|
|
variables</ulink>.</para>
|
|
</section>
|
|
</article>
|