mirror of
https://gitlab.com/shorewall/code.git
synced 2024-12-24 07:08:53 +01:00
2875 lines
101 KiB
XML
2875 lines
101 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>
|
||
<!--$Id$-->
|
||
|
||
<articleinfo>
|
||
<title>Configuration Files Tips and Hints</title>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Tom</firstname>
|
||
|
||
<surname>Eastep</surname>
|
||
</author>
|
||
</authorgroup>
|
||
|
||
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
||
|
||
<copyright>
|
||
<year>2001-2013</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>
|
||
|
||
<caution>
|
||
<para>If you copy or edit your configuration files on a system running
|
||
Microsoft Windows, you must run them through <ulink
|
||
url="http://www.megaloman.com/~hany/software/hd2u/">dos2unix</ulink>
|
||
before you use them with Shorewall.</para>
|
||
</caution>
|
||
|
||
<section>
|
||
<title id="Intro">Introduction</title>
|
||
|
||
<para>This article offers hints about how to accomplish common tasks with
|
||
Shorewall. The <ulink url="Introduction.html">Introduction to
|
||
Shorewall</ulink> is required reading for being able to use this article
|
||
effectively. For information about setting up your first Shorewall-based
|
||
firewall, see the <ulink url="GettingStarted.html">Quickstart
|
||
Guides</ulink>.</para>
|
||
</section>
|
||
|
||
<section id="Files">
|
||
<title>Files</title>
|
||
|
||
<para><itemizedlist>
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/shorewall.conf</filename> - used to
|
||
set global firewall parameters.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/params</filename> - use this file to
|
||
set shell variables that you will expand in other files. It is
|
||
always processed by /bin/sh or by the shell specified through
|
||
SHOREWALL_SHELL in
|
||
<filename>/etc/shorewall/shorewall.conf.</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/zones</filename> - partition the
|
||
firewall's view of the world into zones.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/policy</filename> - establishes
|
||
firewall high-level policy.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/interfaces</filename> - describes the
|
||
interfaces on the firewall system.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/hosts</filename> - allows defining
|
||
zones in terms of individual hosts and subnetworks.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/masq</filename> - directs the
|
||
firewall where to use many-to-one (dynamic) Network Address
|
||
Translation (a.k.a. Masquerading) and Source Network Address
|
||
Translation (SNAT).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/rules</filename> - defines rules that
|
||
are exceptions to the overall policies established in
|
||
/etc/shorewall/policy.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/nat</filename> - defines one-to-one
|
||
NAT rules.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/proxyarp</filename> - defines use of
|
||
Proxy ARP.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/routestopped</filename> - defines
|
||
hosts accessible when Shorewall is stopped.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules </filename>- The file has a
|
||
rather unfortunate name because it is used to define marking of
|
||
packets for later use by both traffic control/shaping and policy
|
||
routing.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tos</filename> - defines rules for
|
||
setting the TOS field in packet headers.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tunnels</filename> - defines tunnels
|
||
(VPN) with end-points on the firewall system.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/blacklist</filename> - Deprecated in
|
||
favor of <filename>/etc/shorewall/blrules</filename>. Lists
|
||
blacklisted IP/subnet/MAC addresses.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/blrules</filename> — Added in
|
||
Shorewall 4.5.0. Define blacklisting and whitelisting.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/init</filename> - commands that you
|
||
wish to execute at the beginning of a <quote>shorewall start</quote>
|
||
or <quote>shorewall restart</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/start</filename> - commands that you
|
||
wish to execute at the completion of a <quote>shorewall
|
||
start</quote> or <quote>shorewall restart</quote></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/stop </filename>- commands that you
|
||
wish to execute at the beginning of a <quote>shorewall
|
||
stop</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/stopped</filename> - commands that
|
||
you wish to execute at the completion of a <quote>shorewall
|
||
stop</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/ecn</filename> - disable Explicit
|
||
Congestion Notification (ECN - RFC 3168) to remote hosts or
|
||
networks.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/accounting</filename> - define IP
|
||
traffic accounting rules</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/actions</filename> and
|
||
<filename>/usr/share/shorewall/action.template</filename> allow
|
||
user-defined actions.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/providers</filename> - defines an
|
||
alternate routing table.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/rtrules</filename> - Defines routing
|
||
rules to be used in conjunction with the routing tables defined in
|
||
<filename>/etc/shorewall/providers</filename>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcdevices</filename>,
|
||
<filename>/etc/shorewall/tcclasses</filename>,
|
||
<filename>/etc/shorewall/tcfilters</filename> - Define complex
|
||
traffic shaping.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules</filename> - Mark or classify
|
||
traffic for traffic shaping or multiple providers.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcinterfaces</filename> and
|
||
<filename>/etc/shorewall-tcpri</filename> - Define simple traffic
|
||
shaping.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/secmarks</filename> - Added in
|
||
Shorewall 4.4.13. Attach an SELinux context to selected
|
||
packets.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/vardir</filename> - Determines the
|
||
directory where Shorewall maintains its state.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/actions.std</filename> -
|
||
Actions defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/action.*</filename> - Details
|
||
of actions defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/macro.*</filename> - Details of
|
||
macros defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/modules</filename> - directs
|
||
the firewall to load kernel modules.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/modules</filename> — Specifies the kernel
|
||
modules to be loaded during shorewall start/restart.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/helpers</filename> — Added in Shorewall
|
||
4.4.7. Specifies the kernel modules to be loaded during shorewall
|
||
start/restart when LOAD_HELPERS_ONLY=Yes in
|
||
<filename>shorewall.conf</filename>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/arprules</filename> — Added in Shorewall
|
||
4.5.12. Allows specification of arptables rules.</para>
|
||
</listitem>
|
||
</itemizedlist></para>
|
||
|
||
<para><emphasis role="bold">If you need to change a file in
|
||
/usr/share/shorewall/, copy it to <filename>/etc/shorewall</filename> and
|
||
modify the copy</emphasis></para>
|
||
</section>
|
||
|
||
<section id="Manpages">
|
||
<title>Man Pages</title>
|
||
|
||
<para>Man pages are provided in section 5 for each of the Shorewall
|
||
configuration files. The name of the page is formed by prefixing the file
|
||
name with "shorewall-".</para>
|
||
|
||
<para>Example — To view the manual page for
|
||
<filename>/etc/shorewall/interfaces</filename>:</para>
|
||
|
||
<programlisting>man shorewall-interfaces</programlisting>
|
||
|
||
<para>The /etc/shorewall/shorewall.conf file is an exception -- the man
|
||
page for that file is 'shorewall.conf':</para>
|
||
|
||
<programlisting>man shorewall.conf</programlisting>
|
||
</section>
|
||
|
||
<section id="Comments">
|
||
<title>Comments</title>
|
||
|
||
<para>You may place comments in configuration files by making the first
|
||
non-whitespace character a pound sign (<quote>#</quote>). You may also
|
||
place comments at the end of any line, again by delimiting the comment
|
||
from the rest of the line with a pound sign.</para>
|
||
|
||
<example id="comment">
|
||
<title>Comments in a Configuration File</title>
|
||
|
||
<programlisting># This is a comment
|
||
ACCEPT net $FW tcp www #This is an end-of-line comment</programlisting>
|
||
</example>
|
||
|
||
<important>
|
||
<para>If a comment ends with a backslash ("\"), the next line will also
|
||
be treated as a comment. See <link linkend="Continuation">Line
|
||
Continuation</link> below.</para>
|
||
</important>
|
||
</section>
|
||
|
||
<section id="Names">
|
||
<title>Names</title>
|
||
|
||
<para>When you define an object in Shorewall (<ulink
|
||
url="manpages/shorewall-zones.html">Zone</ulink>, <link
|
||
linkend="Logical">Logical Interface</link>, <ulink
|
||
url="ipsets.html">ipsets</ulink>, <ulink
|
||
url="Actions.html">Actions</ulink>, etc., you give it a name. Shorewall
|
||
names start with a letter and consist of letters, digits or underscores
|
||
("_"). Except for Zone names, Shorewall does not impose a limit on name
|
||
length.</para>
|
||
|
||
<para>When an ipset is referenced, the name must be preceded by a plus
|
||
sign ("+").</para>
|
||
|
||
<para>The last character of an interface may also be a plus sign to
|
||
indicate a wildcard name.</para>
|
||
|
||
<para>Physical interface names match names shown by 'ip link ls'; if the
|
||
name includes an at sign ("@"), do not include that character or any
|
||
character that follows. For example, "sit1@NONE" is referred to as simply
|
||
'sit1".</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Zone and Chain Names</title>
|
||
|
||
<para>For a pair of zones, Shorewall creates two Netfilter chains; one for
|
||
connections in each direction. The names of these chains are formed by
|
||
separating the names of the two zones by either "2" or "-".</para>
|
||
|
||
<para>Example: Traffic from zone A to zone B would go through chain A2B
|
||
(think "A to B") or "A-B".</para>
|
||
|
||
<para>The default separator is "2" but you can override that by setting
|
||
ZONE_SEPARATOR="-" in <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
|
||
|
||
<para>Zones themselves have names that begin with a letter and are
|
||
composed of letters, numerals, and "_". The maximum length of a name is
|
||
dependent on the setting of LOGFORMAT in <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). See <ulink
|
||
url="manpages/shorewall-zones.html">shorewall-zones</ulink> (5) for
|
||
details.</para>
|
||
</section>
|
||
|
||
<section id="COMMENT">
|
||
<title>Attach Comment to Netfilter Rules</title>
|
||
|
||
<para>If you kernel and iptables contain comment match support (see the
|
||
output of <command>shorewall show capabilities</command>), then you can
|
||
attach comments to Netfilter rules. This feature is available in the
|
||
following files:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/conntrack</filename> (formerly
|
||
<filename>/etc/shorewall/notrack</filename>)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/accounting</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/masq</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/nat</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/rules</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/secmarks</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tunnels</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Action definition files
|
||
(<filename>/etc/shorewall/action.*</filename>)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Macro definition files (/etc/shorewall/macro.*)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>To attach a comment to one or more rules, insert a record above the
|
||
rules that begins with the word COMMENT (must be in all caps). The
|
||
remainder of the line is treated as a comment -- that comment will appear
|
||
delimited by "/* ... */" in the output of the <command>shorewall[-lite]
|
||
show</command> and <command>shorewall[-lite] dump</command> commands. The
|
||
comment will be attached to each generated rule until another COMMENT line
|
||
appears. To stop attaching comments to rules, simply insert a line that
|
||
contains the single word COMMENT.</para>
|
||
|
||
<para>Example (<filename>/etc/shorewall/rules</filename>):</para>
|
||
|
||
<programlisting>COMMENT Stop NETBIOS noise
|
||
|
||
REJECT loc net tcp 137,445
|
||
REJECT loc net udp 137:139
|
||
|
||
COMMENT Stop my idiotic work laptop from sending to the net with an HP source/dest IP address
|
||
|
||
DROP loc:!192.168.0.0/22 net
|
||
|
||
COMMENT</programlisting>
|
||
|
||
<para>Here's the corresponding output from
|
||
<filename>/sbin/shorewall-lite</filename>:</para>
|
||
|
||
<programlisting>gateway:~ # <command>shorewall-lite show loc2net</command>
|
||
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008
|
||
|
||
Counters reset Mon Oct 16 14:52:17 PDT 2006
|
||
|
||
Chain loc2net (1 references)
|
||
pkts bytes target prot opt in out source destination
|
||
0 0 LOG tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
|
||
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25
|
||
0 0 LOG udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
|
||
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031
|
||
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 137,445 <emphasis
|
||
role="bold">/* Stop NETBIOS noise */</emphasis>
|
||
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:137:139 <emphasis
|
||
role="bold">/* Stop NETBIOS noise */</emphasis>
|
||
0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 <emphasis
|
||
role="bold">/* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */</emphasis>
|
||
5 316 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0
|
||
gateway:~ #
|
||
|
||
</programlisting>
|
||
|
||
<para>COMMENT lines in macro files work somewhat differently from other
|
||
files. COMMENT lines in macros are ignored if COMMENT support is not
|
||
available or if there was a COMMENT in use when the top-level macro was
|
||
invoked. This allows the following:</para>
|
||
|
||
<para><filename>/usr/share/shorewall/macro.SSH</filename>:</para>
|
||
|
||
<para><programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE RATE USER/
|
||
# PORT(S) PORT(S) LIMIT GROUP
|
||
COMMENT SSH
|
||
PARAM - - tcp 22 </programlisting>
|
||
<filename>/etc/shorewall/rules</filename>:<programlisting>COMMENT Allow SSH from home
|
||
SSH(ACCEPT) net:$MYIP $FW
|
||
COMMENT</programlisting>The comment line in macro.SSH will not override the
|
||
COMMENT line in the rules file and the generated rule will show <emphasis
|
||
role="bold">/* Allow SSH from home */</emphasis> when displayed through
|
||
the Shorewall show and dump commands.</para>
|
||
</section>
|
||
|
||
<section id="BlankColumn">
|
||
<title>"Blank" Columns</title>
|
||
|
||
<para>If you don't want to supply a value in a column but want to supply a
|
||
value in a following column, simply enter '-' to make the column appear
|
||
empty.</para>
|
||
|
||
<para>Example:<programlisting>#INTERFACE BROADCAST OPTIONS
|
||
br0 - routeback</programlisting></para>
|
||
</section>
|
||
|
||
<section id="Continuation">
|
||
<title>Line Continuation</title>
|
||
|
||
<para>You may continue lines in the configuration files using the usual
|
||
backslash (<quote>\</quote>) followed immediately by a new line character
|
||
(Enter key).</para>
|
||
|
||
<example id="continuation">
|
||
<title>Line Continuation</title>
|
||
|
||
<programlisting>ACCEPT net $FW tcp \↵
|
||
smtp,www,pop3,imap #Services running on the firewall</programlisting>
|
||
|
||
<para>In certain cases, leading white space is ignored in continuation
|
||
lines:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The continued line ends with a colon (":")</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The continued line ends with a comma (",")</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Example (<filename>/etc/shorewall/rules</filename>):</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST
|
||
# PORT(S)
|
||
ACCEPT net:\
|
||
206.124.146.177,\
|
||
206.124.146.178,\
|
||
206.124.146.180\
|
||
dmz tcp 873</programlisting>
|
||
|
||
<para>The leading white space on the first through third continuation
|
||
lines is ignored so the SOURCE column effectively contains
|
||
"net:206.124.146.177,206.124.147.178,206.124.146.180". Because the third
|
||
continuation line does not end with a comma or colon, the leading white
|
||
space in the last line is not ignored.</para>
|
||
</example>
|
||
|
||
<important>
|
||
<para>A trailing backslash is not ignored in a comment. So the continued
|
||
rule above can be commented out with a single '#' as follows:</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST
|
||
# PORT(S)
|
||
<emphasis role="bold">#</emphasis>ACCEPT net:\
|
||
206.124.146.177,\
|
||
206.124.146.178,\
|
||
206.124.146.180\
|
||
dmz tcp 873</programlisting>
|
||
</important>
|
||
</section>
|
||
|
||
<section id="Pairs">
|
||
<title>Alternate Specification of Column Values - Shorewall 4.4.24 and
|
||
Later</title>
|
||
|
||
<para>Some of the configuration files now have a large number of columns.
|
||
That makes it awkward to specify a value for one of the right-most columns
|
||
as you must have the correct number of intervening '-' columns.</para>
|
||
|
||
<para>This problem is addressed by allowing column values to be specified
|
||
as <replaceable>column-name</replaceable>/<replaceable>value</replaceable>
|
||
pairs.</para>
|
||
|
||
<para>There is considerable flexibility in how you specify the
|
||
pairs:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>At any point, you can enter a semicolon (';') followed by one or
|
||
more specifications of the following forms:</para>
|
||
|
||
<simplelist>
|
||
<member><replaceable>column-name</replaceable>=<replaceable>value</replaceable></member>
|
||
|
||
<member><replaceable>column-name</replaceable>=<replaceable>>value</replaceable></member>
|
||
|
||
<member><replaceable>column-name</replaceable>:<replaceable>value</replaceable></member>
|
||
</simplelist>
|
||
|
||
<para>The value may optionally be enclosed in double quotes.</para>
|
||
|
||
<para>The pairs must be separated by white space, but you can add a
|
||
comma adjacent to the <replaceable>values</replaceable> for
|
||
readability as in:</para>
|
||
|
||
<simplelist>
|
||
<member><emphasis role="bold">; proto=>udp,
|
||
port=1024</emphasis></member>
|
||
</simplelist>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>You can enclose the pairs in curly brackets ("{...}") rather
|
||
than separating them from columns by a semicolon:</para>
|
||
|
||
<simplelist>
|
||
<member><emphasis role="bold">{ proto:udp, port:1024
|
||
}</emphasis></member>
|
||
</simplelist>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>The following table shows the column names for each of the
|
||
table-oriented configuration files.</para>
|
||
|
||
<note>
|
||
<para>Column names are <emphasis
|
||
role="bold">case-insensitive</emphasis>.</para>
|
||
</note>
|
||
|
||
<informaltable>
|
||
<tgroup cols="2">
|
||
<tbody>
|
||
<row>
|
||
<entry><emphasis role="bold">File</emphasis></entry>
|
||
|
||
<entry><emphasis role="bold">Column names</emphasis></entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>accounting</entry>
|
||
|
||
<entry>action,chain, source, dest, proto, dport, sport, user,
|
||
mark, ipsec, headers</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>conntrack (formerly notrack)</entry>
|
||
|
||
<entry>source,dest,proto,dport,sport,user,switch</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>blacklist</entry>
|
||
|
||
<entry>networks,proto,port,options</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>blrules</entry>
|
||
|
||
<entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>ecn</entry>
|
||
|
||
<entry>interface,hosts. Beginning with Shorewall 4.5.4, 'host' is
|
||
a synonym for 'hosts'.</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>hosts</entry>
|
||
|
||
<entry>zone,hosts,options. Beginning with Shorewall 4.5.4, 'host'
|
||
is a synonym for 'hosts'.</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>interfaces</entry>
|
||
|
||
<entry>zone,interface,broadcast,options</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>maclist</entry>
|
||
|
||
<entry>disposition,interface,mac,addresses</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>masq</entry>
|
||
|
||
<entry>interface,source,address,proto,port,ipsec,mark,user,switch</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>nat</entry>
|
||
|
||
<entry>external,interface,internal,allints,local</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>netmap</entry>
|
||
|
||
<entry>type,net1,interface,net2,net3,proto,dport,sport</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>notrack</entry>
|
||
|
||
<entry>source,dest,proto,dport,sport,user</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>policy</entry>
|
||
|
||
<entry>source,dest,policy,loglevel,limit,connlimit</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>providers</entry>
|
||
|
||
<entry>table,number,mark,duplicate,interface,gateway,options,copy</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>proxyarp and proxyndp</entry>
|
||
|
||
<entry>address,interface,external,haveroute,persistent</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>rtrules</entry>
|
||
|
||
<entry>source,dest,provider,priority</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>routes</entry>
|
||
|
||
<entry>provider,dest,gateway,device</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>routestopped</entry>
|
||
|
||
<entry>interface,hosts,options,proto,dport,sport</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>rules</entry>
|
||
|
||
<entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>secmarks</entry>
|
||
|
||
<entry>secmark,chain,source,dest,proto,dport,sport,user,mark</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcclasses</entry>
|
||
|
||
<entry>interface,mark,rate,ceil,prio,options</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcdevices</entry>
|
||
|
||
<entry>interface,in_bandwidth,out_bandwidth,options,redirect</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcfilters</entry>
|
||
|
||
<entry>class,source,dest,proto,dport,sport,tos,length</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcinterfaces</entry>
|
||
|
||
<entry>interface,type,in_bandwidth,out_bandwidth</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcpri</entry>
|
||
|
||
<entry>band,proto,port,address,interface,helper</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcrules</entry>
|
||
|
||
<entry>mark,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers.
|
||
Beginning with Shorewall 4.5.3, 'action' is a synonym for
|
||
'mark'.</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tos</entry>
|
||
|
||
<entry>source,dest,proto,dport,sport,tos,mark</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tunnels</entry>
|
||
|
||
<entry>type,zone,gateway,gateway_zone. Beginning with Shorewall
|
||
4.5.3, 'gateways' is a synonym for 'gateway'. Beginning with
|
||
Shorewall 4.5.4, 'gateway_zones' is a synonym for
|
||
'gateway_zone'.</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>zones</entry>
|
||
|
||
<entry>zone,type,options,in_options,out_options</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
|
||
<para>Example (rules file):</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST
|
||
# PORT(S)
|
||
DNAT net loc:10.0.0.1 tcp 80 ; mark="88"</programlisting>
|
||
|
||
<para>Here's the same line in several equivalent formats:</para>
|
||
|
||
<programlisting>{ action=>DNAT, source=>net, dest=>loc:10.0.0.1, proto=>tcp, dport=>80, mark=>88 }
|
||
; action:"DNAT" source:"net" dest:"loc:10.0.0.1" proto:"tcp" dport:"80" mark:"88"
|
||
DNAT { source=net dest=loc:10.0.0.1 proto=tcp dport=80 mark=88 }</programlisting>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Addresses</title>
|
||
|
||
<para>In both Shorewall and Shorewall6, there are two basic types of
|
||
addresses:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Host Address</term>
|
||
|
||
<listitem>
|
||
<para>This address type refer to a single host.</para>
|
||
|
||
<para>In IPv4, the format is <emphasis>i.j.k.l</emphasis> where
|
||
<emphasis>i</emphasis> through <emphasis>l</emphasis> are decimal
|
||
numbers between 1 and 255.</para>
|
||
|
||
<para>In IPv6, the format is <emphasis>a:b:c:d:e:f:g:h</emphasis>
|
||
where <emphasis>a</emphasis> through <emphasis>h</emphasis> consist
|
||
of 1 to 4 hexidecimal digits (leading zeros may be omitted). a
|
||
single series of 0 addresses may be omitted. For example
|
||
2001:227:e857:1:0:0:0:0:1 may be written 2001:227:e857:1::1.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>Network Address</term>
|
||
|
||
<listitem>
|
||
<para>A network address refers to 1 or more hosts and consists of a
|
||
host address followed by a slash ("/") and a <firstterm>Variable
|
||
Length Subnet Mask</firstterm> (VLSM). This is known as
|
||
<firstterm>Classless Internet Domain Routing</firstterm> (CIDR)
|
||
notation.</para>
|
||
|
||
<para>The VLSM is a decimal number. For IPv4, it is in the range 0
|
||
through 32. For IPv6, the range is 0 through 128. The number
|
||
represents the number of leading bits in the address that represent
|
||
the network address; the remainder of the bits are a host address
|
||
and are generally given as zero.</para>
|
||
|
||
<para>Examples:</para>
|
||
|
||
<para>IPv4: 192.168.1.0/24</para>
|
||
|
||
<para>IPv6: 2001:227:e857:1:0:0:0:0:1/64</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>In the Shorewall documentation and manpages, we have tried to make
|
||
it clear which type of address is accepted in each specific case.</para>
|
||
|
||
<para>For more information about addressing, see the<ulink
|
||
url="shorewall_setup_guide.htm#Addressing"> Setup Guide</ulink>.</para>
|
||
</section>
|
||
|
||
<section id="SOURCE-DEST">
|
||
<title>Specifying SOURCE and DEST</title>
|
||
|
||
<para>Entries in Shorewall configuration files often deal with the source
|
||
(SOURCE) and destination (DEST) of connections and Shorewall implements a
|
||
uniform way for specifying them.</para>
|
||
|
||
<para>A SOURCE or DEST consists of one to three parts separated by colons
|
||
(":"):</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>ZONE — The name of a zone declared in
|
||
<filename>/etc/shorewall/zones</filename> or
|
||
<filename>/etc/shorewall6/zones</filename>. This part is only
|
||
available in the rules file (<filename>/etc/shorewall/rules</filename>
|
||
and <filename>/etc/shorewall6/rules</filename>).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>INTERFACE — The name of an interface that matches an entry in
|
||
<filename>/etc/shorewall/interfaces</filename>
|
||
(<filename>/etc/shorewall6/interfaces</filename>).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>ADDRESS LIST — A list of one or more addresses (host or network)
|
||
or address ranges, separated by commas. In an IPv6 configuration, this
|
||
list must be included in square or angled brackets ("[...]" or
|
||
"<...>"). The list may have <link
|
||
linkend="Exclusion">exclusion</link>.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>Examples.</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>All hosts in the <emphasis role="bold">net</emphasis> zone —
|
||
<emphasis role="bold">net</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Subnet 192.168.1.0/29 in the <emphasis
|
||
role="bold">loc</emphasis> zone — <emphasis
|
||
role="bold">loc:192.168.1.0/29</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>All hosts in the net zone connecting through <filename
|
||
class="devicefile">ppp0</filename> — <emphasis
|
||
role="bold">net:ppp0</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>All hosts interfaced by <filename
|
||
class="devicefile">eth3</filename> — <emphasis
|
||
role="bold">eth3</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Subnet 10.0.1.0/24 interfacing through <filename><filename
|
||
class="devicefile">eth2</filename></filename> — <emphasis
|
||
role="bold">eth2:10.0.1.0/24</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Host 2002:ce7c:92b4:1:a00:27ff:feb1:46a9 in the <emphasis
|
||
role="bold">loc</emphasis> zone — <emphasis
|
||
role="bold">loc::[2002:ce7c:92b4:1:a00:27ff:feb1:46a9]</emphasis></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The primary IP address of eth0 in the $FW zone - <emphasis
|
||
role="bold">$FW:&eth0</emphasis> (see <link
|
||
linkend="Rvariables">Run-time Address Variables</link> below)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>All hosts in Vatican City - <emphasis
|
||
role="bold">net:^VA</emphasis> (Shorwall 4.5.4 and later - See <ulink
|
||
url="ISO-3661.html">this article</ulink>).</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</section>
|
||
|
||
<section id="INCLUDE">
|
||
<title>INCLUDE Directive</title>
|
||
|
||
<para>Any configuration file may contain INCLUDE directives. An INCLUDE
|
||
directive consists of the word INCLUDE followed by a path name and causes
|
||
the contents of the named file to be logically included into the file
|
||
containing the INCLUDE. Relative path names given in an INCLUDE directive
|
||
are resolved using the current CONFIG_PATH setting (see <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>
|
||
|
||
<para>INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
|
||
directives are ignored with a warning message.</para>
|
||
|
||
<para>Beginning with Shorewall 4.4.17, the INCLUDE directive may also
|
||
appear in the following <ulink
|
||
url="shorewall_extension_scripts.htm">extension scripts</ulink>:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>clear</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>findgw</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>init</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>isusable</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>refresh</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>refreshed</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>restore</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>restored</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>start</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>started</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>stop</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>stopped</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>tcclear</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>When used in these scripts, the INCLUDEd files are copied into the
|
||
compiled firewall script.</para>
|
||
|
||
<caution>
|
||
<para>Prior to Shorewall 4.4.17, if you are using <ulink
|
||
url="Shorewall-Lite.html">Shorewall Lite</ulink> , it is not advisable
|
||
to use INCLUDE in the <filename>params</filename> file in an export
|
||
directory if you set EXPORTPARAMS=Yes in <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). If you do
|
||
that, you must ensure that the included file is also present on the
|
||
firewall system's <filename
|
||
class="directory">/etc/shorewall-lite/</filename> directory.</para>
|
||
|
||
<para>If you only need the <filename>params</filename> file at compile
|
||
time, you can set EXPORTPARAMS=No in
|
||
<filename>shorewall.conf</filename>. That prevents the
|
||
<filename>params</filename> file from being copied into the compiled
|
||
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
|
||
<filename>params</filename> file. Note that with Shorewall 4.4.17 and
|
||
later:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The variables set at compile time are available at run-time
|
||
even with EXPORTPARAMS=No.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The INCLUDE directive in the <filename>params</filename> file
|
||
is processed at compile time and the INCLUDEd file is copied into
|
||
the compiled script.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</caution>
|
||
|
||
<example id="include">
|
||
<title>Use of INCLUDE</title>
|
||
|
||
<programlisting> shorewall/params.mgmt:
|
||
|
||
MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3
|
||
TIME_SERVERS=4.4.4.4
|
||
BACKUP_SERVERS=5.5.5.5
|
||
|
||
----- end params.mgmt -----
|
||
|
||
shorewall/params:
|
||
|
||
# Shorewall 1.3 /etc/shorewall/params
|
||
[..]
|
||
#######################################
|
||
|
||
INCLUDE params.mgmt
|
||
|
||
# params unique to this host here
|
||
#LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
|
||
|
||
----- end params -----
|
||
|
||
shorewall/rules.mgmt:
|
||
|
||
ACCEPT net:$MGMT_SERVERS $FW tcp 22
|
||
ACCEPT $FW net:$TIME_SERVERS udp 123
|
||
ACCEPT $FW net:$BACKUP_SERVERS tcp 22
|
||
|
||
----- end rules.mgmt -----
|
||
|
||
shorewall/rules:
|
||
|
||
# Shorewall version 1.3 - Rules File
|
||
[..]
|
||
#######################################
|
||
|
||
INCLUDE rules.mgmt
|
||
|
||
# rules unique to this host here
|
||
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
|
||
|
||
----- end rules -----</programlisting>
|
||
|
||
<para>You may include multiple files in one command using an <link
|
||
linkend="Embedded">embedded shell command</link>.</para>
|
||
|
||
<para>Example (include all of the files ending in ".rules" in a
|
||
directory:):<programlisting>gateway:/etc/shorewall # ls rules.d
|
||
ALL.rules DNAT.rules FW.rules NET.rules REDIRECT.rules VPN.rules
|
||
gateway:/etc/shorewall # </programlisting></para>
|
||
|
||
<para>/etc/shorewall/rules:<programlisting>SECTION NEW
|
||
SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
|
||
|
||
<para>If you are the sort to put such an entry in your rules file even
|
||
though /etc/shorewall/rules.d might not exist or might be empty, then
|
||
you probably want:</para>
|
||
|
||
<programlisting>SECTION NEW
|
||
SHELL cat /etc/shorewall/rules.d/*.rules 2> /dev/null || true</programlisting>
|
||
|
||
<para>Beginning with Shorewall 4.5.2, in files other than
|
||
<filename>/etc/shorewall/params</filename> and
|
||
<filename>/etc/shorewall/conf</filename>, INCLUDE may be immediately
|
||
preceeded with '?' to signal that the line is a compiler directive and
|
||
not configuration data.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>?INCLUDE common.rules</programlisting>
|
||
</example>
|
||
</section>
|
||
|
||
<section>
|
||
<title>?FORMAT Directive</title>
|
||
|
||
<para>A number of different files support multiple formats. Prior to
|
||
Shorewall 4.5.11, the format was specified by a line having 'FORMAT' as
|
||
the first token. This requires each of the file processors to handle
|
||
FORMAT separately.</para>
|
||
|
||
<para>In Shorewall 4.5.11, the ?FORMAT directive was created to centralize
|
||
processing of FORMAT directives. The old entries, while still supported,
|
||
are now deprecated.</para>
|
||
|
||
<para>The ?FORMAT directive is as follows:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>?FORMAT <replaceable>format</replaceable></term>
|
||
|
||
<listitem>
|
||
<para>Where format is an integer. In all cases, the default format
|
||
is 1. The following table shows the files that have different
|
||
formats and the supported formats for each.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<informaltable>
|
||
<tgroup align="left" cols="2">
|
||
<tbody>
|
||
<row>
|
||
<entry>FILE</entry>
|
||
|
||
<entry>FORMATS</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>action files (action.*)</entry>
|
||
|
||
<entry>1 and 2</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>conntrack</entry>
|
||
|
||
<entry>1, 2 and 3</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>interfaces</entry>
|
||
|
||
<entry>1 and 2</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>macro files (macro.*)</entry>
|
||
|
||
<entry>1 and 2</entry>
|
||
</row>
|
||
|
||
<row>
|
||
<entry>tcrules</entry>
|
||
|
||
<entry>1 and 2</entry>
|
||
</row>
|
||
</tbody>
|
||
</tgroup>
|
||
</informaltable>
|
||
</section>
|
||
|
||
<section>
|
||
<title>?COMMENT Directive</title>
|
||
|
||
<para>A number of files allow attaching comments to generated Netfilter
|
||
rules:</para>
|
||
|
||
<simplelist>
|
||
<member><filename>accounting</filename></member>
|
||
|
||
<member><filename>action</filename>.* files</member>
|
||
|
||
<member><filename>blrules</filename></member>
|
||
|
||
<member><filename>conntrack</filename></member>
|
||
|
||
<member><filename>macro</filename>.* files</member>
|
||
|
||
<member><filename>masq</filename></member>
|
||
|
||
<member><filename>nat</filename></member>
|
||
|
||
<member><filename>rules</filename></member>
|
||
|
||
<member><filename>secmarks</filename></member>
|
||
|
||
<member><filename>tcrules</filename></member>
|
||
|
||
<member><filename>tunnels</filename></member>
|
||
</simplelist>
|
||
|
||
<para>Prior to Shorewall 4.5.11, comments were specified by a line having
|
||
COMMENT as the first token. The remainder of the line is treated as a
|
||
comment to be attached to rules.</para>
|
||
|
||
<para>In Shorewall 4.5.11, the ?COMMENT directive was created to
|
||
centralize processing of COMMENT directives. The old entries, while still
|
||
supported, are now deprecated.</para>
|
||
|
||
<para>The ?COMMENT directive is as follows:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>COMMENT [ <replaceable>comment</replaceable> ]</term>
|
||
|
||
<listitem>
|
||
<para>If <replaceable>comment</replaceable> is present, it will
|
||
appear enclosed in /*....*/ in the output of the <command>shorewall
|
||
show </command>and <command>shorewall dump</command> commands. If no
|
||
<replaceable>comment</replaceable> is present, the rules generated
|
||
by following entries will not have comments attached.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section id="CONFIG_PATH">
|
||
<title>CONFIG_PATH</title>
|
||
|
||
<para>The CONFIG_PATH option in shorewall.conf determines where the
|
||
compiler searches for files. The default setting is
|
||
CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that the
|
||
compiler first looks in /etc/shorewall and if it doesn't find the file, it
|
||
then looks in /usr/share/shorewall.</para>
|
||
|
||
<para>You can change this setting to have the compiler look in different
|
||
places. For example, if you want to put your own versions of standard
|
||
macros in /etc/shorewall/Macros, then you could set
|
||
CONFIG_PATH=/etc/shorewall:/etc/shorewall/Macros:/usr/share/shorewall and
|
||
the compiler will use your versions rather than the standard ones.</para>
|
||
</section>
|
||
|
||
<section id="Variables">
|
||
<title>Using Shell Variables</title>
|
||
|
||
<para>You may use the <filename>/etc/shorewall/params</filename> file to
|
||
set shell variables that you can then use in the other configuration
|
||
files.</para>
|
||
|
||
<para>It is suggested that variable names begin with an upper case letter
|
||
to distinguish them from variables used internally within the Shorewall
|
||
programs</para>
|
||
|
||
<para>The following variable names must be avoided. Those in <emphasis
|
||
role="bold">bold font</emphasis> must be avoided in all Shorewall
|
||
versions; those in regular font must be avoided in versions prior to
|
||
4.4.8.</para>
|
||
|
||
<simplelist>
|
||
<member><emphasis role="bold">Any option from <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink>
|
||
(5)</emphasis></member>
|
||
|
||
<member><emphasis role="bold">COMMAND</emphasis></member>
|
||
|
||
<member><emphasis role="bold">CONFDIR</emphasis></member>
|
||
|
||
<member>DEBUG</member>
|
||
|
||
<member>ECHO_E</member>
|
||
|
||
<member>ECHO_N</member>
|
||
|
||
<member>EXPORT</member>
|
||
|
||
<member>FAST</member>
|
||
|
||
<member>FILEMODE</member>
|
||
|
||
<member>HOSTNAME</member>
|
||
|
||
<member>IPT_OPTIONS</member>
|
||
|
||
<member>NOROUTES</member>
|
||
|
||
<member>PREVIEW</member>
|
||
|
||
<member>PRODUCT</member>
|
||
|
||
<member>PROFILE</member>
|
||
|
||
<member>PURGE</member>
|
||
|
||
<member>RECOVERING</member>
|
||
|
||
<member>RESTOREPATH</member>
|
||
|
||
<member>RING_BELL</member>
|
||
|
||
<member><emphasis role="bold">SHAREDIR</emphasis></member>
|
||
|
||
<member><emphasis role="bold">Any name beginning with SHOREWALL_ or
|
||
SW_</emphasis></member>
|
||
|
||
<member>STOPPING</member>
|
||
|
||
<member>TEST</member>
|
||
|
||
<member>TIMESTAMP</member>
|
||
|
||
<member>USE_VERBOSITY</member>
|
||
|
||
<member><emphasis role="bold">VARDIR</emphasis></member>
|
||
|
||
<member><emphasis role="bold">VARLIB</emphasis></member>
|
||
|
||
<member>VERBOSE</member>
|
||
|
||
<member>VERBOSE_OFFSET</member>
|
||
|
||
<member>VERSION</member>
|
||
</simplelist>
|
||
|
||
<para>Example:</para>
|
||
|
||
<blockquote>
|
||
<programlisting> /etc/shorewall/params
|
||
|
||
NET_IF=eth0
|
||
NET_BCAST=130.252.100.255
|
||
NET_OPTIONS=routefilter,routefilter
|
||
|
||
/etc/shorewall/interfaces record:
|
||
|
||
net $NET_IF $NET_BCAST $NET_OPTIONS
|
||
|
||
The result will be the same as if the record had been written
|
||
|
||
net eth0 130.252.100.255 routefilter,routefilter
|
||
</programlisting>
|
||
</blockquote>
|
||
|
||
<para>Variables may be used anywhere in the other configuration
|
||
files.<note>
|
||
<para>If you use "$FW" on the right side of assignments in the
|
||
<filename>/etc/shorewall/params</filename> file, you must also set the
|
||
FW variable in that file.</para>
|
||
|
||
<para>Example:<programlisting>/etc/shorewall/zones:
|
||
|
||
#ZONE TYPE OPTIONS
|
||
<emphasis role="bold">fw</emphasis> firewall
|
||
|
||
/etc/shorewall/params:
|
||
|
||
FW=<emphasis role="bold">fw</emphasis>
|
||
BLARG=$FW:206.124.146.176</programlisting></para>
|
||
</note></para>
|
||
|
||
<para>Because the <filename>/etc/shorewall/params</filename> file is
|
||
simply sourced into the shell, you can place arbitrary shell code in the
|
||
file and it will be executed each time that the file is read. Any code
|
||
included should follow these guidelines:</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The code should not have side effects, especially on other
|
||
shorewall configuration files.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The code should be safe to execute multiple times without
|
||
producing different results.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Should not depend on where the code is called from.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Should not assume anything about the state of Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The names of any functions or variables declared should begin
|
||
with an upper case letter.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The <filename>/etc/shorewall/params</filename> file is processed
|
||
by the compiler at compile-time and by the compiled script at
|
||
run-time. If you have set EXPORTPARAMS=No in
|
||
<filename>shorewall.conf</filename>, then the
|
||
<filename><filename>params</filename></filename> file is only
|
||
processed by the compiler; it is not run by the compiled script.
|
||
Beginning with Shorewall 4.4.17, the values of the variables set at
|
||
compile time are available at run time with EXPORTPRARMS=No.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If you are using <ulink url="Shorewall-Lite.html">Shorewall
|
||
Lite</ulink> and if the <filename>params</filename> script needs to
|
||
set shell variables based on the configuration of the firewall system,
|
||
you can use this trick:</para>
|
||
|
||
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
|
||
|
||
<para>The <command>shorewall-lite call</command> command allows you to
|
||
to call interactively any Shorewall function that you can call in an
|
||
extension script.</para>
|
||
|
||
<note>
|
||
<para>Within your configuration files, only the $VAR and ${VAR}
|
||
forms of variable expansion are supported. You may not use the more
|
||
exotic forms supported by the shell (${VAR:=val}, ${VAR:-val},
|
||
...)</para>
|
||
</note>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>Beginning with Shorewall 4.4.27, you may also use options in <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5) (e.g.,
|
||
$BLACKLIST_LOGLEVEL).</para>
|
||
|
||
<note>
|
||
<para>When an option is set to 'No' in shorewall.conf, the corresponding
|
||
shell variable will be empty.</para>
|
||
</note>
|
||
|
||
<note>
|
||
<para>Options that were not set in shorewall.conf will expand to their
|
||
default value.</para>
|
||
</note>
|
||
|
||
<para id="Rvariables">Beginning with Shorewall 4.5.2, configuration files
|
||
can access variables defined in the <ulink
|
||
url="Install.htm#shorewallrc">shorewallrc file</ulink>.</para>
|
||
|
||
<para>Beginning with Shorewall 4.5.11, variables can be altered by
|
||
compiler directives.</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>?SET <replaceable>variable value</replaceable></term>
|
||
|
||
<listitem>
|
||
<para>The <replaceable>variable</replaceable> can be specified
|
||
either with or without a leading '$' to allow using both Perl and
|
||
Shell variable representation.</para>
|
||
|
||
<para>The <replaceable>value</replaceable> is a Perl-compatible
|
||
expression.</para>
|
||
|
||
<note>
|
||
<para>The Shorewall compiler performs variable expansion within
|
||
the expression. So variables are expanded even when they appear in
|
||
single quotes.</para>
|
||
</note>
|
||
|
||
<note>
|
||
<para>If a variable within the expression can contain a
|
||
non-numeric value, it is a good idea to enclose it in quotes.
|
||
Otherwise, the Shorewall compiler has to guess whether to enclose
|
||
the variable's value in quotes or not.</para>
|
||
</note>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>?RESET <replaceable>variable</replaceable></term>
|
||
|
||
<listitem>
|
||
<para>Removes the named <replaceable>variable</replaceable> from the
|
||
compiler's variable table.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>Action variables are read-only and cannot be ?SET (although you can
|
||
change their values <ulink url="Actions.html#Embedded">using embedded
|
||
Perl</ulink>).</para>
|
||
</section>
|
||
|
||
<section id="AddressVariables">
|
||
<title>Address Variables</title>
|
||
|
||
<para>Given that shell variables are expanded at compile time, there is no
|
||
way to cause such variables to be expanded at run time. Prior to Shorewall
|
||
4.4.17, this made it difficult (to impossible) to include dynamic IP
|
||
addresses in a <ulink url="Shorewall-Lite.html">Shorewall-lite</ulink>
|
||
configuration.</para>
|
||
|
||
<para>Version 4.4.17 implemented <firstterm>Run-time address
|
||
variables</firstterm>. In configuration files, these variables are
|
||
expressed as an apersand ('&') followed by the logical name of an
|
||
interface defined in shorewall-interfaces (5). Wildcard interfaces (those
|
||
ending in '+') are not supported and will cause a compilation
|
||
error.</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Example:</term>
|
||
|
||
<listitem>
|
||
<para><emphasis role="bold">&eth0</emphasis> would represent the
|
||
primary IP address of eth0.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>Beginning with Shorewall 4.5.11, you can define your own address
|
||
variables by using this syntax:</para>
|
||
|
||
<simplelist>
|
||
<member>&{<replaceable>variable</replaceable>}</member>
|
||
</simplelist>
|
||
|
||
<para>where <replaceable>variable</replaceable> is a valid shell variable
|
||
name. The generated script will verify that the
|
||
<replaceable>variable</replaceable> contains a valid host or network
|
||
address, either from the environment or from it being assigned in your
|
||
<emphasis>init</emphasis> <ulink
|
||
url="shorewall_extension_scripts.htm">extension script</ulink>, and will
|
||
raise an error if it does not. In the error case, the state of the
|
||
firewall will remain unchanged.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<para>/etc/shorewall/init:</para>
|
||
|
||
<programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>
|
||
|
||
<para>/etc/shorewall/rules:</para>
|
||
|
||
<programlisting>test:debug net:<emphasis role="bold">&{SMC_ADDR}</emphasis> fw</programlisting>
|
||
|
||
<para>A second form is also available beginning with Shorewall
|
||
4.5.11</para>
|
||
|
||
<simplelist>
|
||
<member>%{<replaceable>variable</replaceable>}</member>
|
||
</simplelist>
|
||
|
||
<para>Unlike with the first form, this form does not require the variable
|
||
to be set. If the variable is empty, the generated script will supply the
|
||
all-zeros address (0.0.0.0 in IPv4 and :: in IPv6). In most cases, the
|
||
compiler simply omits rules containing matches on the all-zeros
|
||
address.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<para>/etc/shorewall/init:</para>
|
||
|
||
<programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>
|
||
|
||
<para>/etc/shorewall/rules:</para>
|
||
|
||
<programlisting>test:debug net:<emphasis role="bold">%{SMC_ADDR}</emphasis> fw</programlisting>
|
||
|
||
<important>
|
||
<para>For a particular address variable, all references must use the
|
||
same prefix character ('&' or '%'). Otherwise, the following error
|
||
message is raised:</para>
|
||
|
||
<simplelist>
|
||
<member>ERROR: Mixed required/optional usage of address variable
|
||
<replaceable>variable</replaceable></member>
|
||
</simplelist>
|
||
</important>
|
||
|
||
<para>Run-time address variables may be used in the SOURCE and DEST column
|
||
of the following configuration files:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><ulink
|
||
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="Actions.html">Action</ulink> files</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-accounting.html">shorewall-blacklist</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="Macros.html">Macro</ulink> files</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="manpages/shorewall-tos.html">shorewall-tos</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>They may also appear in the ORIGINAL DEST column of:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><ulink
|
||
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="Macros.html">Macro</ulink> files</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>For optional interfaces, if the interface is not usable at the time
|
||
that the firewall starts, one of two approaches are taken, depending on
|
||
the context:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>the all-zero address will be used (0.0.0.0 in IPv4 and :: in
|
||
IPv6), resulting in no packets matching the rule (or all packets if
|
||
used with exclusion).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>the entire rule is omitted from the ruleset.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Beginning with Shorewall 4.5.1, <firstterm>Run-time Gateway
|
||
Variables</firstterm> in the form of a percent sign ('%') followed by a
|
||
logical interface name are also supported. These are expanded at run-time
|
||
to the gateway through the named interface. For optional interfaces, if
|
||
the interface is not usable at the time that the firewall starts, the nil
|
||
address will be used (0.0.0.0 in IPv4 and :: in IPv6), resulting in no
|
||
packets matching the rule. Run-time gateway variables may be used in the
|
||
SOURCE and DEST columns of the following configuration files:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><ulink
|
||
url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="Actions.html">Action</ulink> files</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-accounting.html">shorewall-blacklist</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="Macros.html">Macro</ulink> files</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5) (As a
|
||
qualifier to the INTERFACE).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink
|
||
url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="manpages/shorewall-tos.html">shorewall-tos</ulink>
|
||
(5)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Example:</term>
|
||
|
||
<listitem>
|
||
<para><emphasis role="bold">%eth0</emphasis> would represent the IP
|
||
address of the gateway out of eth0.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>If there is no gateway out of the named interface, the nil IP
|
||
address is used (0.0.0.0 in IPv4 and :: in IPv6). That way, the generated
|
||
rule will match no packets (or all packets if used with exclusion).</para>
|
||
</section>
|
||
|
||
<section id="ActionVariables">
|
||
<title>Action Variables</title>
|
||
|
||
<para>Action variables were introduced in Shorewall 4.4.16 and may be
|
||
accessed within the body of an <ulink
|
||
url="Actions.html">action</ulink>.</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Parameter variables</term>
|
||
|
||
<listitem>
|
||
<para>Parameter variables expand to the value of the corresponding
|
||
action parameter. <emphasis>$1</emphasis> is the first parameter,
|
||
<emphasis>$2</emphasis> is the second parameter and so on.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>Chain name</term>
|
||
|
||
<listitem>
|
||
<para>Beginning with Shorewall 4.5.10, $0 expands to the name of the
|
||
action chain. Shorewall generates a separate chain for each unique
|
||
(action,log-level,log-tag,parameters) tupple. The first such chain
|
||
has the same name as the action itself. Subsequent chains are formed
|
||
by prepending '%' to the action name and appending a number to
|
||
insure uniqueness. For an action called 'Action', the chains would
|
||
be <emphasis>Action</emphasis>, <emphasis>%Action</emphasis>,
|
||
<emphasis>%Action0</emphasis>, <emphasis>%Action1</emphasis> and so
|
||
on.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</section>
|
||
|
||
<section id="ShorewallVariables">
|
||
<title>Shorewall Variables</title>
|
||
|
||
<para>Shorewall Variables were introduced in Shorewall 4.5.11. To insure
|
||
uniqueness, these variables start with the character @; the name of the
|
||
variable must be enclosed in {...} when the following character is
|
||
alphanumeric or is an underscore ("_"). With the exception of @0 (or it's
|
||
alias @chain), Shorewall variables may only be used within an action
|
||
body.</para>
|
||
|
||
<para>Prior to Shorewall 4.5.13, Shorewall variables are read-only.
|
||
Beginning with Shorewall 4.5.13, their values may be altered using the
|
||
?SET directive.</para>
|
||
|
||
<para>The Shorewall variables are:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>@0 and @chain (@{0} and @{chain})</term>
|
||
|
||
<listitem>
|
||
<para>Expands to the name of the current chain. Unlike $0, @0 has
|
||
all non-alphanumeric characters except underscore removed. Also
|
||
unlike $0, @0 may be used in SWITCH columns in configuration
|
||
files.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>@1, @2, ... (@{1}, @{2}, ...</term>
|
||
|
||
<listitem>
|
||
<para>These are synonyms for the Action parameter variables $1, $2,
|
||
etc.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>@loglevel (@{loglevel})</term>
|
||
|
||
<listitem>
|
||
<para>Expands to the log level specified when the action was
|
||
invoked.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>@logtag (@{logtag})</term>
|
||
|
||
<listitem>
|
||
<para>Expands to the log tag specified when the action was
|
||
invoked.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>@disposition (@{disposition})</term>
|
||
|
||
<listitem>
|
||
<para>Added in Shorewall 4.5.13. When a non-inlined action is
|
||
entered, this variable is set to the empty value. When an inline
|
||
action is entered, the variable's value is unchanged.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>Beginning with Shorewall 4.5.13, the values of @chain and
|
||
@disposition are used to generated the --log-prefix in logging rules. When
|
||
either is empty, the historical value is used to generate the
|
||
--log-prefix. </para>
|
||
</section>
|
||
|
||
<section id="Conditional">
|
||
<title>Conditional Entries</title>
|
||
|
||
<para>Beginning with Shorewall 4.5.2, lines in configuration files may be
|
||
conditionally included or omitted based on the setting of <link
|
||
linkend="Variables">Shell variables</link>.</para>
|
||
|
||
<para>The general form is:</para>
|
||
|
||
<programlisting>?IF <replaceable>$variable
|
||
|
||
</replaceable><lines to be included if $variable is non-empty and non-zero>
|
||
|
||
?ELSE
|
||
|
||
<lines to be omitted if $variable is non-empty and non-zero>
|
||
|
||
?ENDIF</programlisting>
|
||
|
||
<para>The compiler predefines two special
|
||
<replaceable>variable</replaceable>s that may only be used in ?IF
|
||
lines:</para>
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>__IPV4</term>
|
||
|
||
<listitem>
|
||
<para>True if this is an IPv4 compilation</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>__IPV6</term>
|
||
|
||
<listitem>
|
||
<para>True if this is an IPv6 compilation.</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>Unless <replaceable>variable</replaceable> is one of these
|
||
pre-defined ones, it is searched for in the following places in the order
|
||
listed.</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>the compiler's environmental variables.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>variables set in
|
||
<filename>/etc/shorewall/params</filename>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>options set in
|
||
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>options set in the <filename>shorewallrc</filename> file when
|
||
Shorewall Core was installed.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<important>
|
||
<para>Beginning with Shorewall 4.5.11, the compiler's environmental
|
||
variables are search last rather than first.</para>
|
||
</important>
|
||
|
||
<para>If the <replaceable>variable</replaceable> is still not
|
||
found:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>if it begins with '__', then those leading characters are
|
||
stripped off.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>the variable is then searched for in the defined
|
||
<firstterm>capabilities</firstterm>. The current set of capabilities
|
||
may be obtained by the command <command>shorewall show
|
||
capabilities</command> (the capability names are in
|
||
parentheses).</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>If it is not found in any of those places, the
|
||
<replaceable>variable</replaceable> is assumed to have a value of 0
|
||
(false) in Shorewall versions prior to 4.5.11. In 4.5.11 and later, it is
|
||
assumed to have the value '' (an empty string, which also evaluates to
|
||
false).</para>
|
||
|
||
<para>The setting in <filename>/etc/shorewall/params</filename> by be
|
||
overridden at runtime, provided the setting in
|
||
<filename>/etc/shorewall/params</filename> is done like this:</para>
|
||
|
||
<programlisting>[ -n "${<replaceable>variable</replaceable>:=0}" ]</programlisting>
|
||
|
||
<para>or like this:</para>
|
||
|
||
<programlisting>[ -n "${<replaceable>variable</replaceable>}" ] || <replaceable>variable</replaceable>=0</programlisting>
|
||
|
||
<para>Either of those will set variable to 0 if it is not set to a
|
||
non-empty value in the environment. The setting can be overridden at
|
||
runtime:</para>
|
||
|
||
<programlisting><replaceable>variable</replaceable>=1 shorewall restart -c # use -c to force recompilation if AUTOMAKE=Yes in /etc/shorewall/shorewall.conf</programlisting>
|
||
|
||
<para>The ?ELSE may be omitted if there are no lines to be omitted.</para>
|
||
|
||
<para>The test may also be inverted using '!':</para>
|
||
|
||
<programlisting>?IF ! <replaceable>$variable
|
||
|
||
</replaceable><lines to be omitted if $variable is non-empty and non-zero>
|
||
|
||
?ELSE
|
||
|
||
<lines to be included if $variable is non-empty and non-zero>
|
||
|
||
?ENDIF</programlisting>
|
||
|
||
<para>Conditional entries may be nested but the number of ?IFs must match
|
||
the number of ?ENDs in any give file. <link linkend="INCLUDE">INCLUDE
|
||
directives</link> are ignored in omitted lines.</para>
|
||
|
||
<programlisting>?IF <replaceable>$variable1
|
||
|
||
</replaceable><lines to be included if $variable1 is non-empty and non-zero>
|
||
|
||
?IF $variable2
|
||
|
||
<lines to be included if $variable1 and $variable2 are non-empty and non-zero>
|
||
|
||
?ELSE
|
||
|
||
<lines to be omitted if $variable1 is non-empty and non-zero and if $variable2 is empty or zero>
|
||
|
||
?ENDIF
|
||
<replaceable>
|
||
</replaceable><lines to be included if $variable1 is non-empty and non-zero>
|
||
|
||
?ELSE
|
||
|
||
<lines to be omitted if $variable is non-empty and non-zero>
|
||
|
||
?ENDIF</programlisting>
|
||
|
||
<para>Beginning with Shorewall 4.5.6, rather than a simple variable in ?IF
|
||
directives, Perl-compatible expressions are allowed (after the Shorewall
|
||
compiler expands all variables, the resulting expression is then evaluated
|
||
by Perl). Variables in the expressions are as described above.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>?IF $BLACKLIST_LOGLEVEL == 6 && ! __LOG_OPTIONS</programlisting>
|
||
|
||
<para>Additionally, a ?ELSIF directive is supported.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>?IF <replaceable>expression-1
|
||
|
||
</replaceable><lines to be included if expression-1 evaluates to true (non-empty and non-zero)
|
||
|
||
?ELSIF <replaceable>expression1-2</replaceable>
|
||
|
||
<lines to be included if expression-1 evaluates to false (zero or empty) and expression-2 evaluates to true
|
||
|
||
?ELSIF <replaceable>expression-3
|
||
</replaceable>
|
||
<lines to be included if expression-1 and expression-2 both evalute to false and expression-3 evalutes to true
|
||
|
||
?ELSE
|
||
|
||
<lines to be included if all three expressions evaluate to false.
|
||
|
||
?ENDIF</programlisting>
|
||
</section>
|
||
|
||
<section id="Embedded">
|
||
<title>Embedded Shell and Perl</title>
|
||
|
||
<para>Earlier versions of Shorewall offered <ulink
|
||
url="shorewall_extension_scripts.htm">extension scripts</ulink> to allow
|
||
users to extend Shorewall's functionality. Extension scripts were designed
|
||
to work under the limitations of the Bourne Shell. With the current
|
||
Perl-based compiler, <firstterm>Embedded scripts</firstterm> offer a
|
||
richer and more flexible extension capability.</para>
|
||
|
||
<para>While inline scripts may be written in either Shell or Perl, those
|
||
written in Perl have a lot more power. They may be used in all
|
||
configuration files except <filename>/etc/shorewall/params</filename> and
|
||
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
|
||
|
||
<para><emphasis role="bold">Note:</emphasis>In this section, '[' and ']'
|
||
are meta-characters which indicate that what they enclose is optional and
|
||
may be omitted.</para>
|
||
|
||
<para>Single line scripts take one of the following forms:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>[<emphasis role="bold">?</emphasis>]<emphasis
|
||
role="bold">PERL</emphasis> <<emphasis>perl
|
||
script</emphasis>></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>[<emphasis role="bold">?</emphasis>]<emphasis
|
||
role="bold">SHELL</emphasis> <<emphasis>shell
|
||
script</emphasis>></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<note>
|
||
<para>The optional leading question mark (?) is allowed in Shorewall
|
||
4.5.5 and later.</para>
|
||
</note>
|
||
|
||
<para>Shell scripts run in a child shell process and their output is piped
|
||
back to the compiler which processes that output as if it were embedded at
|
||
the point of the script.</para>
|
||
|
||
<para>Example: The following entries in
|
||
<filename>/etc/shorewall/rules</filename> are equivalent:<programlisting>SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done</programlisting><programlisting>ACCEPT net fw tcp 22
|
||
ACCEPT loc fw tcp 22
|
||
ACCEPT dmz fw tcp 22</programlisting></para>
|
||
|
||
<para>Perl scripts run in the context of of the compiler process using
|
||
Perl's eval() function. Perl scripts are implicitly prefixed by the
|
||
following:</para>
|
||
|
||
<programlisting>package Shorewall::User;
|
||
use Shorewall::Config ( qw/shorewall/ );</programlisting>
|
||
|
||
<para>To produce output that will be processed by the compiler as if it
|
||
were embedded in the file at the point of the script, pass that output to
|
||
the Shorewall::Config::shorewall() function. The Perl equivalent of the
|
||
above SHELL script would be:<programlisting>PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</programlisting>A
|
||
couple of more points should be mentioned:</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>Compile-time extension scripts are also implicitly prefixed by
|
||
"package Shorewall::User;".</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>A <emphasis role="bold">compile</emphasis> extension script is
|
||
supported. That script is run early in the compilation process and
|
||
allows users to load additional modules and to define data and
|
||
functions for use in subsequent embedded scripts and extension
|
||
scripts.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><ulink url="ManualChains.html">Manual Chains</ulink> may be
|
||
added in the <emphasis role="bold">compile</emphasis> extension
|
||
script..</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>Multi-line scripts use one of the following forms:<programlisting>[<emphasis
|
||
role="bold">?</emphasis>]<emphasis role="bold">BEGIN SHELL</emphasis>
|
||
<<emphasis>shell script</emphasis>>
|
||
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
|
||
role="bold">SHELL</emphasis> ]</programlisting><programlisting>[<emphasis
|
||
role="bold">?</emphasis>]<emphasis role="bold">BEGIN PERL</emphasis> [<emphasis
|
||
role="bold">;</emphasis>]
|
||
<<emphasis>perl script</emphasis>>
|
||
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
|
||
role="bold">PERL</emphasis> ] [<emphasis role="bold">;</emphasis>]</programlisting><note>
|
||
<para>The optional leading question mark (?) is allowed in Shorewall
|
||
4.5.5 and later.</para>
|
||
</note></para>
|
||
</section>
|
||
|
||
<section id="dnsnames">
|
||
<title>Using DNS Names</title>
|
||
|
||
<caution>
|
||
<para>I personally recommend strongly against using DNS names in
|
||
Shorewall configuration files. If you use DNS names and you are called
|
||
out of bed at 2:00AM because Shorewall won't start as a result of DNS
|
||
problems then don't say that you were not forewarned.</para>
|
||
</caution>
|
||
|
||
<para>Host addresses in Shorewall configuration files may be specified as
|
||
either IP addresses or DNS Names.</para>
|
||
|
||
<para>DNS names in iptables rules aren't nearly as useful as they first
|
||
appear. When a DNS name appears in a rule, the iptables utility resolves
|
||
the name to one or more IP addresses and inserts those addresses into the
|
||
rule. So changes in the DNS->IP address relationship that occur after
|
||
the firewall has started have absolutely no effect on the firewall's rule
|
||
set.</para>
|
||
|
||
<para>For some sites, using DNS names is very risky. Here's an
|
||
example:</para>
|
||
|
||
<programlisting>teastep@ursa:~$ dig pop.gmail.com
|
||
|
||
; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com
|
||
;; global options: printcmd
|
||
;; Got answer:
|
||
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1774
|
||
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0
|
||
|
||
;; QUESTION SECTION:
|
||
;pop.gmail.com. IN A
|
||
|
||
;; ANSWER SECTION:
|
||
pop.gmail.com. <emphasis role="bold">300</emphasis> IN CNAME gmail-pop.l.google.com.
|
||
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.109
|
||
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.111</programlisting>
|
||
|
||
<para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
|
||
minutes later, the answer may change!</para>
|
||
|
||
<para>So this rule may work for five minutes then suddently stop
|
||
working:</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST
|
||
# PORT(S)
|
||
POP(ACCEPT) loc net:pop.gmail.com</programlisting>
|
||
|
||
<para>If your firewall rules include DNS names then:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>If your <filename>/etc/resolv.conf </filename>is wrong then your
|
||
firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your <filename>/etc/nsswitch.conf</filename> is wrong then
|
||
your firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your Name Server(s) is(are) down then your firewall won't
|
||
start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your startup scripts try to start your firewall before
|
||
starting your DNS server then your firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Factors totally outside your control (your ISP's router is down
|
||
for example), can prevent your firewall from starting.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>You must bring up your network interfaces prior to starting your
|
||
firewall.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Each DNS name must be fully qualified and include a minimum of two
|
||
periods (although one may be trailing). This restriction is imposed by
|
||
Shorewall to insure backward compatibility with existing configuration
|
||
files.</para>
|
||
|
||
<example id="validdns">
|
||
<title>Valid DNS Names</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>mail.shorewall.net</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>shorewall.net. (note the trailing period).</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</example>
|
||
|
||
<example id="invaliddns">
|
||
<title>Invalid DNS Names</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>mail (not fully qualified)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>shorewall.net (only one period)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</example>
|
||
|
||
<para>DNS names may not be used as:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The server address in a DNAT rule (/etc/shorewall/rules
|
||
file)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>In the ADDRESS column of an entry in /etc/shorewall/masq.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>In the <filename>/etc/shorewall/nat</filename> file.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>These restrictions are imposed by Netfilter and not by
|
||
Shorewall.</para>
|
||
</section>
|
||
|
||
<section id="Lists">
|
||
<title>Comma-separated Lists</title>
|
||
|
||
<para>Comma-separated lists are allowed in a number of contexts within the
|
||
configuration files. A comma separated list:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Must not have any embedded white space.<programlisting> Valid: routefilter,dhcp,arpfilter
|
||
Invalid: routefilter, dhcp, arpfilter</programlisting></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If you use line continuation to break a comma-separated list,
|
||
the comma must be the last thing on the continued line before '\'
|
||
unless the continuation line has no leading white space.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Entries in a comma-separated list may appear in any
|
||
order.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section id="Compliment">
|
||
<title>Complementing an Address, Subnet, Protocol or Port List</title>
|
||
|
||
<para>Where specifying an IP address, a subnet or an interface, you can
|
||
precede the item with <quote>!</quote> to specify the complement of the
|
||
item. For example, !192.168.1.4 means <quote>any host but
|
||
192.168.1.4</quote>. There must be no white space following the
|
||
<quote>!</quote>.</para>
|
||
|
||
<para>Similarly, in columns that specify an IP protocol, you can preceed
|
||
the protocol name or number by "!". For example, !tcp means "any protocol
|
||
except tcp".</para>
|
||
|
||
<para>This also works with port lists, providing that the list contains 15
|
||
or fewer ports (where a <link linkend="Ranges">port range</link> counts as
|
||
two ports). For example !ssh,smtp means "any port except 22 and
|
||
25".</para>
|
||
|
||
<para>In Shorewall 4.4.19 and later, icmp type lists are supported but
|
||
complementing an icmp type list is <emphasis>not</emphasis> supported. You
|
||
may, however, complement a single icmp (icmp6) type.</para>
|
||
</section>
|
||
|
||
<section id="Exclusion">
|
||
<title>Exclusion Lists</title>
|
||
|
||
<para>Where a comma-separated list of addresses is accepted, an
|
||
<firstterm>exclusion list</firstterm> may also be included. An exclusion
|
||
list is a comma-separated list of addresses that begins with "!".</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
|
||
|
||
<para>The above list refers to "All addresses except 192.168.1.3,
|
||
192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
|
||
|
||
<para>Exclusion lists can also be added after a network address.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
|
||
|
||
<para>The above list refers to "All addresses in 192.168.1.0-192.168.1.255
|
||
except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
|
||
</section>
|
||
|
||
<section id="IPRanges">
|
||
<title>IP Address Ranges</title>
|
||
|
||
<para>If you kernel and iptables have iprange match support, you may use
|
||
IP address ranges in Shorewall configuration file entries; IP address
|
||
ranges have the syntax <<emphasis>low IP
|
||
address</emphasis>>-<<emphasis>high IP address</emphasis>>.
|
||
Example: 192.168.1.5-192.168.1.12.</para>
|
||
|
||
<para>To see if your kernel and iptables have the required support, use
|
||
the <command>shorewall show capabilities</command> command:</para>
|
||
|
||
<programlisting>>~ <command>shorewall show capabilities</command>
|
||
...
|
||
Shorewall has detected the following iptables/netfilter capabilities:
|
||
NAT: Available
|
||
Packet Mangling: Available
|
||
Multi-port Match: Available
|
||
Connection Tracking Match: Available
|
||
Packet Type Match: Not available
|
||
Policy Match: Available
|
||
Physdev Match: Available
|
||
<emphasis role="bold">IP range Match: Available <--------------</emphasis></programlisting>
|
||
</section>
|
||
|
||
<section id="Ports">
|
||
<title>Protocol Number/Names and Port Numbers/Service Names</title>
|
||
|
||
<para>Unless otherwise specified, when giving a protocol number you can
|
||
use either an integer or a protocol name from
|
||
<filename>/etc/protocols</filename>. Similarly, when giving a port number
|
||
you can use either an integer or a service name from
|
||
<filename>/etc/services</filename>.<note>
|
||
<para>The rules compiler translates protocol names to protocol numbers
|
||
and service names to port numbers itself.</para>
|
||
</note></para>
|
||
|
||
<para>Also, unless otherwise documented, a protocol number/name can be
|
||
preceded by '!' to specify "All protocols except this one" (e.g.,
|
||
"!tcp").</para>
|
||
</section>
|
||
|
||
<section id="ICMP">
|
||
<title>ICMP and ICMP6 Types and Codes</title>
|
||
|
||
<para>When dealing with ICMP, the DEST PORT specifies the type or type and
|
||
code. You may specify the numeric type, the numeric type and code
|
||
separated by a slash (e.g., 3/4) or you may use a type name.</para>
|
||
|
||
<para>Type names for IPv4 and their corresponding type or type/code
|
||
are:</para>
|
||
|
||
<programlisting>echo-reply' => 0
|
||
destination-unreachable => 3
|
||
network-unreachable => 3/0
|
||
host-unreachable => 3/1
|
||
protocol-unreachable => 3/2
|
||
port-unreachable => 3/3
|
||
fragmentation-needed => 3/4
|
||
source-route-failed => 3/5
|
||
network-unknown => 3/6
|
||
host-unknown => 3/7
|
||
network-prohibited => 3/9
|
||
host-prohibited => 3/10
|
||
TOS-network-unreachable => 3/11
|
||
TOS-host-unreachable => 3/12
|
||
communication-prohibited => 3/13
|
||
host-precedence-violation => 3/14
|
||
precedence-cutoff => 3/15
|
||
source-quench => 4
|
||
redirect => 5
|
||
network-redirect => 5/0
|
||
host-redirect => 5/1
|
||
TOS-network-redirect => 5/2
|
||
TOS-host-redirect => 5/3
|
||
echo-request => 8
|
||
router-advertisement => 9
|
||
router-solicitation => 10
|
||
time-exceeded => 11
|
||
ttl-zero-during-transit => 11/0
|
||
ttl-zero-during-reassembly=> 11/1
|
||
parameter-problem => 12
|
||
ip-header-bad => 12/0
|
||
required-option-missing => 12/1
|
||
timestamp-request => 13
|
||
timestamp-reply => 14
|
||
address-mask-request => 17
|
||
address-mask-reply => 18</programlisting>
|
||
|
||
<para>Type names for IPv6 and their corresponding type or type/code
|
||
are:</para>
|
||
|
||
<programlisting>destination-unreachable => 1
|
||
no-route' => 1/0
|
||
communication-prohibited => 1/1
|
||
address-unreachable' => 1/2
|
||
port-unreachable' => 1/3
|
||
packet-too-big => 2
|
||
time-exceeded' => 3
|
||
ttl-exceeded' => 3
|
||
ttl-zero-during-transit => 3/0
|
||
ttl-zero-during-reassembly => 3/1
|
||
parameter-problem => 4
|
||
bad-header => 4/0
|
||
unknown-header-type => 4/1
|
||
unknown-option => 4/2
|
||
echo-request => 128
|
||
echo-reply => 129
|
||
router-solicitation => 133
|
||
router-advertisement => 134
|
||
neighbour-solicitation => 135
|
||
neighbour-advertisement => 136
|
||
redirect => 137</programlisting>
|
||
|
||
<para>Shorewall 4.4 does not accept lists if ICMP (ICMP6) types prior to
|
||
Shorewall 4.4.19.</para>
|
||
</section>
|
||
|
||
<section id="Ranges">
|
||
<title>Port Ranges</title>
|
||
|
||
<para>If you need to specify a range of ports, the proper syntax is
|
||
<low port number>:<high port number>. For example, if you want
|
||
to forward the range of tcp ports 4000 through 4100 to local host
|
||
192.168.1.3, the entry in /etc/shorewall/rules is:</para>
|
||
|
||
<programlisting>#ACTION SOURCE DESTINATION PROTO DEST PORTS(S)
|
||
DNAT net loc:192.168.1.3 tcp <emphasis role="bold">4000:4100</emphasis></programlisting>
|
||
|
||
<para>If you omit the low port number, a value of zero is assumed; if you
|
||
omit the high port number, a value of 65535 is assumed.</para>
|
||
|
||
<para>Also, unless otherwise documented, a port range can be preceded by
|
||
'!' to specify "All ports except those in this range" (e.g.,
|
||
"!4000:4100").</para>
|
||
</section>
|
||
|
||
<section id="Portlists">
|
||
<title>Port Lists</title>
|
||
|
||
<para>In most cases where a port or port range may appear, a
|
||
comma-separated list of ports or port ranges may also be entered.
|
||
Shorewall requires the Netfilter <emphasis
|
||
role="bold">multiport</emphasis> match capability if ports lists are used
|
||
(see the output of "<emphasis role="bold">shorewall show
|
||
capabilities</emphasis>").</para>
|
||
|
||
<para>Also, unless otherwise documented, a port list can be preceded by
|
||
'!' to specify "All ports except these" (e.g., "!80,443").</para>
|
||
|
||
<para>Prior to Shorewall 4.4.4, port lists appearing in the <ulink
|
||
url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
|
||
(5) file may specify no more than 15 ports; port ranges appearing in a
|
||
list count as two ports each.</para>
|
||
</section>
|
||
|
||
<section id="MAC">
|
||
<title>Using MAC Addresses</title>
|
||
|
||
<para>Media Access Control (MAC) addresses can be used to specify packet
|
||
source in several of the configuration files. In order to control traffic
|
||
to/from a host by its MAC address, the host must be on the same network as
|
||
the firewall.</para>
|
||
|
||
<para>To use this feature, your kernel must have MAC Address Match support
|
||
(CONFIG_IP_NF_MATCH_MAC) included.</para>
|
||
|
||
<para>MAC addresses are 48 bits wide and each Ethernet Controller has a
|
||
unique MAC address.</para>
|
||
|
||
<para>In GNU/Linux, MAC addresses are usually written as a series of 6 hex
|
||
numbers separated by colons.</para>
|
||
|
||
<example id="mac">
|
||
<title>MAC Address of an Ethernet Controller</title>
|
||
|
||
<programlisting> gateway:~ # <command>ip link ls dev eth0</command>
|
||
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc htb qlen 1000
|
||
link/ether <emphasis role="bold">02:00:08:E3:FA:55</emphasis> brd ff:ff:ff:ff:ff:ff
|
||
gateway:~ #</programlisting>
|
||
</example>
|
||
|
||
<para>Because Shorewall uses colons as a separator for address fields,
|
||
Shorewall requires MAC addresses to be written in another way. In
|
||
Shorewall, MAC addresses begin with a tilde (<quote>~</quote>) and consist
|
||
of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in
|
||
the example above would be written <emphasis
|
||
role="bold">~02-00-08-E3-FA-55</emphasis>.</para>
|
||
|
||
<note>
|
||
<para>It is not necessary to use the special Shorewall notation in the
|
||
<filename><ulink
|
||
url="MAC_Validation.html">/etc/shorewall/maclist</ulink></filename>
|
||
file.</para>
|
||
</note>
|
||
</section>
|
||
|
||
<section id="RateLimit">
|
||
<title>Rate Limiting (Rate and Burst)</title>
|
||
|
||
<para>Shorewall supports rate limiting in a number of ways. When
|
||
specifying a rate limit, both a <firstterm>rate</firstterm> and a
|
||
<firstterm>burst</firstterm> value are given.</para>
|
||
|
||
<para>Example from <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>
|
||
|
||
<simplelist>
|
||
<member>LOGRATE=10/minute</member>
|
||
|
||
<member>LOGBURST=5</member>
|
||
</simplelist>
|
||
|
||
<para>For each logging rule, the first time the rule is reached, the
|
||
packet will be logged; in fact, since the burst is 5, the first five
|
||
packets will be logged. After this, it will be 6 seconds (1 minute divided
|
||
by the rate of 10) before a message will be logged from the rule,
|
||
regardless of how many packets reach it. Also, every 6 seconds which
|
||
passes, one of the bursts will be regained; if no packets hit the rule for
|
||
30 seconds, the burst will be fully recharged; back where we
|
||
started.</para>
|
||
|
||
<note>
|
||
<para>The LOGRATE and LOGBURST options are deprecated in favor of
|
||
LOGLIMIT.</para>
|
||
</note>
|
||
|
||
<para>Shorewall also supports per-IP rate limiting.</para>
|
||
|
||
<para>Another example from <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>
|
||
|
||
<simplelist>
|
||
<member>LOGLIMIT="s:5/min:5"</member>
|
||
</simplelist>
|
||
|
||
<para>Here, the leading "s:" indicates that logging is to be limited by
|
||
source IP address ("d:" would indicate limiting by destination IP
|
||
address).</para>
|
||
|
||
<para>"s:" is followed by the rate (5 messages per minute) and the burst
|
||
(5).</para>
|
||
|
||
<para>The rate and limit arguments have the same meaning as in the example
|
||
above.</para>
|
||
</section>
|
||
|
||
<section id="Switches">
|
||
<title>Switches</title>
|
||
|
||
<para>There are times when you would like to enable or disable one or more
|
||
rules in the configuration without having to do a <command>shorewall
|
||
restart</command>. This may be accomplished using the SWITCH column in
|
||
<ulink url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5) or
|
||
<ulink url="manpages6/shorewall6-rules.html">shorewall6-rules</ulink> (5).
|
||
Using this column requires that your kernel and iptables include
|
||
<firstterm>Condition Match Support</firstterm> and you must be running
|
||
Shorewall 4.4.24 or later. See the output of <command>shorewall show
|
||
capabilities</command> and <command>shorewall version</command> to
|
||
determine if you can use this feature. As of this writing, Condition Match
|
||
Support requires that you install xtables-addons.</para>
|
||
|
||
<para>The SWITCH column contains the name of a
|
||
<firstterm>switch.</firstterm> Each switch is initially in the <emphasis
|
||
role="bold">off</emphasis> position. You can turn on the switch named
|
||
<emphasis>switch1</emphasis> by:</para>
|
||
|
||
<simplelist>
|
||
<member><command>echo 1 >
|
||
/proc/net/nf_condition/switch1</command></member>
|
||
</simplelist>
|
||
|
||
<para>You can turn it off again by:</para>
|
||
|
||
<simplelist>
|
||
<member><command>echo 0 >
|
||
/proc/net/nf_condition/switch1</command></member>
|
||
</simplelist>
|
||
|
||
<para>If you simply include the switch name in the SWITCH column, then the
|
||
rule is enabled only when the switch is <emphasis
|
||
role="bold">on</emphasis>. If you precede the switch name with ! (e.g.,
|
||
!switch1), then the rule is enabled only when the switch is <emphasis
|
||
role="bold">off</emphasis>. Switch settings are retained over
|
||
<command>shorewall restart</command>.</para>
|
||
|
||
<para>Shorewall requires that switch names:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>begin with a letter and be composed of letters, digits,
|
||
underscore ('_') or hyphen ('-'); and</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>be 30 characters or less in length.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Multiple rules can be controlled by the same switch.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<blockquote>
|
||
<para>Forward port 80 to dmz host $BACKUP if switch 'primary_down' is
|
||
on.</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ MARK CONNLIMIT TIME HEADERS SWITCH
|
||
# PORT(S) PORT(S) DEST LIMIT GROUP
|
||
DNAT net dmz:$BACKUP tcp 80 - - - - - - - - <emphasis
|
||
role="bold">primary_down</emphasis> </programlisting>
|
||
</blockquote>
|
||
</section>
|
||
|
||
<section id="Logical">
|
||
<title>Logical Interface Names</title>
|
||
|
||
<para>When dealing with a complex configuration, it is often awkward to
|
||
use physical interface names in the Shorewall configuration.</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>You need to remember which interface is which.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If you move the configuration to another firewall, the interface
|
||
names might not be the same.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Beginning with Shorewall 4.4.4, you can use logical interface names
|
||
which are mapped to the actual interface using the
|
||
<option>physical</option> option in <ulink
|
||
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink>
|
||
(5).</para>
|
||
|
||
<para>Here is an example:</para>
|
||
|
||
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
|
||
net <emphasis role="bold">COM_IF </emphasis> detect dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,<emphasis
|
||
role="bold">physical=eth0</emphasis>
|
||
net <emphasis role="bold">EXT_IF</emphasis> detect dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,<emphasis
|
||
role="bold">physical=eth2</emphasis>
|
||
loc <emphasis role="bold">INT_IF </emphasis> detect dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,<emphasis
|
||
role="bold">physical=eth1</emphasis>
|
||
dmz <emphasis role="bold">VPS_IF </emphasis> detect logmartians=1,routefilter=0,routeback,<emphasis
|
||
role="bold">physical=venet0</emphasis>
|
||
loc <emphasis role="bold">TUN_IF</emphasis> detect <emphasis
|
||
role="bold">physical=tun+</emphasis></programlisting>
|
||
|
||
<para>In this example, COM_IF is a logical interface name that refers to
|
||
Ethernet interface <filename class="devicefile">eth0</filename>, EXT_IF is
|
||
a logical interface name that refers to Ethernet interface <filename
|
||
class="devicefile">eth2</filename>, and so on.</para>
|
||
|
||
<para>Here are a couple of more files from the same configuration:</para>
|
||
|
||
<para><ulink url="manpages/shorewall-masq.html">shorewall-masq</ulink>
|
||
(5):</para>
|
||
|
||
<programlisting>#INTERFACE SOURCE ADDRESS
|
||
|
||
COMMENT Masquerade Local Network
|
||
<emphasis role="bold">COM_IF</emphasis> 0.0.0.0/0
|
||
<emphasis role="bold">EXT_IF </emphasis> !206.124.146.0/24 206.124.146.179:persistent</programlisting>
|
||
|
||
<para><ulink
|
||
url="manpages/shorewall-providers.html">shorewall-providers</ulink>
|
||
(5)</para>
|
||
|
||
<programlisting>#NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
|
||
Avvanta 1 0x10000 main <emphasis role="bold">EXT_IF </emphasis> 206.124.146.254 loose,fallback <emphasis
|
||
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis>
|
||
Comcast 2 0x20000 main <emphasis role="bold">COM_IF</emphasis> detect balance <emphasis
|
||
role="bold">INT_IF,VPS_IF,TUN_IF</emphasis></programlisting>
|
||
|
||
<para>Note in particular that Shorewall translates TUN_IF to <filename
|
||
class="devicefile">tun*</filename> in the COPY column.</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>Optional and Required Interfaces</title>
|
||
|
||
<para>Normally, Shorewall assumes that all interfaces described in <ulink
|
||
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5)
|
||
are going to be in an up and usable state when Shorewall starts or
|
||
restarts. You can alter that assumption by specifying the <emphasis
|
||
role="bold">optional</emphasis> option in the OPTIONS column.</para>
|
||
|
||
<para>When an interface is marked as optional, Shorewall will determine
|
||
the interface state at <command>start</command> and
|
||
<command>restart</command> and adjust its configuration
|
||
accordingly.</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The <emphasis role="bold">arp_filter</emphasis>, <emphasis
|
||
role="bold">arp_ignore</emphasis>, <emphasis
|
||
role="bold">routefilter</emphasis>, <emphasis
|
||
role="bold">logmartians</emphasis>, <emphasis
|
||
role="bold">proxyarp</emphasis> and <emphasis
|
||
role="bold">sourceroute</emphasis> options are not enforced when the
|
||
interface is down, thus avoiding an error message such
|
||
as:<programlisting>WARNING: Cannot set Martian logging on ppp0</programlisting></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If the interface is associated with a provider in <ulink
|
||
url="manpages/shorewall-providers.html">shorewall-providers</ulink>
|
||
(5), <command>start</command> and <command>restart</command> will not
|
||
fail if the interface is not usable.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>When DETECT_DNAT_IPADDRS=Yes in <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5), DNAT
|
||
rules in shorewall-rules (5) involving the interface will be omitted
|
||
when the interface does not have an IP address.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If <emphasis role="bold">detect</emphasis> is specified in the
|
||
ADDRESS column of an entry in <ulink
|
||
url="manpages/shorewall-masq.html">shorewall-masq</ulink> (5) then the
|
||
firewall still start if the optional interface in the INTERFACE column
|
||
does not have an IP address.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>If you don't want the firewall to start unless a given interface is
|
||
usable, then specify <emphasis role="bold">required</emphasis> in the
|
||
OPTIONS column of <ulink
|
||
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5).
|
||
If you have installed and configured the Shorewall-init package, then when
|
||
the interface becomes available, an automatic attempt will be made to
|
||
start the firewall.</para>
|
||
</section>
|
||
|
||
<section id="Levels">
|
||
<title>Shorewall Configurations</title>
|
||
|
||
<para>Shorewall allows you to have configuration directories other than
|
||
<filename class="directory">/etc/shorewall</filename>. The shorewall
|
||
check, start and restart commands allow you to specify an alternate
|
||
configuration directory and Shorewall will use the files in the alternate
|
||
directory rather than the corresponding files in /etc/shorewall. The
|
||
alternate directory need not contain a complete configuration; those files
|
||
not in the alternate directory will be read from <filename
|
||
class="directory">/etc/shorewall</filename>.<important>
|
||
<para>Shorewall requires that the file
|
||
<filename>/etc/shorewall/shorewall.conf</filename> to always exist.
|
||
Certain global settings are always obtained from that file. If you
|
||
create alternative configuration directories, do not remove
|
||
/etc/shorewall/shorewall.conf.</para>
|
||
</important></para>
|
||
|
||
<para>This facility permits you to easily create a test or temporary
|
||
configuration by</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>copying the files that need modification from /etc/shorewall to
|
||
a separate directory;</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>modify those files in the separate directory; and</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>specifying the separate directory in a <command>shorewall
|
||
start</command> or <command>shorewall restart</command> command (e.g.,
|
||
<command>shorewall restart /etc/testconfig</command> )</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</section>
|
||
|
||
<section id="Save">
|
||
<title>Saved Configurations</title>
|
||
|
||
<para>Shorewall allows you to <firstterm>save</firstterm> the
|
||
currently-running configuration in a form that permits it to be
|
||
re-installed quickly. When you save the configuration using the
|
||
<command>shorewall save</command> command, the running configuration is
|
||
saved in a file in the <filename
|
||
class="directory">/var/lib/shorewall</filename> directory. The default
|
||
name of that file is <filename>/var/lib/shorewall/restore</filename> but
|
||
you can specify a different name as part of the command. For example, the
|
||
command <command>shorewall save standard</command> will save the running
|
||
configuration in <filename>/var/lib/shorewall/standard</filename>. A saved
|
||
configuration is re-installed using the <command>shorewall
|
||
restore</command> command. Again, that command normally will restore the
|
||
configuration saved in <filename>/var/lib/shorewall/restore</filename> but
|
||
as with the <command>save</command> command, you can specify a different
|
||
file name in the command. For example, <command>shorewall restore
|
||
standard</command> will re-install the configuration saved in
|
||
<filename>/var/lib/shorewall/standard</filename>. By permitting you to
|
||
save different configurations under different names, Shorewall provides a
|
||
means for quickly switching between these different saved
|
||
configurations.</para>
|
||
|
||
<para>As mentioned above, the default configuration is called 'restore'
|
||
but like most things in Shorewall, that default can be changed. The
|
||
default name is specified using the <emphasis
|
||
role="bold">RESTOREFILE</emphasis> option in
|
||
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
|
||
|
||
<warning>
|
||
<para>The default saved configuration is used by Shorewall in a number
|
||
of ways besides in the <command>restore</command> command; to avoid
|
||
surprises, I recommend that you read the <ulink
|
||
url="starting_and_stopping_shorewall.htm#Saved">Shorewall Operations
|
||
documentation section about saved configurations</ulink> before creating
|
||
one.</para>
|
||
</warning>
|
||
</section>
|
||
</article>
|