<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Configuration Files</title><link rel="stylesheet" href="html.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="id257527"></a>Configuration Files</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Eastep</span></h3></div></div></div><div><p class="copyright">Copyright © 2001-2008 Thomas M. Eastep</p></div><div><div class="legalnotice"><a id="id292633"></a><p>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.2 or any later version published by the Free Software Foundation; with
no Invariant Sections, with no Front-Cover, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
“<span class="quote"><a class="ulink" href="GnuCopyright.htm" target="_self">GNU Free Documentation
License</a></span>”.</p></div></div><div><p class="pubdate">2008/12/15</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#Files">Files</a></span></dt><dt><span class="section"><a href="#Manpages">Man Pages</a></span></dt><dt><span class="section"><a href="#Comments">Comments</a></span></dt><dt><span class="section"><a href="#COMMENT">Attach Comment to Netfilter Rules</a></span></dt><dt><span class="section"><a href="#BlankColumn">"Blank" Columns</a></span></dt><dt><span class="section"><a href="#Continuation">Line Continuation</a></span></dt><dt><span class="section"><a href="#INCLUDE">INCLUDE Directive</a></span></dt><dt><span class="section"><a href="#Variables">Using Shell Variables</a></span></dt><dt><span class="section"><a href="#Embedded">Embedded Shell and Perl</a></span></dt><dt><span class="section"><a href="#dnsnames">Using DNS Names</a></span></dt><dt><span class="section"><a href="#Lists">Comma-separated Lists</a></span></dt><dt><span class="section"><a href="#Compliment">Complementing an Address or Subnet</a></span></dt><dt><span class="section"><a href="#Exclusion">Exclusion Lists</a></span></dt><dt><span class="section"><a href="#IPRanges">IP Address Ranges</a></span></dt><dt><span class="section"><a href="#Ports">Protocol Number/Names and Port Numbers/Service Names</a></span></dt><dt><span class="section"><a href="#Ranges">Port Ranges</a></span></dt><dt><span class="section"><a href="#Portlists">Port Lists</a></span></dt><dt><span class="section"><a href="#MAC">Using MAC Addresses</a></span></dt><dt><span class="section"><a href="#Levels">Shorewall Configurations</a></span></dt><dt><span class="section"><a href="#Save">Saved Configurations</a></span></dt></dl></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p><span class="bold"><strong>This article applies to Shorewall 3.0 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.</strong></span></p></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>If you copy or edit your configuration files on a system running
Microsoft Windows, you must run them through <a class="ulink" href="http://www.megaloman.com/~hany/software/hd2u/" target="_self">dos2unix</a>
before you use them with Shorewall.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Files"></a>Files</h2></div></div></div><div class="itemizedlist"><ul type="disc"><li><p><code class="filename">/etc/shorewall/shorewall.conf</code> - used to
set global firewall parameters.</p></li><li><p><code class="filename">/etc/shorewall/params</code> - use this file to
set shell variables that you will expand in other files.</p></li><li><p><code class="filename">/etc/shorewall/zones</code> - partition the
firewall's view of the world into zones.</p></li><li><p><code class="filename">/etc/shorewall/policy</code> - establishes
firewall high-level policy.</p></li><li><p><code class="filename">/etc/shorewall/interfaces</code> - describes the
interfaces on the firewall system.</p></li><li><p><code class="filename">/etc/shorewall/hosts</code> - allows defining
zones in terms of individual hosts and subnetworks.</p></li><li><p><code class="filename">/etc/shorewall/masq</code> - directs the
firewall where to use many-to-one (dynamic) Network Address
Translation (a.k.a. Masquerading) and Source Network Address
Translation (SNAT).</p></li><li><p><code class="filename">/etc/shorewall/modules</code> - directs the
firewall to load kernel modules.</p></li><li><p><code class="filename">/etc/shorewall/rules</code> - defines rules that
are exceptions to the overall policies established in
/etc/shorewall/policy.</p></li><li><p><code class="filename">/etc/shorewall/nat</code> - defines one-to-one
NAT rules.</p></li><li><p><code class="filename">/etc/shorewall/proxyarp</code> - defines use of
Proxy ARP.</p></li><li><p><code class="filename">/etc/shorewall/routestopped</code> - defines
hosts accessible when Shorewall is stopped.</p></li><li><p><code class="filename">/etc/shorewall/tcrules </code>- defines marking
of packets for later use by traffic control/shaping or policy
routing.</p></li><li><p><code class="filename">/etc/shorewall/tos</code> - defines rules for
setting the TOS field in packet headers.</p></li><li><p><code class="filename">/etc/shorewall/tunnels</code> - defines tunnels
(VPN) with end-points on the firewall system.</p></li><li><p><code class="filename">/etc/shorewall/blacklist</code> - lists
blacklisted IP/subnet/MAC addresses.</p></li><li><p><code class="filename">/etc/shorewall/init</code> - commands that you
wish to execute at the beginning of a “<span class="quote">shorewall start</span>”
or “<span class="quote">shorewall restart</span>”.</p></li><li><p><code class="filename">/etc/shorewall/start</code> - commands that you
wish to execute at the completion of a “<span class="quote">shorewall
start</span>” or “<span class="quote">shorewall restart</span>”</p></li><li><p><code class="filename">/etc/shorewall/stop </code>- commands that you
wish to execute at the beginning of a “<span class="quote">shorewall
stop</span>”.</p></li><li><p><code class="filename">/etc/shorewall/stopped</code> - commands that
you wish to execute at the completion of a “<span class="quote">shorewall
stop</span>”.</p></li><li><p><code class="filename">/etc/shorewall/ecn</code> - disable Explicit
Congestion Notification (ECN - RFC 3168) to remote hosts or
networks.</p></li><li><p><code class="filename">/etc/shorewall/accounting</code> - define IP
traffic accounting rules</p></li><li><p><code class="filename">/etc/shorewall/actions</code> and
<code class="filename">/usr/share/shorewall/action.template</code> allow
user-defined actions.</p></li><li><p><code class="filename">/etc/shorewall/providers</code> - defines an
alternate routing table.</p></li><li><p><code class="filename">/etc/shorewall/route_rules</code> (Added in
Shorewall 3.2.0) - Defines routing rules to be used in conjunction
with the routing tables defined in
<code class="filename">/etc/shorewall/providers</code>.</p></li><li><p><code class="filename">/etc/shorewall/tcdevices</code>,
<code class="filename">/etc/shorewall/tcclasses</code>,
<code class="filename">/etc/shorewall/tcfilters</code> (tcfilters added in
Shorewall 4.2.0) - Define traffic shaping.</p></li><li><p><code class="filename">/etc/shorewall/tcrules</code> - Mark or classify
traffic for traffic shaping or multiple providers.</p></li><li><p><code class="filename">/etc/shorewall/vardir</code> - (Added in
Shorewall 4.0.0-RC2) - Determines the directory where Shorewall
maintains its state.</p></li><li><p><code class="filename">/usr/share/shorewall/actions.std</code> -
Actions defined by Shorewall.</p></li><li><p><code class="filename">/usr/share/shorewall/action.*</code> - Details
of actions defined by Shorewall.</p></li><li><p><code class="filename">/usr/share/shorewall/macro.*</code> - Details of
macros defined by Shorewall.</p></li><li><p><code class="filename">/usr/share/rfc1918</code> — Defines the behavior
of the 'norfc1918' interface option in
<code class="filename">/etc/shorewall/interfaces</code>. <span class="bold"><strong>If you need to change this file, copy it to
<code class="filename">/etc/shorewall</code> and modify the
copy</strong></span>.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Manpages"></a>Man Pages</h2></div></div></div><p>Beginning with Shorewall version 3.4, 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-".</p><p>Example — To view the manual page for
<code class="filename">/etc/shorewall/interfaces</code>:</p><pre class="programlisting">man shorewall-interfaces</pre><p>The /etc/shorewall/shorewall.conf file is an exception -- the man
page for that file is 'shorewall.conf':</p><pre class="programlisting">man shorewall.conf</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Comments"></a>Comments</h2></div></div></div><p>You may place comments in configuration files by making the first
non-whitespace character a pound sign (“<span class="quote">#</span>”). 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.</p><div class="example"><a id="comment"></a><p class="title"><b>Example 1. Comments in a Configuration File</b></p><div class="example-contents"><pre class="programlisting"># This is a comment
ACCEPT net $FW tcp www #This is an end-of-line comment</pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="COMMENT"></a>Attach Comment to Netfilter Rules</h2></div></div></div><p>Beginning with Shorewall version 3.3.3, if you kernel and iptables
contain comment match support (see the output of <span class="command"><strong>shorewall show
capabilities</strong></span>), then you can attach comments to Netfilter rules.
This feature is available in the following files:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="filename">/etc/shorewall/masq</code></p></li><li><p><code class="filename">/etc/shorewall/nat</code></p></li><li><p><code class="filename">/etc/shorewall/rules</code></p></li><li><p><code class="filename">/etc/shorewall/tcrules</code></p></li><li><p>Action definition files
(<code class="filename">/etc/shorewall/action.*</code>)</p></li><li><p>Macro definition files (/etc/shorewall/macro.*) — Added in
Shorewall-perl 4.2.0. They are ignored by Shorewall-shell 4.1 and
later.</p></li></ul></div><p>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 <span class="command"><strong>shorewall[-lite]
show</strong></span> and <span class="command"><strong>shorewall[-lite] dump</strong></span> 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.</p><p>Example (<code class="filename">/etc/shorewall/rules</code>):</p><pre class="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</pre><p>Here's the corresponding output from
<code class="filename">/sbin/shorewall-lite</code>:</p><pre class="programlisting">gateway:~ # <span class="command"><strong>shorewall-lite show loc2net</strong></span>
Shorewall Lite 3.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2006
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 <span class="bold"><strong>/* Stop NETBIOS noise */</strong></span>
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:137:139 <span class="bold"><strong>/* Stop NETBIOS noise */</strong></span>
0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 <span class="bold"><strong>/* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */</strong></span>
5 316 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0
gateway:~ #
</pre><p>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:</p><p><code class="filename">/usr/share/shorewall/macro.SSH</code>:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST SOURCE RATE USER/
# PORT(S) PORT(S) LIMIT GROUP
COMMENT SSH
PARAM - - tcp 22 </pre><p>
<code class="filename">/etc/shorewall/rules</code>:</p><pre class="programlisting">COMMENT Allow SSH from home
SSH/ALLOW net:$MYIP $FW
COMMENT</pre><p>The comment line in macro.SSH will not override the
COMMENT line in the rules file and the generated rule will show <span class="bold"><strong>/* Allow SSH from home */</strong></span> when displayed through
the Shorewall show and dump commands.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="BlankColumn"></a>"Blank" Columns</h2></div></div></div><p>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.</p><p>Example:</p><pre class="programlisting">#INTERFACE BROADCAST OPTIONS
br0 - routeback</pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Continuation"></a>Line Continuation</h2></div></div></div><p>You may continue lines in the configuration files using the usual
backslash (“<span class="quote">\</span>”) followed immediately by a new line character
(Enter key).</p><div class="example"><a id="continuation"></a><p class="title"><b>Example 2. Line Continuation</b></p><div class="example-contents"><pre class="programlisting">ACCEPT net $FW tcp \↵
smtp,www,pop3,imap #Services running on the firewall</pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="INCLUDE"></a>INCLUDE Directive</h2></div></div></div><p>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 <a class="ulink" href="manpages/shorewall.conf.html" target="_self">shorewall.conf</a>(5)).</p><p>INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
directives are ignored with a warning message.</p><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>If you are using <a class="ulink" href="CompiledPrograms.html%23Lite" target="_self">Shorewall Lite</a> and are
running a version of Shorewall earlier than 3.2.9, it is not advisable
to use INCLUDE in the <code class="filename">params</code> file in an export
directory. If you do that, you must ensure that the included file is
also present on the firewall system's <code class="filename">/etc/shorewall-lite/</code> directory.</p><p>Beginning with Shorewall version 3.2.9 (3.4.0 RC2), you can set
EXPORTPARAMS=No in <code class="filename">shorewall.conf</code>. That prevents
the <code class="filename">params</code> file from being copied into the compiled
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
<code class="filename">params</code> file.</p></div><div class="example"><a id="include"></a><p class="title"><b>Example 3. Use of INCLUDE</b></p><div class="example-contents"><pre class="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 -----</pre><p>Users of Shorewall-perl 4.0.6 and later may include multiple files
in one command using an <a class="link" href="#Embedded" title="Embedded Shell and Perl">embedded shell
command</a>.</p><p>Example (include all of the files ending in ".rules" in a
directory:):</p><pre class="programlisting">gateway:/etc/shorewall # ls rules.d
ALL.rules DNAT.rules FW.rules NET.rules REDIRECT.rules VPN.rules
gateway:/etc/shorewall # </pre><p>/etc/shorewall/rules:</p><pre class="programlisting">SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules</pre></div></div><br class="example-break" /></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Variables"></a>Using Shell Variables</h2></div></div></div><p>You may use the <code class="filename">/etc/shorewall/params</code> file to
set shell variables that you can then use in some of the other
configuration files.</p><p>It is suggested that variable names begin with an upper case letter
to distinguish them from variables used internally within the Shorewall
programs</p><p>Example:</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"> /etc/shorewall/params
NET_IF=eth0
NET_BCAST=130.252.100.255
NET_OPTIONS=routefilter,norfc1918
/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,norfc1918
</pre></blockquote></div><p>Variables may be used anywhere in the other configuration
files.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shorewall-perl users: If you use "$FW" on the right side of
assignments in the <code class="filename">/etc/shorewall/params</code> file,
you must also set the FW variable in that file.</p><p>Example:</p><pre class="programlisting">/etc/shorewall/zones:
#ZONE TYPE OPTIONS
<span class="bold"><strong>fw</strong></span> firewall
/etc/shorewall/params:
FW=<span class="bold"><strong>fw</strong></span>
BLARG=$FW:206.124.146.176</pre></div><p>Because the <code class="filename">/etc/shorewall/params</code> 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:</p><div class="orderedlist"><ol type="1"><li><p>The code should not have side effects, especially on other
shorewall configuration files.</p></li><li><p>The code should be safe to execute multiple times without
producing different results.</p></li><li><p>Should not depend on where the code is called from (the params
file is sourced by both /sbin/shorewall and
/usr/lib/shorewall/firewall).</p></li><li><p>Should not assume anything about the state of Shorewall.</p></li><li><p>The names of any functions or variables declared should begin
with an upper case letter.</p></li><li><p>The <code class="filename">/etc/shorewall/params</code> file is processed
by the compiler at compile-time and by the compiled script at
run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if you have
set EXPORTPARAMS=No in <code class="filename">shorewall.conf</code>, then the
<code class="filename"><code class="filename">params</code></code> file is only
processed by the compiler; it is not run by the compiled
script.</p></li><li><p>If you are using <a class="ulink" href="CompiledPrograms.html#Lite" target="_self">Shorewall Lite</a> and if the
<code class="filename">params</code> script needs to set shell variables based
on the configuration of the firewall system, you can use this
trick:</p><pre class="programlisting">EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</pre><p>The <span class="command"><strong>shorewall-lite call</strong></span> command allows you to
to call interactively any Shorewall function that you can call in an
extension script.</p></li></ol></div><p>When expanding a variable, the acceptable forms of expansion depend
on whether you are using Shorewall-shell or Shorewall-perl.</p><div class="itemizedlist"><ul type="disc"><li><p>Shorewall-shell and all Shorewall versions prior to 4.0 can use
any form of expansion supported by the shell ($VAR, ${VAR},
${VAR:=val}, ...).</p></li><li><p>Shorewall-perl only supports the $VAR and ${VAR} forms.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Embedded"></a>Embedded Shell and Perl</h2></div></div></div><p>This feature was added in Shorewall-perl 4.0.6. To use it, you must
be running 4.0.6 or later and must be using Shorewall-perl
(SHOREWALL_COMPILER=perl in shorewall.conf).</p><p>Earlier versions of Shorewall offered <a class="ulink" href="shorewall_extension_scripts.htm" target="_self">extension scripts</a> to allow
users to extend Shorewall's functionality. Extension scripts were designed
to work under the limitations of the Bourne Shell. With Shorewall-perl,
<em class="firstterm">Embedded scripts</em> offer a richer and more flexible
extension capability.</p><p>While inline scripts scripts may be written in either Shell or Perl,
those written in Perl have a lot more power.</p><p>Embedded scripts can be either single-line or multi-line. Single
line scripts take one of the following forms:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>PERL</strong></span> <<span class="emphasis"><em>perl
script</em></span>></p></li><li><p><span class="bold"><strong>SHELL</strong></span> <<span class="emphasis"><em>shell
script</em></span>></p></li></ul></div><p>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.</p><p>Example: The following entries in
<code class="filename">/etc/shorewall/rules</code> are equivalent:</p><pre class="programlisting">SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done</pre><pre class="programlisting">ACCEPT net fw tcp 22
ACCEPT loc fw tcp 22
ACCEPT dmz fw tcp 22</pre><p>Perl scripts run in the context of of the compiler process. 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() function. The Perl equivalent of the above SHELL script would
be:</p><pre class="programlisting">PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</pre><p>Perl
scripts are implicitly prefixed by the following:</p><pre class="programlisting">package Shorewall::User;
use Shorewall::Config qw/shorewall/;</pre><p>As part of the change that added embedded scripts:</p><div class="orderedlist"><ol type="1"><li><p>Compile-time extension scripts are also implicitly prefixed by
"package Shorewall::User;".</p></li><li><p>A <span class="bold"><strong>compile</strong></span> extension script was
added for use by Shorewall-perl. 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.</p></li><li><p>A <a class="ulink" href="ManualChains.html" target="_self">Manual Chain</a> facility
was added.</p></li></ol></div><p>Multi-line scripts use one of the following forms:</p><pre class="programlisting"><span class="bold"><strong>BEGIN SHELL</strong></span>
<<span class="emphasis"><em>shell script</em></span>>
<span class="bold"><strong>END</strong></span> [ <span class="bold"><strong>SHELL</strong></span> ]</pre><pre class="programlisting"><span class="bold"><strong>BEGIN PERL</strong></span> [;]
<<span class="emphasis"><em>perl script</em></span>>
<span class="bold"><strong>END</strong></span> [ <span class="bold"><strong>PERL</strong></span> ] [<span class="bold"><strong>;</strong></span>]</pre><p><span class="bold"><strong>Note: </strong></span>The '[' and ']' above are
meta-characters which indicate that what they enclose is optional and may
be omitted. So you may follow PERL with a semicolon ( ':') or you may omit
the semicolon.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="dnsnames"></a>Using DNS Names</h2></div></div></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>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.</p></div><p>Host addresses in Shorewall configuration files may be specified as
either IP addresses or DNS Names.</p><p>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.</p><p>For some sites, using DNS names is very risky. Here's an
example:</p><pre class="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. <span class="bold"><strong>300</strong></span> IN CNAME gmail-pop.l.google.com.
gmail-pop.l.google.com. <span class="bold"><strong>300</strong></span> IN A 209.85.201.109
gmail-pop.l.google.com. <span class="bold"><strong>300</strong></span> IN A 209.85.201.111</pre><p>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
minutes later, the answer may change!</p><p>So this rule may work for five minutes then suddently stop
working:</p><pre class="programlisting">#ACTION SOURCE DEST PROTO DEST
# PORT(S)
POP/ACCEPT loc net:pop.gmail.com</pre><p>If your firewall rules include DNS names then:</p><div class="itemizedlist"><ul type="disc"><li><p>If your <code class="filename">/etc/resolv.conf </code>is wrong then your
firewall won't start.</p></li><li><p>If your <code class="filename">/etc/nsswitch.conf</code> is wrong then
your firewall won't start.</p></li><li><p>If your Name Server(s) is(are) down then your firewall won't
start.</p></li><li><p>If your startup scripts try to start your firewall before
starting your DNS server then your firewall won't start.</p></li><li><p>Factors totally outside your control (your ISP's router is down
for example), can prevent your firewall from starting.</p></li><li><p>You must bring up your network interfaces prior to starting your
firewall.</p></li></ul></div><p>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.</p><div class="example"><a id="validdns"></a><p class="title"><b>Example 4. Valid DNS Names</b></p><div class="example-contents"><div class="itemizedlist"><ul type="disc"><li><p>mail.shorewall.net</p></li><li><p>shorewall.net. (note the trailing period).</p></li></ul></div></div></div><br class="example-break" /><div class="example"><a id="invaliddns"></a><p class="title"><b>Example 5. Invalid DNS Names</b></p><div class="example-contents"><div class="itemizedlist"><ul type="disc"><li><p>mail (not fully qualified)</p></li><li><p>shorewall.net (only one period)</p></li></ul></div></div></div><br class="example-break" /><p>DNS names may not be used as:</p><div class="itemizedlist"><ul type="disc"><li><p>The server address in a DNAT rule (/etc/shorewall/rules
file)</p></li><li><p>In the ADDRESS column of an entry in /etc/shorewall/masq.</p></li><li><p>In the <code class="filename">/etc/shorewall/nat</code> file.</p></li></ul></div><p>These restrictions are imposed by Netfilter and not by
Shorewall.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Lists"></a>Comma-separated Lists</h2></div></div></div><p>Comma-separated lists are allowed in a number of contexts within the
configuration files. A comma separated list:</p><div class="itemizedlist"><ul type="disc"><li><p>Must not have any embedded white space.</p><pre class="programlisting"> Valid: routefilter,dhcp,norfc1918
Invalid: routefilter, dhcp, norfc1818</pre></li><li><p>If you use line continuation to break a comma-separated list,
the continuation line(s) must begin in column 1 (or there would be
embedded white space)</p></li><li><p>Entries in a comma-separated list may appear in any
order.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Compliment"></a>Complementing an Address or Subnet</h2></div></div></div><p>Where specifying an IP address, a subnet or an interface, you can
precede the item with “<span class="quote">!</span>” to specify the complement of the
item. For example, !192.168.1.4 means “<span class="quote">any host but
192.168.1.4</span>”. There must be no white space following the
“<span class="quote">!</span>”.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Exclusion"></a>Exclusion Lists</h2></div></div></div><p>Shorewall 3.0 differs from earlier versions in that in most contexts
where a comma-separated list of addresses is accepted, an
<em class="firstterm">exclusion list</em> may also be included. An exclusion
list is a comma-separated list of addresses that begins with "!".</p><p>Example:</p><pre class="programlisting">!192.168.1.3,192.168.1.12,192.168.1.32/27</pre><p>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.</p><p>Exclusion lists can also be added after a network address.</p><p>Example:</p><pre class="programlisting">192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27</pre><p>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.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="IPRanges"></a>IP Address Ranges</h2></div></div></div><p>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 <<span class="emphasis"><em>low IP
address</em></span>>-<<span class="emphasis"><em>high IP address</em></span>>.
Example: 192.168.1.5-192.168.1.12.</p><p>To see if your kernel and iptables have the required support, use
the <span class="command"><strong>shorewall show capabilities</strong></span> command:</p><pre class="programlisting">>~ <span class="command"><strong>shorewall show capabilities</strong></span>
...
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
<span class="bold"><strong>IP range Match: Available <--------------
</strong></span></pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Ports"></a>Protocol Number/Names and Port Numbers/Service Names</h2></div></div></div><p>Unless otherwise specified, when giving a protocol number you can
use either an integer or a protocol name from
<code class="filename">/etc/protocols</code>. Similarly, when giving a port number
you can use either an integer or a service name from
<code class="filename">/etc/services</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shorewall-perl translates protocol names to protocol numbers and
service names to port numbers itself.</p><p>In Shorewall versions 4.0.0 - 4.0.4, the mapping that it uses is
contained in the Perl module
<code class="filename">/usr/share/shorewall-perl/Shorewall/Ports.pm</code>.
That module is built when Shorewall is installed or upgraded using the
current <code class="filename">/etc/protocols</code> and
<code class="filename">/etc/services</code> files as input (if the build
program fails, a fallback version of the module is installed).</p><p>To generate a new Ports.pm module:</p><pre class="programlisting">cp /usr/share/shorewall-perl/Shorewall/Ports.pm /usr/share/shorewall-perl/Shorewall/Ports.pm.backup
/usr/share/shorewall/buildports.pm > /usr/share/shorewall-perl/Shorewall/Ports.pm</pre><p>Beginning with Shorewall version 4.0.5, the
<code class="filename">/usr/share/shorewall-perl/Shorewall/Ports.pm</code> has
been eliminated and the Shorewall-perl compiler uses Perl's interfaces
to getprotobyname(3posix) and getservbyname(3posix).</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Ranges"></a>Port Ranges</h2></div></div></div><p>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:</p><pre class="programlisting">#ACTION SOURCE DESTINATION PROTO DEST PORTS(S)
DNAT net loc:192.168.1.3 tcp 4000:4100</pre><p>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.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Portlists"></a>Port Lists</h2></div></div></div><p>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 will use the Netfilter <span class="bold"><strong>multiport</strong></span> match capability if it is available (see
the output of "<span class="bold"><strong>shorewall show
capabilities</strong></span>") and if its use is appropriate.</p><p>Shorewall can use multiport match if:</p><div class="orderedlist"><ol type="1"><li><p>The list contains 15 or fewer port number; and</p></li><li><p>There are no port ranges listed OR your iptables/kernel support
the Extended <span class="bold"><strong>multiport</strong></span> match (again
see the output of "<span class="command"><strong>shorewall show capabilities</strong></span>").
Where the Extended <span class="bold"><strong>multiport</strong></span> match is
available, each port range counts as two ports toward the maximum of
15.</p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shorewall-perl requires <span class="bold"><strong>multiport</strong></span>
match in order to accept port lists in Shorewall configuration files. It
further requires Extended <span class="bold"><strong>multiport</strong></span>
match in order to accept port ranges in port lists. Shorewall-perl will
never break a list longer than 15 ports (with each range counting as two
ports) into smaller lists. So you must be sure that your port lists can
be handled directly by the Netfilter/iptables capabilities
available.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="MAC"></a>Using MAC Addresses</h2></div></div></div><p>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.</p><p>To use this feature, your kernel must have MAC Address Match support
(CONFIG_IP_NF_MATCH_MAC) included.</p><p>MAC addresses are 48 bits wide and each Ethernet Controller has a
unique MAC address.</p><p>In GNU/Linux, MAC addresses are usually written as a series of 6 hex
numbers separated by colons.</p><div class="example"><a id="mac"></a><p class="title"><b>Example 6. MAC Address of an Ethernet Controller</b></p><div class="example-contents"><pre class="programlisting"> gateway:~ # <span class="command"><strong>ip link ls dev eth0</strong></span>
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc htb qlen 1000
link/ether <span class="bold"><strong>02:00:08:E3:FA:55</strong></span> brd ff:ff:ff:ff:ff:ff
gateway:~ #</pre></div></div><br class="example-break" /><p>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 (“<span class="quote">~</span>”) and consist
of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in
the example above would be written <span class="bold"><strong>~02-00-08-E3-FA-55</strong></span>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is not necessary to use the special Shorewall notation in the
<code class="filename"><a class="ulink" href="MAC_Validation.html" target="_self">/etc/shorewall/maclist</a></code>
file.</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Levels"></a>Shorewall Configurations</h2></div></div></div><p>Shorewall allows you to have configuration directories other than
<code class="filename">/etc/shorewall</code>. 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 <code class="filename">/etc/shorewall</code>.</p><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Shorewall requires that the file
<code class="filename">/etc/shorewall/shorewall.conf</code> 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.</p></div><p>This facility permits you to easily create a test or temporary
configuration by</p><div class="orderedlist"><ol type="1"><li><p>copying the files that need modification from /etc/shorewall to
a separate directory;</p></li><li><p>modify those files in the separate directory; and</p></li><li><p>specifying the separate directory in a <span class="command"><strong>shorewall
start</strong></span> or <span class="command"><strong>shorewall restart</strong></span> command (e.g.,
<span class="command"><strong>shorewall restart /etc/testconfig</strong></span> )</p></li></ol></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Save"></a>Saved Configurations</h2></div></div></div><p>Shorewall allows you to <em class="firstterm">save</em> the
currently-running configuration in a form that permits it to be
re-installed quickly. When you save the configuration using the
<span class="command"><strong>shorewall save</strong></span> command, the running configuration is
saved in a file in the <code class="filename">/var/lib/shorewall</code> directory. The default
name of that file is <code class="filename">/var/lib/shorewall/restore</code> but
you can specify a different name as part of the command. For example, the
command <span class="command"><strong>shorewall save standard</strong></span> will save the running
configuration in <code class="filename">/var/lib/shorewall/standard</code>. A saved
configuration is re-installed using the <span class="command"><strong>shorewall
restore</strong></span> command. Again, that command normally will restore the
configuration saved in <code class="filename">/var/lib/shorewall/restore</code> but
as with the <span class="command"><strong>save</strong></span> command, you can specify a different
file name in the command. For example, <span class="command"><strong>shorewall restore
standard</strong></span> will re-install the configuration saved in
<code class="filename">/var/lib/shorewall/standard</code>. By permitting you to
save different configurations under different names, Shorewall provides a
means for quickly switching between these different saved
configurations.</p><p>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 <span class="bold"><strong>RESTOREFILE</strong></span> option in
<code class="filename">/etc/shorewall/shorewall.conf</code>.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>The default saved configuration is used by Shorewall in a number
of ways besides in the <span class="command"><strong>restore</strong></span> command; to avoid
surprises, I recommend that you read the <a class="ulink" href="starting_and_stopping_shorewall.htm#Saved" target="_self">Shorewall Operations
documentation section about saved configurations</a> before creating
one.</p></div></div></div></body></html>
