2004-02-14 19:06:39 +01:00
<?xml version="1.0" encoding="UTF-8"?>
2008-07-07 22:22:09 +02:00
< !DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
2004-02-14 19:06:39 +01:00
<article >
<!-- $Id$ -->
<articleinfo >
2010-02-19 17:12:56 +01:00
<title > Configuration Files Tips and Hints</title>
2004-02-14 19:06:39 +01:00
<authorgroup >
<author >
<firstname > Tom</firstname>
<surname > Eastep</surname>
</author>
</authorgroup>
2006-07-07 03:04:16 +02:00
<pubdate > <?dbtimestamp format="Y/m/d"?> </pubdate>
2004-02-14 19:06:39 +01:00
<copyright >
2011-09-23 23:44:20 +02:00
<year > 2001-2011</year>
2004-02-14 19:06:39 +01:00
<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
2004-10-23 19:27:42 +02:00
<quote > <ulink url= "GnuCopyright.htm" > GNU Free Documentation
License</ulink> </quote> .</para>
2004-02-14 19:06:39 +01:00
</legalnotice>
</articleinfo>
2005-08-31 20:58:40 +02:00
<caution >
2009-02-28 04:45:43 +01:00
<para > <emphasis role= "bold" > This article applies to Shorewall 4.3 and
2005-08-31 20:58:40 +02:00
later. If you are running a version of Shorewall earlier than Shorewall
2009-10-16 19:45:46 +02:00
4.3.5 then please see the documentation for that
release.</emphasis> </para>
2005-08-31 20:58:40 +02:00
</caution>
2004-02-14 19:06:39 +01:00
<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>
2010-06-06 17:24:28 +02:00
<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>
2004-02-14 19:06:39 +01:00
<section id= "Files" >
<title > Files</title>
2004-10-23 19:27:42 +02:00
<para > <itemizedlist >
<listitem >
<para > <filename > /etc/shorewall/shorewall.conf</filename> - used to
2007-07-09 22:47:59 +02:00
set global firewall parameters.</para>
2004-10-23 19:27:42 +02:00
</listitem>
<listitem >
<para > <filename > /etc/shorewall/params</filename> - use this file to
set shell variables that you will expand in other files.</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 >
2005-09-17 08:26:55 +02:00
<para > <filename > /etc/shorewall/routestopped</filename> - defines
hosts accessible when Shorewall is stopped.</para>
2004-10-23 19:27:42 +02:00
</listitem>
<listitem >
2010-06-25 15:31:26 +02:00
<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
2004-10-23 19:27:42 +02:00
routing.</para>
</listitem>
<listitem >
<para > <filename > /etc/shorewall/tos</filename> - defines rules for
setting the TOS field in packet headers.</para>
</listitem>
<listitem >
2005-10-22 19:37:38 +02:00
<para > <filename > /etc/shorewall/tunnels</filename> - defines tunnels
(VPN) with end-points on the firewall system.</para>
2004-10-23 19:27:42 +02:00
</listitem>
<listitem >
<para > <filename > /etc/shorewall/blacklist</filename> - lists
blacklisted IP/subnet/MAC addresses.</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
2005-10-22 19:37:38 +02:00
<filename > /usr/share/shorewall/action.template</filename> allow
user-defined actions.</para>
2004-10-23 19:27:42 +02:00
</listitem>
2005-05-27 08:16:09 +02:00
<listitem >
<para > <filename > /etc/shorewall/providers</filename> - defines an
2005-08-31 20:58:40 +02:00
alternate routing table.</para>
2005-05-27 08:16:09 +02:00
</listitem>
2006-07-09 23:25:23 +02:00
<listitem >
2012-02-23 22:36:00 +01:00
<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>
2006-07-09 23:25:23 +02:00
</listitem>
2008-03-22 17:11:52 +01:00
<listitem >
<para > <filename > /etc/shorewall/tcdevices</filename> ,
<filename > /etc/shorewall/tcclasses</filename> ,
2010-04-12 02:00:19 +02:00
<filename > /etc/shorewall/tcfilters</filename> - Define complex
traffic shaping.</para>
2008-03-22 17:11:52 +01:00
</listitem>
<listitem >
<para > <filename > /etc/shorewall/tcrules</filename> - Mark or classify
traffic for traffic shaping or multiple providers.</para>
</listitem>
2010-04-12 02:00:19 +02:00
<listitem >
<para > <filename > /etc/shorewall/tcinterfaces</filename> and
<filename > /etc/shorewall-tcpri</filename> - Define simple traffic
shaping.</para>
</listitem>
2010-09-06 18:06:40 +02:00
<listitem >
<para > <filename > /etc/shorewall/secmarks</filename> - Added in
Shorewall 4.4.13. Attach an SELinux context to selected
packets.</para>
</listitem>
2007-07-09 21:39:28 +02:00
<listitem >
2009-02-28 04:45:43 +01:00
<para > <filename > /etc/shorewall/vardir</filename> - Determines the
directory where Shorewall maintains its state.</para>
2007-07-09 21:39:28 +02:00
</listitem>
2004-10-23 19:27:42 +02:00
<listitem >
<para > <filename > /usr/share/shorewall/actions.std</filename> -
Actions defined by Shorewall.</para>
</listitem>
<listitem >
2005-08-31 20:58:40 +02:00
<para > <filename > /usr/share/shorewall/action.*</filename> - Details
2004-10-23 19:27:42 +02:00
of actions defined by Shorewall.</para>
</listitem>
2005-08-31 20:58:40 +02:00
<listitem >
<para > <filename > /usr/share/shorewall/macro.*</filename> - Details of
macros defined by Shorewall.</para>
</listitem>
2009-06-28 17:11:27 +02:00
<listitem >
<para > <filename > /usr/share/shorewall/modules</filename> - directs
2009-09-10 23:55:50 +02:00
the firewall to load kernel modules.</para>
2009-06-28 17:11:27 +02:00
</listitem>
2009-05-30 17:34:34 +02:00
<listitem >
<para > <filename > /usr/share/modules</filename> — Specifies the kernel
2010-01-22 05:30:35 +01:00
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>
2009-05-30 17:34:34 +02:00
</listitem>
2004-10-23 19:27:42 +02:00
</itemizedlist> </para>
2009-06-28 17:11:27 +02:00
<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>
2004-02-14 19:06:39 +01:00
</section>
2006-12-22 17:22:10 +01:00
<section id= "Manpages" >
2006-12-19 03:10:12 +01:00
<title > Man Pages</title>
2009-02-28 04:45:43 +01:00
<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>
2006-12-19 03:10:12 +01:00
<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>
2004-02-14 19:06:39 +01:00
<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>
2007-06-28 17:09:37 +02:00
<example id= "comment" >
2004-02-14 19:06:39 +01:00
<title > Comments in a Configuration File</title>
<programlisting > # This is a comment
2005-09-12 20:43:26 +02:00
ACCEPT net $FW tcp www #This is an end-of-line comment</programlisting>
2004-02-14 19:06:39 +01:00
</example>
</section>
2010-07-25 01:04:21 +02:00
<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>
2006-10-17 00:19:36 +02:00
<section id= "COMMENT" >
<title > Attach Comment to Netfilter Rules</title>
2009-02-28 04:45:43 +01:00
<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>
2006-10-17 00:19:36 +02:00
<itemizedlist >
2009-03-19 22:52:13 +01:00
<listitem >
<para > <filename > /etc/shorewall/accounting</filename> </para>
</listitem>
2006-10-17 00:19:36 +02:00
<listitem >
<para > <filename > /etc/shorewall/masq</filename> </para>
</listitem>
<listitem >
<para > <filename > /etc/shorewall/nat</filename> </para>
</listitem>
2009-03-19 22:52:13 +01:00
<listitem >
2009-03-20 17:47:27 +01:00
<para > <filename > /etc/shorewall/notrack</filename> </para>
2009-03-19 22:52:13 +01:00
</listitem>
2006-10-17 00:19:36 +02:00
<listitem >
<para > <filename > /etc/shorewall/rules</filename> </para>
</listitem>
2010-09-07 05:37:34 +02:00
<listitem >
<para > <filename > /etc/shorewall/secmarks</filename> </para>
</listitem>
2006-10-17 00:19:36 +02:00
<listitem >
<para > <filename > /etc/shorewall/tcrules</filename> </para>
</listitem>
2009-03-19 22:52:13 +01:00
<listitem >
<para > <filename > /etc/shorewall/tunnels</filename> </para>
</listitem>
2006-10-17 00:19:36 +02:00
<listitem >
<para > Action definition files
(<filename > /etc/shorewall/action.*</filename> )</para>
</listitem>
2008-02-06 21:55:00 +01:00
<listitem >
2009-02-28 04:45:43 +01:00
<para > Macro definition files (/etc/shorewall/macro.*)</para>
2008-02-06 21:55:00 +01:00
</listitem>
2006-10-17 00:19:36 +02:00
</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>
2009-02-28 04:45:43 +01:00
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008
2006-10-17 00:19:36 +02:00
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>
2008-02-06 21:55:00 +01:00
<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
2010-07-23 23:32:11 +02:00
SSH(ACCEPT) net:$MYIP $FW
2008-02-06 21:55:00 +01:00
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>
2006-10-17 00:19:36 +02:00
</section>
2008-05-18 15:39:11 +02:00
<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>
2004-02-14 19:06:39 +01:00
<section id= "Continuation" >
<title > Line Continuation</title>
<para > You may continue lines in the configuration files using the usual
2005-10-22 19:37:38 +02:00
backslash (<quote > \</quote> ) followed immediately by a new line character
(Enter key).</para>
2004-02-14 19:06:39 +01:00
2007-06-28 17:09:37 +02:00
<example id= "continuation" >
2004-02-14 19:06:39 +01:00
<title > Line Continuation</title>
2005-10-22 19:37:38 +02:00
<programlisting > ACCEPT net $FW tcp \↵
2004-02-14 19:06:39 +01:00
smtp,www,pop3,imap #Services running on the firewall</programlisting>
2009-03-27 17:55:51 +01:00
<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>
2009-05-30 17:34:34 +02:00
<para > The leading white space on the first through third continuation
2009-03-27 17:55:51 +01:00
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>
2004-02-14 19:06:39 +01:00
</example>
</section>
2011-09-26 02:08:53 +02:00
<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>
2011-10-02 20:45:55 +02:00
<para > There is considerable flexibility in how you specify the
pairs:</para>
2011-09-26 02:08:53 +02:00
2011-10-02 20:45:55 +02:00
<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>
2011-09-26 02:08:53 +02:00
2011-10-02 20:45:55 +02:00
<member > <replaceable > column-name</replaceable> :<replaceable > value</replaceable> </member>
</simplelist>
2011-09-26 02:08:53 +02:00
2011-10-02 20:45:55 +02:00
<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>
2011-09-26 02:08:53 +02:00
<note >
2011-10-02 20:45:55 +02:00
<para > Column names are <emphasis
role="bold">case-insensitive</emphasis> .</para>
2011-09-26 02:08:53 +02:00
</note>
<informaltable >
2011-10-01 18:56:25 +02:00
<tgroup cols= "2" >
2011-09-26 02:08:53 +02:00
<tbody >
<row >
<entry > <emphasis role= "bold" > File</emphasis> </entry>
2011-10-01 18:56:25 +02:00
<entry > <emphasis role= "bold" > Column names</emphasis> </entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > accounting</entry>
2011-10-01 18:56:25 +02:00
<entry > action,chain, source, dest, proto, dport, sport, user,
mark, ipsec, headers</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > blacklist</entry>
2011-10-01 18:56:25 +02:00
<entry > networks,proto,port,options</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > ecn</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,hosts</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > hosts</entry>
2011-10-01 18:56:25 +02:00
<entry > zone,hosts,options</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > interfaces</entry>
2011-10-01 18:56:25 +02:00
<entry > zone,interface,broadcast,options</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > maclist</entry>
2011-10-01 18:56:25 +02:00
<entry > disposition,interface,mac,addresses</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > masq</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,source,address,proto,port,ipsec,mark,user</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > nat</entry>
2011-10-02 20:45:55 +02:00
<entry > external,interface,internal,allints,local</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > netmap</entry>
2011-10-01 18:56:25 +02:00
<entry > type,net1,interface,net2,net3,proto,dport,sport</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > notrack</entry>
2011-10-01 18:56:25 +02:00
<entry > source,dest,proto,dport,sport,user</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > policy</entry>
2011-10-01 18:56:25 +02:00
<entry > source,dest,policy,loglevel,limit,connlimit</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > providers</entry>
2011-10-01 18:56:25 +02:00
<entry > table,number,mark,duplicate,interface,gateway,options,copy</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
2011-10-08 00:07:09 +02:00
<entry > proxyarp and proxyndp</entry>
2011-09-26 02:08:53 +02:00
2011-10-01 18:56:25 +02:00
<entry > address,interface,external,haveroute,persistent</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
2012-01-09 16:19:10 +01:00
<entry > rtrules</entry>
2011-09-26 02:08:53 +02:00
2011-10-01 18:56:25 +02:00
<entry > source,dest,provider,priority</entry>
2011-09-26 02:08:53 +02:00
</row>
2011-10-09 16:05:08 +02:00
<row >
<entry > routes</entry>
<entry > provider,dest,gateway,device</entry>
</row>
2011-09-26 02:08:53 +02:00
<row >
<entry > routestopped</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,hosts,options,proto,dport,sport</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > rules</entry>
2011-10-01 18:56:25 +02:00
<entry > action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > secmarks</entry>
2011-10-02 20:45:55 +02:00
<entry > secmark,chain,source,dest,proto,dport,sport,user,mark</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcclasses</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,mark,rate,ceil,prio,options</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcdevices</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,in_bandwidth,out_bandwidth,options,redirect</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcfilters</entry>
2011-10-02 20:45:55 +02:00
<entry > class,source,dest,proto,dport,sport,tos,length</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcinterfaces</entry>
2011-10-01 18:56:25 +02:00
<entry > interface,type,in_bandwidth,out_bandwidth</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcpri</entry>
2011-10-01 18:56:25 +02:00
<entry > band,proto,port,address,interface,helper</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tcrules</entry>
2011-10-01 18:56:25 +02:00
<entry > mark,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tos</entry>
2011-10-01 18:56:25 +02:00
<entry > source,dest,proto,dport,sport,tos,mark</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > tunnels</entry>
2011-10-01 18:56:25 +02:00
<entry > type,zone,gateway,gateway_zone</entry>
2011-09-26 02:08:53 +02:00
</row>
<row >
<entry > zones</entry>
2011-10-01 18:56:25 +02:00
<entry > zone,type,options,in_options,out_options</entry>
2011-09-26 02:08:53 +02:00
</row>
</tbody>
</tgroup>
</informaltable>
<para > Example (rules file):</para>
<programlisting > #ACTION SOURCE DEST PROTO DEST
# PORT(S)
2011-10-02 20:45:55 +02:00
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>
2011-09-26 02:08:53 +02:00
</section>
2010-11-04 00:31:50 +01:00
<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 >
2010-11-04 17:57:33 +01:00
<para > This address type refer to a single host.</para>
2010-11-04 00:31:50 +01:00
<para > In IPv4, the format is <emphasis > i.j.k.l</emphasis> where
<emphasis > i</emphasis> through <emphasis > l</emphasis> are decimal
2010-11-04 17:57:33 +01:00
numbers between 1 and 255.</para>
2010-11-04 00:31:50 +01:00
<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
2010-11-04 17:57:33 +01:00
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>
2010-11-04 00:31:50 +01:00
</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
2010-11-04 17:57:33 +01:00
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>
2010-11-04 00:31:50 +01:00
</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>
2010-11-04 17:57:33 +01:00
<para > For more information about addressing, see the<ulink
url="shorewall_setup_guide.htm#Addressing"> Setup Guide</ulink> .</para>
2010-11-04 00:31:50 +01:00
</section>
2009-09-10 23:55:50 +02:00
<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
2010-07-23 23:17:38 +02:00
list must be includef in square or angled brackets ("[...]" or
"< ...> "). The list may have <link
linkend="Exclusion">exclusion</link> .</para>
2009-09-10 23:55:50 +02:00
</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
2010-07-23 23:19:05 +02:00
role="bold">loc:[2002:ce7c:92b4:1:a00:27ff:feb1:46a9]</emphasis> </para>
2009-09-10 23:55:50 +02:00
</listitem>
2011-01-26 18:08:48 +01:00
<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>
2009-09-10 23:55:50 +02:00
</orderedlist>
</section>
2004-02-14 19:06:39 +01:00
<section id= "INCLUDE" >
<title > INCLUDE Directive</title>
2007-02-09 18:03:55 +01:00
<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
2008-02-10 17:18:11 +01:00
are resolved using the current CONFIG_PATH setting (see <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5)).</para>
2004-02-14 19:06:39 +01:00
2004-10-23 19:27:42 +02:00
<para > INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
directives are ignored with a warning message.</para>
2004-02-14 19:06:39 +01:00
2011-01-16 00:43:45 +01:00
<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>
2011-01-16 00:56:20 +01:00
<para > When used in these scripts, the INCLUDEd files are copied into the
2011-01-16 00:43:45 +01:00
compiled firewall script.</para>
2007-02-09 18:03:55 +01:00
<caution >
2011-01-16 00:43:45 +01:00
<para > Prior to Shorewall 4.4.17, if you are using <ulink
2011-10-01 18:56:25 +02:00
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
2011-01-16 00:43:45 +01:00
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
2007-02-09 18:03:55 +01:00
class="directory">/etc/shorewall-lite/</filename> directory.</para>
2009-02-28 04:45:43 +01:00
<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
2007-02-09 18:03:55 +01:00
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
2011-01-09 19:12:36 +01:00
<filename > params</filename> file. Note that with Shorewall 4.4.17 and
2011-01-26 18:08:48 +01:00
later:</para>
2011-01-16 00:56:20 +01:00
<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>
2007-02-09 18:03:55 +01:00
</caution>
2007-06-28 17:09:37 +02:00
<example id= "include" >
2004-02-14 19:06:39 +01:00
<title > Use of INCLUDE</title>
<programlisting > shorewall/params.mgmt:
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
2004-02-14 19:06:39 +01:00
2008-01-09 16:52:02 +01:00
</programlisting>
2008-02-29 22:56:25 +01:00
2009-02-28 04:45:43 +01:00
<para > You may include multiple files in one command using an <link
linkend="Embedded">embedded shell command</link> .</para>
2008-02-29 22:56:25 +01:00
<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
2008-02-29 23:11:46 +01:00
SHELL cat /etc/shorewall/rules.d/*.rules</programlisting> </para>
2011-04-03 18:56:30 +02:00
<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>
2004-02-14 19:06:39 +01:00
</example>
</section>
2011-05-22 17:59:05 +02:00
<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>
2008-11-09 21:14:58 +01:00
<section id= "Variables" >
<title > Using Shell Variables</title>
<para > You may use the <filename > /etc/shorewall/params</filename> file to
2010-05-31 19:25:53 +02:00
set shell variables that you can then use in the other configuration
files.</para>
2008-11-09 21:14:58 +01:00
<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>
2010-02-22 17:36:31 +01:00
<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>
2010-02-19 17:12:56 +01:00
<simplelist >
2010-02-22 17:36:31 +01:00
<member > <emphasis role= "bold" > Any option from <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>
(5)</emphasis> </member>
2010-02-22 00:14:40 +01:00
2010-02-23 16:18:54 +01:00
<member > <emphasis role= "bold" > COMMAND</emphasis> </member>
2010-02-22 17:36:31 +01:00
<member > <emphasis role= "bold" > CONFDIR</emphasis> </member>
2010-02-19 17:12:56 +01:00
<member > DEBUG</member>
2010-02-25 21:37:22 +01:00
<member > ECHO_E</member>
<member > ECHO_N</member>
2010-02-19 17:12:56 +01:00
<member > EXPORT</member>
<member > FAST</member>
2010-03-03 20:46:23 +01:00
<member > FILEMODE</member>
2010-03-02 20:59:38 +01:00
<member > HOSTNAME</member>
2010-02-19 17:12:56 +01:00
<member > IPT_OPTIONS</member>
2010-03-03 19:28:09 +01:00
<member > NOROUTES</member>
2010-02-19 17:12:56 +01:00
2010-02-22 00:14:40 +01:00
<member > PREVIEW</member>
2010-03-02 21:34:36 +01:00
<member > PRODUCT</member>
2010-02-22 00:14:40 +01:00
2010-02-19 17:12:56 +01:00
<member > PROFILE</member>
<member > PURGE</member>
2010-03-03 19:28:09 +01:00
<member > RECOVERING</member>
2010-02-21 17:34:21 +01:00
2010-02-26 17:35:50 +01:00
<member > RESTOREPATH</member>
2010-02-19 17:12:56 +01:00
2010-02-25 21:37:22 +01:00
<member > RING_BELL</member>
2010-02-22 17:36:31 +01:00
<member > <emphasis role= "bold" > SHAREDIR</emphasis> </member>
2010-02-22 00:14:40 +01:00
2010-02-23 15:57:29 +01:00
<member > <emphasis role= "bold" > Any name beginning with SHOREWALL_ or
SW_</emphasis> </member>
2010-02-19 17:12:56 +01:00
2010-03-02 16:37:30 +01:00
<member > STOPPING</member>
2010-02-19 17:12:56 +01:00
<member > TEST</member>
2010-03-03 19:28:09 +01:00
<member > TIMESTAMP</member>
2010-02-21 17:34:21 +01:00
2010-02-19 17:12:56 +01:00
<member > USE_VERBOSITY</member>
2010-02-22 17:36:31 +01:00
<member > <emphasis role= "bold" > VARDIR</emphasis> </member>
2010-02-22 00:14:40 +01:00
2010-03-01 02:58:01 +01:00
<member > VERBOSE</member>
2010-02-19 17:12:56 +01:00
<member > VERBOSE_OFFSET</member>
2010-03-02 17:18:01 +01:00
<member > VERSION</member>
2010-02-19 17:12:56 +01:00
</simplelist>
2008-11-09 21:14:58 +01:00
<para > Example:</para>
<blockquote >
<programlisting >
NET_IF=eth0
NET_BCAST=130.252.100.255
2009-06-05 19:51:30 +02:00
NET_OPTIONS=routefilter,routefilter
2008-11-09 21:14:58 +01:00
net $NET_IF $NET_BCAST $NET_OPTIONS
2009-06-05 19:51:30 +02:00
net eth0 130.252.100.255 routefilter,routefilter
2008-11-09 21:14:58 +01:00
</programlisting>
</blockquote>
<para > Variables may be used anywhere in the other configuration
files.<note >
2009-02-28 04:45:43 +01:00
<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>
2008-11-09 21:14:58 +01:00
<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 >
2010-07-24 16:09:02 +02:00
<para > Should not depend on where the code is called from.</para>
2008-11-09 21:14:58 +01:00
</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
2009-05-30 17:34:34 +02:00
run-time. If you have set EXPORTPARAMS=No in
<filename > shorewall.conf</filename> , then the
2008-11-09 21:14:58 +01:00
<filename > <filename > params</filename> </filename> file is only
2011-01-09 19:12:36 +01:00
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>
2008-11-09 21:14:58 +01:00
</listitem>
<listitem >
2011-10-01 18:56:25 +02:00
<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>
2008-11-09 21:14:58 +01:00
<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>
2011-01-26 18:08:48 +01:00
<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>
2008-11-09 21:14:58 +01:00
</listitem>
</orderedlist>
2011-01-26 18:08:48 +01:00
<para id= "Rvariables" > Given that shell variables are expanded at compile
time, there is no way to cause such variables to be expended at run time.
Prior to Shorewall 4.4.17, this made it difficult (to impossible) to
include dynamic IP addresses in a <ulink
2011-09-28 03:13:57 +02:00
url="Shorewall-Lite.html">Shorewall-lite</ulink> configuration.</para>
2011-01-26 18:08:48 +01:00
<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 > 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>
2012-02-23 22:36:00 +01:00
<listitem >
<para > <ulink
url="manpages/shorewall-nat.html">shorewall-nat</ulink> (5)</para>
</listitem>
2011-01-26 18:08:48 +01:00
<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
2012-02-24 18:02:04 +01:00
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>
2011-12-17 16:40:43 +01:00
2012-02-23 22:36:00 +01:00
<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
2012-02-24 18:02:04 +01:00
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>
2012-02-23 22:36:00 +01:00
<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>
2012-02-24 18:02:04 +01:00
<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>
2011-12-17 16:40:43 +01:00
<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
2012-02-23 22:36:00 +01:00
shell variable will be empty.</para>
2011-12-17 16:40:43 +01:00
</note>
<note >
<para > Options that were not set in shorewall.conf will expand to their
default value.</para>
</note>
2008-11-09 21:14:58 +01:00
</section>
2007-10-29 20:13:04 +01:00
<section id= "Embedded" >
2007-11-29 01:56:29 +01:00
<title > Embedded Shell and Perl</title>
2007-10-28 00:34:18 +02:00
<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
2009-02-28 04:45:43 +01:00
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>
2007-10-28 00:34:18 +02:00
2009-10-21 18:39:50 +02:00
<para > While inline scripts may be written in either Shell or Perl, those
2012-03-13 20:27:04 +01:00
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>
2007-10-28 00:34:18 +02:00
2007-10-29 20:13:04 +01:00
<para > Embedded scripts can be either single-line or multi-line. Single
line scripts take one of the following forms:</para>
2007-10-28 00:34:18 +02:00
<itemizedlist >
<listitem >
<para > <emphasis role= "bold" > PERL</emphasis> < <emphasis > perl
script</emphasis> > </para>
</listitem>
<listitem >
<para > <emphasis role= "bold" > SHELL</emphasis> < <emphasis > shell
script</emphasis> > </para>
</listitem>
</itemizedlist>
<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>
2009-10-21 18:39:50 +02:00
<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>
2007-10-28 00:34:18 +02:00
<programlisting > package Shorewall::User;
2011-12-17 16:40:43 +01:00
use Shorewall::Config ( qw/shorewall/ );</programlisting>
2007-10-28 00:34:18 +02:00
2009-10-21 18:39:50 +02:00
<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>
2007-10-28 00:34:18 +02:00
<orderedlist >
<listitem >
<para > Compile-time extension scripts are also implicitly prefixed by
"package Shorewall::User;".</para>
</listitem>
<listitem >
2009-02-28 04:45:43 +01:00
<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>
2007-10-28 00:34:18 +02:00
</listitem>
2007-12-02 02:45:42 +01:00
<listitem >
2009-02-28 04:45:43 +01:00
<para > <ulink url= "ManualChains.html" > Manual Chains</ulink> may be
added in the <emphasis role= "bold" > compile</emphasis> extension
script..</para>
2007-12-02 02:45:42 +01:00
</listitem>
2007-10-28 00:34:18 +02:00
</orderedlist>
<para > Multi-line scripts use one of the following forms:<programlisting > <emphasis
role="bold">BEGIN SHELL</emphasis>
2007-10-28 00:51:16 +02:00
< <emphasis > shell script</emphasis> >
2007-10-28 00:40:44 +02:00
<emphasis role= "bold" > END</emphasis> [ <emphasis role= "bold" > SHELL</emphasis> ]</programlisting> <programlisting > <emphasis
2007-10-28 00:34:18 +02:00
role="bold">BEGIN PERL</emphasis> [;]
< <emphasis > perl script</emphasis> >
<emphasis role= "bold" > END</emphasis> [ <emphasis role= "bold" > PERL</emphasis> ] [<emphasis
role="bold">;</emphasis> ]</programlisting> </para>
2007-11-29 00:11:07 +01:00
<para > <emphasis role= "bold" > Note: </emphasis> The '[' and ']' above are
meta-characters which indicate that what they enclose is optional and may
2010-02-26 01:35:19 +01:00
be omitted. So you may follow PERL with a semicolon ( ';') or you may omit
2007-11-29 00:11:07 +01:00
the semicolon.</para>
2007-10-28 00:34:18 +02:00
</section>
2004-02-14 19:06:39 +01:00
<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
2004-10-23 19:27:42 +02:00
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>
2004-02-14 19:06:39 +01:00
</caution>
2005-08-31 21:06:30 +02:00
<para > Host addresses in Shorewall configuration files may be specified as
either IP addresses or DNS Names.</para>
2004-02-14 19:06:39 +01:00
2004-10-23 19:27:42 +02:00
<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
2008-10-05 23:45:05 +02:00
the firewall has started have absolutely no effect on the firewall's rule
set.</para>
2004-02-14 19:06:39 +01:00
2008-11-09 21:14:58 +01:00
<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)
2009-03-15 21:46:56 +01:00
POP(ACCEPT) loc net:pop.gmail.com</programlisting>
2008-11-09 21:14:58 +01:00
2004-02-14 19:06:39 +01:00
<para > If your firewall rules include DNS names then:</para>
<itemizedlist >
<listitem >
<para > If your <filename > /etc/resolv.conf </filename> is wrong then your
2004-10-23 19:27:42 +02:00
firewall won't start.</para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
<para > If your <filename > /etc/nsswitch.conf</filename> is wrong then
2004-10-23 19:27:42 +02:00
your firewall won't start.</para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
2004-10-23 19:27:42 +02:00
<para > If your Name Server(s) is(are) down then your firewall won't
2004-02-14 19:06:39 +01:00
start.</para>
</listitem>
<listitem >
<para > If your startup scripts try to start your firewall before
2004-10-23 19:27:42 +02:00
starting your DNS server then your firewall won't start.</para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
2004-10-23 19:27:42 +02:00
<para > Factors totally outside your control (your ISP's router is down
for example), can prevent your firewall from starting.</para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
<para > You must bring up your network interfaces prior to starting your
firewall.</para>
</listitem>
</itemizedlist>
2005-05-28 03:46:19 +02:00
<para > Each DNS name must be fully qualified and include a minimum of two
2004-02-14 19:06:39 +01:00
periods (although one may be trailing). This restriction is imposed by
Shorewall to insure backward compatibility with existing configuration
files.</para>
2007-06-28 17:09:37 +02:00
<example id= "validdns" >
2004-02-14 19:06:39 +01:00
<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>
2007-06-28 17:09:37 +02:00
<example id= "invaliddns" >
2004-02-14 19:06:39 +01:00
<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 >
2004-10-23 19:27:42 +02:00
<para > The server address in a DNAT rule (/etc/shorewall/rules
file)</para>
2004-02-14 19:06:39 +01:00
</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>
2004-10-23 19:27:42 +02:00
<para > These restrictions are imposed by Netfilter and not by
Shorewall.</para>
2004-02-14 19:06:39 +01:00
</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 >
2009-06-05 19:51:30 +02:00
<para > Must not have any embedded white space.<programlisting > Valid: routefilter,dhcp,arpfilter
Invalid: routefilter, </programlisting> </para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
<para > If you use line continuation to break a comma-separated list,
2009-05-30 17:34:34 +02:00
the comma must be the last thing on the continued line before '\'
unless the continuation line has no leading white space.</para>
2004-02-14 19:06:39 +01:00
</listitem>
<listitem >
2004-10-23 19:27:42 +02:00
<para > Entries in a comma-separated list may appear in any
order.</para>
2004-02-14 19:06:39 +01:00
</listitem>
</itemizedlist>
</section>
2005-08-31 21:06:30 +02:00
<section id= "Compliment" >
2011-04-03 18:56:30 +02:00
<title > Complementing an Address, Subnet, Protocol or Port List</title>
2005-08-31 21:06:30 +02:00
<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>
2011-04-03 18:56:30 +02:00
<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>
2005-08-31 21:06:30 +02:00
</section>
2005-08-31 20:58:40 +02:00
<section id= "Exclusion" >
<title > Exclusion Lists</title>
2009-02-28 04:45:43 +01:00
<para > Where a comma-separated list of addresses is accepted, an
2005-08-31 20:58:40 +02:00
<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>
2005-04-07 18:35:59 +02:00
<section id= "IPRanges" >
2004-10-23 19:27:42 +02:00
<title > IP Address Ranges</title>
2005-08-31 21:06:30 +02:00
<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>
2004-10-23 19:27:42 +02:00
<para > To see if your kernel and iptables have the required support, use
2005-08-31 21:06:30 +02:00
the <command > shorewall show capabilities</command> command:</para>
2004-10-23 19:27:42 +02:00
2005-08-31 21:06:30 +02:00
<programlisting > > ~ <command > shorewall show capabilities</command>
2004-10-23 19:27:42 +02:00
...
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
2009-11-05 20:58:54 +01:00
<emphasis role= "bold" > IP range Match: Available < --------------</emphasis> </programlisting>
2004-10-23 19:27:42 +02:00
</section>
2004-02-14 19:06:39 +01:00
<section id= "Ports" >
2007-06-26 01:37:55 +02:00
<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 >
2009-02-28 04:45:43 +01:00
<para > The rules compiler translates protocol names to protocol numbers
and service names to port numbers itself.</para>
2007-06-26 01:37:55 +02:00
</note> </para>
2009-02-04 00:56:17 +01:00
<para > Also, unless otherwise documented, a protocol number/name can be
2009-02-28 04:45:43 +01:00
preceded by '!' to specify "All protocols except this one" (e.g.,
"!tcp").</para>
2004-02-14 19:06:39 +01:00
</section>
2009-11-05 20:58:54 +01:00
<section id= "ICMP" >
2009-11-05 20:44:40 +01:00
<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
2009-11-11 20:29:21 +01:00
separated by a slash (e.g., 3/4) or you may use a type name.</para>
2009-11-05 20:44:40 +01:00
<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>
2011-04-03 18:56:30 +02:00
<para > Shorewall 4.4 does not accept lists if ICMP (ICMP6) types prior to
Shorewall 4.4.19.</para>
2009-11-05 20:44:40 +01:00
</section>
2004-02-14 19:06:39 +01:00
<section id= "Ranges" >
<title > Port Ranges</title>
<para > If you need to specify a range of ports, the proper syntax is
2004-10-23 19:27:42 +02:00
< low port number> :< high port number> . For example, if you want
to forward the range of tcp ports 4000 through 4100 to local host
2004-02-14 19:06:39 +01:00
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 4000:4100</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>
2009-02-04 00:56:17 +01:00
<para > Also, unless otherwise documented, a port range can be preceded by
'!' to specify "All ports except those in this range" (e.g.,
2009-02-28 04:45:43 +01:00
"!4000:4100").</para>
2004-02-14 19:06:39 +01:00
</section>
2007-06-28 17:09:37 +02:00
<section id= "Portlists" >
2005-03-05 17:53:54 +01:00
<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.
2009-06-28 17:11:27 +02:00
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>
2007-06-26 01:37:55 +02:00
2009-02-04 00:56:17 +01:00
<para > Also, unless otherwise documented, a port list can be preceded by
2009-02-28 04:45:43 +01:00
'!' to specify "All ports except these" (e.g., "!80,443").</para>
2009-06-28 17:11:27 +02:00
2009-11-03 20:36:32 +01:00
<para > Prior to Shorewall 4.4.4, port lists appearing in the <ulink
2010-02-14 17:53:58 +01:00
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>
2005-03-05 17:53:54 +01:00
</section>
2004-02-14 19:06:39 +01:00
<section id= "MAC" >
<title > Using MAC Addresses</title>
<para > Media Access Control (MAC) addresses can be used to specify packet
2004-05-09 00:31:54 +02:00
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>
2004-02-14 19:06:39 +01:00
<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>
2007-06-28 17:09:37 +02:00
<example id= "mac" >
2004-03-17 16:03:46 +01:00
<title > MAC Address of an Ethernet Controller</title>
2004-02-14 19:06:39 +01:00
2008-01-09 17:32:36 +01:00
<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>
2004-02-14 19:06:39 +01:00
</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
2004-10-23 19:27:42 +02:00
the example above would be written <emphasis
role="bold">~02-00-08-E3-FA-55</emphasis> .</para>
2004-02-14 19:06:39 +01:00
<note >
<para > It is not necessary to use the special Shorewall notation in the
2004-10-23 19:27:42 +02:00
<filename > <ulink
url="MAC_Validation.html">/etc/shorewall/maclist</ulink> </filename>
2004-02-14 19:06:39 +01:00
file.</para>
</note>
</section>
2010-02-14 17:53:58 +01:00
<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
2010-02-19 17:12:56 +01:00
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>
2010-02-14 17:53:58 +01:00
<simplelist >
<member > LOGRATE=10/minute</member>
<member > LOGBURST=5</member>
</simplelist>
2010-02-19 17:12:56 +01:00
<para > For each logging rule, the first time the rule is reached, the
2010-02-14 17:53:58 +01:00
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
2010-04-16 15:24:35 +02:00
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>
2011-07-08 16:08:39 +02:00
<note >
<para > The LOGRATE and LOGBURST options are deprecated in favor of
LOGLIMIT.</para>
</note>
2011-09-23 21:33:55 +02:00
<para > Shorewall also supports per-IP rate limiting.</para>
2011-07-08 16:08:39 +02:00
<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>
2010-02-14 17:53:58 +01:00
</section>
2011-09-23 23:44:20 +02:00
<section id= "Switches" >
2011-09-23 21:33:55 +02:00
<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
2011-09-23 23:44:20 +02:00
<firstterm > switch.</firstterm> Each switch that is initially in the
<emphasis role= "bold" > off</emphasis> position. You can turn on the switch
named <emphasis > switch1</emphasis> by:</para>
2011-09-23 21:33:55 +02:00
<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
2011-09-23 23:44:20 +02:00
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
2011-09-24 16:34:58 +02:00
role="bold">off</emphasis> . Switch settings are retained over
<command > shorewall restart</command> .</para>
2011-09-23 21:33:55 +02:00
2011-09-24 16:34:58 +02:00
<para > Shorewall requires that switch names:</para>
2011-09-23 21:33:55 +02:00
2011-09-24 16:34:58 +02:00
<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>
2011-09-23 23:44:20 +02:00
<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 - - - - - - - - primary_down </programlisting>
</blockquote>
2011-09-23 21:33:55 +02:00
</section>
2009-11-11 20:29:21 +01:00
<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
2010-08-14 05:27:14 +02:00
url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink>
2009-11-11 20:29:21 +01:00
(5).</para>
<para > Here is an example:</para>
<programlisting > #ZONE INTERFACE BROADCAST OPTIONS
net COM_IF detect dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,physical=eth0
net EXT_IF detect dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,physical=eth2
loc INT_IF detect dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,physical=eth1
dmz VPS_IF detect logmartians=1,routefilter=0,routeback,physical=venet0
loc TUN_IF detect physical=tun+</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
COM_IF 0.0.0.0/0
EXT_IF !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 EXT_IF 206.124.146.254 loose,fallback INT_IF,VPS_IF,TUN_IF
Comcast 2 0x20000 main COM_IF detect balance INT_IF,VPS_IF,TUN_IF</programlisting>
<para > Note in particular that Shorewall translates TUN_IF to <filename
class="devicefile">tun*</filename> in the COPY column.</para>
</section>
2010-11-10 23:38:55 +01:00
<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>
2010-12-09 19:04:52 +01:00
<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 required 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>
2004-02-14 19:06:39 +01:00
<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
2007-08-31 17:24:45 +02:00
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>
2004-02-14 19:06:39 +01:00
<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 >
2005-04-07 18:35:59 +02:00
<para > specifying the separate directory in a <command > shorewall
start</command> or <command > shorewall restart</command> command (e.g.,
2005-08-31 21:06:30 +02:00
<command > shorewall restart /etc/testconfig</command> )</para>
2004-02-14 19:06:39 +01:00
</listitem>
</orderedlist>
</section>
2005-12-09 19:40:13 +01:00
2007-06-28 17:09:37 +02:00
<section id= "Save" >
2005-12-09 19:40:13 +01:00
<title > Saved Configurations</title>
<para > Shorewall allows you to <firstterm > save</firstterm> the
2005-12-09 19:53:23 +01:00
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
2005-12-09 19:40:13 +01:00
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
2005-12-09 19:53:23 +01:00
file name in the command. For example, <command > shorewall restore
standard</command> will re-install the configuration saved in
2005-12-09 19:40:13 +01:00
<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'
2005-12-09 19:53:23 +01:00
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>
2005-12-09 19:40:13 +01:00
2005-12-09 20:30:51 +01:00
<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>
2005-12-09 19:40:13 +01:00
</section>
2008-07-04 17:11:51 +02:00
</article>
