holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity
a77c49a02e
shorewall_code/Shorewall-docs2/Documentation.xml
teastep 1d62d894ef Back out Crossbeam documentaiton Changes 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@2221 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
2005-06-04 00:48:08 +00:00

4293 lines
166 KiB
XML
Raw Blame History

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article id="Documentation">
<!--$Id$-->
<articleinfo>
<title>Shorewall 2.x Reference</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate>2005-06-01</pubdate>
<copyright>
<year>2001-2005</year>
<holder>Thomas M. Eastep</holder>
</copyright>
<legalnotice>
<para>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.2 or any later version published by the Free Software Foundation; with
no Invariant Sections, with no Front-Cover, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
</legalnotice>
<abstract>
<para>This documentation is intended primarily for reference.
Step-by-step instructions for configuring Shorewall in common setups may
be found in the <ulink url="shorewall_quickstart_guide.htm">QuickStart
Guides</ulink>.</para>
</abstract>
</articleinfo>
<section>
<title>Components</title>
<para>Shorewall consists of the following components:</para>
<variablelist>
<varlistentry>
<term><link linkend="Variables">params</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> that can be used to
establish the values of shell variables for use in other
files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Conf">shorewall.conf</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> that is used to set
several firewall parameters.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Zones">zones</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> that defines a network
partitioning into <quote>zones</quote></para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Policy">policy</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> that establishes overall
firewall policy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Rules">rules</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to express
firewall rules that are exceptions to the high-level policies
established in /etc/shorewall/policy.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Blacklist">blacklist</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to list
blacklisted IP/subnet/MAC addresses.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="ECN">ecn</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to selectively
disable Explicit Congestion Notification (ECN - RFC 3168).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>functions</term>
<listitem>
<para>a set of shell functions used by both the firewall and
shorewall shell programs. Installed in <filename
class="directory">/usr/share/shorewall</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="modules">modules</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and that specifies
kernel modules and their parameters. Shorewall will automatically
load the modules specified in this file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="TOS">tos</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> that is used to specify
how the Type of Service (TOS) field in packets is to be set.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>init.sh and init.debian.sh</term>
<listitem>
<para>a shell script installed in <filename
class="directory">/etc/init.d </filename>to automatically start
Shorewall during boot. The particular script installed depends on
which distribution you are running.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Interfaces">interfaces</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to describe the
interfaces on the firewall system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Hosts">hosts</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to describe
individual hosts or subnetworks in zones.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Ipsec">ipsec</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to describe
ipsec policies associated with zones.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Maclist">maclist</link></term>
<listitem>
<para>a parameter file installed in <filename
class="directory">/etc/shorewall</filename> and used to verify the
MAC address (and possibly also the IP address(es)) of
devices.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Masq">masq</link></term>
<listitem>
<para>This file also describes IP masquerading under Shorewall and
is installed in <filename
class="directory">/etc/shorewall</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>firewall</term>
<listitem>
<para>a shell program that reads the configuration files in
<filename class="directory">/etc/shorewall</filename> and configures
your firewall. This file is installed in <filename
class="directory">/usr/share/shorewall</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="NAT">nat</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/etc/shorewall</filename> used to define <link
linkend="NAT">one-to-one NAT</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="ProxyArp">proxyarp</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/etc/shorewall</filename> used to define <link
linkend="ProxyArp">Proxy Arp</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="rfc1918">rfc1918</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/usr/share/shorewall</filename> used to define the
treatment of packets under the <link linkend="Interfaces">norfc1918
interface option</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Bogons">bogons</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/usr/share/shorewall</filename> used to define the
treatment of packets under the <link linkend="Interfaces">nobogons
interface option</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Routestopped">routestopped</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/etc/shorewall</filename> used to define those
hosts that can access the firewall when Shorewall is stopped.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="traffic_shaping.htm#tcrules">tcrules</ulink></term>
<listitem>
<para>a parameter file in <filename class="directory">/etc/shorewall
</filename>used to define rules for classifying packets for <ulink
url="traffic_shaping.htm">Traffic Shaping/Control</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><link linkend="Tunnels">tunnels</link></term>
<listitem>
<para>a parameter file in <filename
class="directory">/etc/shorewall</filename> used to define IPSec
tunnels.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>shorewall</term>
<listitem>
<para>a shell program (requiring a Bourne shell or derivative) used
to control and monitor the firewall. This should be placed in
<filename class="directory">/sbin</filename> or in <filename
class="directory">/usr/sbin</filename> (the install.sh script and
the rpm install this file in <filename
class="directory">/sbin</filename>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="Accounting.html">accounting</ulink></term>
<listitem>
<para>a parameter file in <filename
class="directory">/etc/shorewall</filename> used to define traffic
accounting rules. This file was added in version 1.4.7.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>version</term>
<listitem>
<para>a file created in <filename
class="directory">/usr/share/shorewall</filename> that describes the
version of Shorewall installed on your system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="Actions.html">actions and
action.template</ulink></term>
<listitem>
<para>files in <filename class="directory">/etc/shorewall</filename>
and <filename class="directory">/usr/share/shorewall</filename>
respectively that allow you to define your own actions for rules in
<filename><link
linkend="Rules">/etc/shorewall/rules</link></filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>actions.std and action.*</term>
<listitem>
<para>files in <filename
class="directory">/usr/share/shorewall</filename> that define the
actions included as a standard part of Shorewall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="Shorewall_and_Routing.html">providers</ulink></term>
<listitem>
<para>file in /etc/shorewall that is used to define multiple
Internet Service Providers and load-balancing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="Shorewall_and_Routing.html">routes</ulink></term>
<listitem>
<para>file in /etc/shorewall that is used to interface to the
experimental ROUTE target from Netfilter patch-o-matic-ng.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="Variables" xreflabel="/etc/shorewall/params">
<title>/etc/shorewall/params</title>
<para>You may use the file <filename>/etc/shorewall/params</filename> file
to set shell variables that you can then use in some of the other
configuration files.</para>
<para>It is suggested that variable names begin with an upper case letter
to distinguish them from variables used internally within the Shorewall
programs</para>
<example>
<title>shell variables</title>
<programlisting>NET_IF=eth0 NET_BCAST=130.252.100.255
NET_OPTIONS=blacklist,norfc1918</programlisting>
</example>
<example>
<title>/etc/shorewall/interfaces record</title>
<programlisting>net $NET_IF $NET_BCAST $NET_OPTIONS</programlisting>
</example>
<para>The result will be the same as if the record had been written</para>
<programlisting>net eth0 130.252.100.255 blacklist,norfc1918</programlisting>
<para>Variables may be used anywhere in the other configuration
files.</para>
</section>
<section id="Zones" xreflabel="/etc/shorewall/zones">
<title>/etc/shorewall/zones</title>
<para>This file is used to define the network zones. There is one entry in
<filename>/etc/shorewall/zones</filename> for each zone; Columns in an
entry are:</para>
<variablelist>
<varlistentry>
<term>ZONE</term>
<listitem>
<para>short name for the zone. The name should be 5 characters or
less in length (4 characters or less if you are running Shorewall
1.4.4 or later) and consist of lower-case letters or numbers. Short
names must begin with a letter and the name assigned to the firewall
is reserved for use by Shorewall itself. Note that the output
produced by iptables is much easier to read if you select short
names that are three characters or less in length. The name
<quote>all</quote> may not be used as a zone name nor may the zone
name assigned to the firewall itself via the FW variable in <xref
linkend="Conf" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DISPLAY</term>
<listitem>
<para>The name of the zone as displayed during Shorewall
startup.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>COMMENTS</term>
<listitem>
<para>Any comments that you want to make about the zone. Shorewall
ignores these comments.</para>
</listitem>
</varlistentry>
</variablelist>
<programlisting>#ZONE DISPLAY COMMENTS
net Net Internet
loc Local Local networks
dmz DMZ Demilitarized zone</programlisting>
<para>You may add, delete and modify entries in the
<filename>/etc/shorewall/zones</filename> file as desired so long as you
have at least one zone defined.</para>
<warning>
<para>If you rename or delete a zone, you should perform
<quote><command>shorewall stop; shorewall start</command></quote> to
install the change rather than <quote><command>shorewall
restart</command></quote>.</para>
</warning>
<warning>
<para>The order of entries in the
<filename>/etc/shorewall/zones</filename> file is significant <link
linkend="Nested">in some cases</link>.</para>
</warning>
</section>
<section id="Interfaces" xreflabel="/etc/shorewall/interfaces">
<title>/etc/shorewall/interfaces</title>
<para>This file is used to tell the firewall which of your firewall's
network interfaces are connected to which zone. There will be one entry in
/etc/shorewall/interfaces for each of your interfaces. Columns in an entry
are:</para>
<variablelist>
<varlistentry>
<term>ZONE</term>
<listitem>
<para>A zone defined in the <xref linkend="Zones" /> file or
<quote>-</quote>. If you specify <quote>-</quote>, you must use the
<xref linkend="Hosts" /> file to define the zones accessed via this
interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>the name of the interface (examples: eth0, ppp0, ipsec+). Each
interface can be listed on only one record in this file.</para>
<note>
<para>You do not need to include the loopback interface (lo) in
this file.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>BROADCAST</term>
<listitem>
<para>the broadcast address(es) for the sub-network(s) attached to
the interface. This should be left empty for P-T-P interfaces (ppp*,
ippp*); if you need to specify options for such an interface, enter
<quote>-</quote> in this column. If you supply the special value
<quote>detect</quote> in this column, the firewall will
automatically determine the broadcast address. In order to use
<quote>detect</quote>:</para>
<itemizedlist>
<listitem>
<para>the interface must be up before you start your
firewall</para>
</listitem>
<listitem>
<para>the interface must only be attached to a single
sub-network (i.e., there must have a single broadcast
address).</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>OPTIONS</term>
<listitem>
<para>a comma-separated list of options. Possible options
include:</para>
<variablelist>
<varlistentry>
<term>arp_filter</term>
<listitem>
<para>(Added in version 1.4.7) - This option causes
<filename>/proc/sys/net/ipv4/conf/&lt;interface&gt;/arp_filter</filename>
to be set with the result that this interface will only answer
ARP <quote>who-has</quote> requests from hosts that are routed
out of that interface. Setting this option facilitates testing
of your firewall where multiple firewall interfaces are
connected to the same HUB/Switch (all interface connected to
the single HUB/Switch should have this option specified). Note
that using such a configuration in a production environment is
strongly recommended against.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>newnotsyn</term>
<listitem>
<para>(Added in version 1.4.6) - This option overrides <link
linkend="Conf">NEWNOTSYN=No</link> for packets arriving on
this interface. In other words, packets coming in on this
interface are processed as if NEWNOTSYN=Yes had been specified
in <xref linkend="Conf" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>routeback</term>
<listitem>
<para>(Added in version 1.4.2) - This option causes Shorewall
to set up handling for routing packets that arrive on this
interface back out the same interface. If this option is
specified, the ZONE column may not contain
<quote>-</quote>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tcpflags</term>
<listitem>
<para>(added in version 1.3.11) - This option causes Shorewall
to make sanity checks on the header flags in TCP packets
arriving on this interface. Checks include Null flags,
SYN+FIN, SYN+RST and FIN+URG+PSH; these flag combinations are
typically used for <quote>silent</quote> port scans. Packets
failing these checks are logged according to the
TCP_FLAGS_LOG_LEVEL option in <xref linkend="Conf" /> and are
disposed of according to the TCP_FLAGS_DISPOSITION
option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>blacklist</term>
<listitem>
<para>This option causes incoming packets on this interface to
be checked against the <link
linkend="Blacklist">blacklist</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>dhcp</term>
<listitem>
<para>The interface is assigned an IP address via DHCP or is
used by a DHCP server running on the firewall. The firewall
will be configured to allow DHCP traffic to and from the
interface even when the firewall is stopped. You may also wish
to use this option if you have a static IP but you are on a
LAN segment that has a lot of Laptops that use DHCP and you
select the <emphasis role="bold">norfc1918</emphasis> option
(see below).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>norfc1918</term>
<listitem>
<para>Packets arriving on this interface and that have a
source or destination address that is reserved in RFC 1918
will be dropped after being optionally logged.</para>
<para>Prior to Shorewall 2.0.1, addresses blocked by the
standard <link linkend="rfc1918">rfc1918 file</link> include
those addresses reserved by RFC1918 plus other ranges reserved
by the IANA or by other RFCs. Beginning with Shorewall 2.0.1,
these additional addresses are covered by the <emphasis
role="bold">nobogons</emphasis> option below.</para>
<para>Beware that as IPv4 addresses become in increasingly
short supply, ISPs are beginning to use RFC 1918 addresses
within their own infrastructure. Also, many cable and DSL
<quote>modems</quote> have an RFC 1918 address that can be
used through a web browser for management and monitoring
functions. If you want to specify <emphasis
role="bold">norfc1918</emphasis> on your external interface
but need to allow access to certain addresses from the above
list, see <ulink url="FAQ.htm#faq14">FAQ 14</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nobogons (Added in Shorewall 2.0.1)</term>
<listitem>
<para>Packets arriving on this interface that have a source
address reserved by the IANA or by other RFCs (other than
1918) are dropped after being optionally logged. See the
/etc/shorewall/bogons file documentation below.</para>
<para>I personally recommend against using the nobogons
option. The IPV4 address space is being rapidly depleated so
the benefit of blocking traffic from unallocated address
ranges is minimal. Plus the rate at which address blocks are
being assigned causes your /etc/shorewall/bogons file to
become out of date with the result that legitimate traffic
gets blocked.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>routefilter</term>
<listitem>
<para>Invoke the Kernel's route filtering (anti-spoofing)
facility on this interface. The kernel will reject any packets
incoming on this interface that have a source address that
would be routed outbound through another interface on the
firewall.</para>
<warning>
<para>If you specify this option for an interface then the
interface must be up prior to starting the firewall.</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>proxyarp</term>
<listitem>
<para>(Added in version 1.3.5) - This option causes Shorewall
to set
/proc/sys/net/ipv4/conf/&lt;<emphasis>interface</emphasis>&gt;/proxy_arp
and is used when implementing Proxy ARP Sub-netting as
described at <ulink
url="http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/">http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/</ulink>.
Do <emphasis role="bold">not</emphasis> set this option if you
are implementing Proxy ARP through entries in <xref
linkend="ProxyArp" />.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>maclist</term>
<listitem>
<para>(Added in version 1.3.10) - If this option is specified,
all connection requests from this interface are subject to
<ulink url="MAC_Validation.html">MAC Verification</ulink>. May
only be specified for ethernet interfaces.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term>detectnets</term>
<listitem>
<para>(Added in version 1.4.10) - If this option is specified,
the zone named in the ZONE column will contain only the hosts
routed through the interface named in the INTERFACE column.
<emphasis role="bold">Do not set this option on your external
(Internet) interface!</emphasis> The interface must be in the
UP state when Shorewall is [re]started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nosmurfs</term>
<listitem>
<para>(Added in version 2.0.0) - If this option is specified,
incoming connection requests will be checked to ensure that
they do not have a broadcast or multicast address as their
source. Any such packets will be dropped after being
optionally logged according to the setting of SMURF_LOG_LEVEL
in <link
linkend="Conf">/etc/shorewall/shorewall.conf</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>logmartians</term>
<listitem>
<para>(Added in version 2.2.0) - If this option is specified,
the kernel's martian logging facility will be enabled on this
interface
(/proc/sys/net/ipv4/conf/&lt;<emphasis>interface</emphasis>&gt;/log_martians
will be set to 1). See also the LOG_MARTIANS option in <link
linkend="Conf">shorewall.conf</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>sourceroute</term>
<listitem>
<para>(Added in version 2.2.0) - If this option is not
specified for an interface, then source-routed packets will
not be accepted from that interface (sets
<filename>/proc/sys/net/ipv4/conf/&lt;interface&gt;</filename>
to 1).</para>
</listitem>
</varlistentry>
</variablelist>
<para>My recommendations concerning options:</para>
<itemizedlist>
<listitem>
<para>External Interface -- <emphasis
role="bold">tcpflags,blacklist,norfc1918,routefilter,nosmurfs,logmartians</emphasis></para>
</listitem>
<listitem>
<para>Wireless Interface -- <emphasis
role="bold">maclist,routefilter,tcpflags,detectnets,nosmurfs</emphasis></para>
</listitem>
<listitem>
<para>Use <emphasis role="bold">dhcp</emphasis> and <emphasis
role="bold">proxyarp</emphasis> when needed.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>You have a conventional firewall setup in which eth0 connects to
a Cable or DSL modem and eth1 connects to your local network and eth0
gets its IP address via DHCP. You want to check all packets entering
from the internet against the <link linkend="Blacklist">black
list</link>. Your /etc/shorewall/interfaces file would be as
follows:</title>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
net eth0 detect dhcp,norfc1918,blacklist</programlisting>
</example>
<example>
<title>You have a standalone dialup GNU/Linux System. Your
/etc/shorewall/interfaces file would be:</title>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
net ppp0</programlisting>
</example>
<example>
<title>You have local interface eth1 with two IP addresses -
192.168.1.1/24 and 192.168.12.1/24</title>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
loc eth1 192.168.1.255,192.168.12.255</programlisting>
</example>
</section>
<section id="Hosts" xreflabel="/etc/shorewall/hosts">
<title>/etc/shorewall/hosts Configuration</title>
<para>For most applications, specifying zones entirely in terms of network
interfaces is sufficient. There may be times though where you need to
define a zone to be a more general collection of hosts. This is the
purpose of the <filename>/etc/shorewall/hosts</filename> file.</para>
<warning>
<para>The only time that you need entries in
<filename>/etc/shorewall/hosts</filename> is where you have <ulink
url="Multiple_Zones.html">more than one zone connecting through a single
interface</ulink>.</para>
<para><emphasis role="bold">IF YOU DON'T HAVE THIS SITUATION THEN DON'T
TOUCH THIS FILE!!</emphasis></para>
</warning>
<para>Columns in this file are:</para>
<variablelist>
<varlistentry>
<term>ZONE</term>
<listitem>
<para>A zone defined in the <xref linkend="Zones" /> file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HOST(S)</term>
<listitem>
<para>The name of an interface defined in the <link
linkend="Interfaces">/etc/shorewall/interfaces</link> file followed
by a colon (":") and a comma-separated list whose elements are
either:</para>
<orderedlist>
<listitem>
<para>The IP address of a host</para>
</listitem>
<listitem>
<para>A subnetwork in the form
&lt;<emphasis>subnet-address</emphasis>&gt;/&lt;<emphasis>mask
width</emphasis>&gt;</para>
</listitem>
<listitem>
<para>A physical port name (Shorewall version 2.0.1 and later);
only allowed when the interface names a bridge created by the
<command>brctl addbr </command>command. This port must not be
defined in <filename>/etc/shorewall/interfaces</filename> and
may optionally followed by a colon (":") and a host or network
IP. See the <ulink url="bridge.html">bridging
documentation</ulink> for details.</para>
</listitem>
</orderedlist>
<warning>
<para>If you are running a version of Shorewall earlier than
1.4.6, only a single host/subnet address may be specified in an
entry in <filename>/etc/shorewall/hosts</filename>.</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>OPTIONS</term>
<listitem>
<para>A comma-separated list of option</para>
<variablelist>
<varlistentry>
<term>routeback</term>
<listitem>
<para>(Added in version 1.4.2) - This option causes Shorewall
to set up handling for routing packets sent by this host group
back back to the same group.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>maclist</term>
<listitem>
<para>Added in version 1.3.10. If specified, connection
requests from the hosts specified in this entry are subject to
<ulink url="MAC_Validation.html">MAC Verification</ulink>.
This option is only valid for ethernet interfaces.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tcpflags (Added in Shorewall 2.0.1)</term>
<listitem>
<para>(added in version 1.3.11) - This option causes Shorewall
to make sanity checks on the header flags in TCP packets
arriving from these hosts. Checks include Null flags, SYN+FIN,
SYN+RST and FIN+URG+PSH; these flag combinations are typically
used for <quote>silent</quote> port scans. Packets failing
these checks are logged according to the TCP_FLAGS_LOG_LEVEL
option in <xref linkend="Conf" /> and are disposed of
according to the TCP_FLAGS_DISPOSITION option.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>blacklist (Added in Shorewall 2.0.1 -- only makes sense
for bridge ports)</term>
<listitem>
<para>This option causes incoming packets on this port to be
checked against the <link
linkend="Blacklist">blacklist</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>norfc1918 (Added in Shorewall 2.0.1 -- only makes sense
for bridge ports)</term>
<listitem>
<para>Packets arriving on this port and that have a source
address that is reserved in RFC 1918 will be dropped after
being optionally logged as specified in the section of
RFC1918_LOG_LEVEL in shorewall.conf.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nobogons (Added in Shorewall 2.0.1 -- only makes sense for
bridge ports)</term>
<listitem>
<para>Packets arriving on this port that have a source address
reserved by the IANA or by other RFCs (other than 1918) are
dropped after being optionally logged. See the
/etc/shorewall/bogons file documentation below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>nosmurfs (Added in Shorewall 2.0.1 -- only makes sense for
bridge ports)</term>
<listitem>
<para>If this option is specified, incoming connection
requests will be checked to ensure that they do not have a
broadcast or multicast address as their source. Any such
packets will be dropped after being optionally logged
according to the setting of SMURF_LOG_LEVEL in <link
linkend="Conf">/etc/shorewall/shorewall.conf</link>.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>If you don't define any hosts for a zone, the hosts in the zone
default to i0:0.0.0.0/0 , i1:0.0.0.0/0, ... where i0, i1, ... are the
interfaces to the zone.</para>
<note>
<para>You probably DON'T want to specify any hosts for your internet
zone since the hosts that you specify will be the only ones that you
will be able to access without adding additional rules.</para>
</note>
<example>
<title>Your local interface is eth1 and you have two groups of local
hosts that you want to make into separate zones:</title>
<programlisting>192.168.1.0/25 192.168.1.128/25</programlisting>
<para>Your /etc/shorewall/interfaces file might look like:</para>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
net eth0 detect dhcp,norfc1918
- eth1 192.168.1.127,192.168.1.255</programlisting>
<para>The <quote>-</quote> in the ZONE column for eth1 tells Shorewall
that eth1 interfaces to multiple zones.</para>
<programlisting>#ZONE HOST(S) OPTIONS
loc1 eth1:192.168.1.0/25
loc2 eth1:192.168.1.128/25</programlisting>
</example>
<example>
<title>You have local interface eth1 with two IP addresses -
192.168.1.1/24 and 192.168.12.1/24</title>
<para>Your /etc/shorewall/interfaces file might look like:</para>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
net eth0 detect dhcp,norfc1918
- eth1 192.168.1.255,192.168.12.255</programlisting>
<para>Your /etc/shorewall/hosts file might look like:</para>
<programlisting>#ZONE HOST(S) OPTIONS
loc eth1:192.168.1.0/24
loc eth1:192.168.12.0/24</programlisting>
<para>If you are running Shorewall 1.4.6 or later, your hosts file may
look like:</para>
<programlisting>#ZONE HOST(S) OPTIONS
loc eth1:192.168.1.0/24,192.168.12.0/24</programlisting>
</example>
<section id="Nested">
<title>Nested and Overlapping Zones</title>
<para>The <filename>/etc/shorewall/interfaces</filename> and
<filename>/etc/shorewall/hosts</filename> file allow you to define
nested or overlapping zones. Such overlapping/nested zones are allowed
and Shorewall processes zones in the order that they appear in the
<filename>/etc/shorewall/zones</filename> file. So if you have nested
zones, you want the sub-zone to appear before the super-zone and in the
case of overlapping zones, the rules that will apply to hosts that
belong to both zones is determined by which zone appears first in
<filename>/etc/shorewall/zones</filename>.</para>
<para>Hosts that belong to more than one zone may be managed by the
rules of all of those zones. This is done through use of the special
<link linkend="CONTINUE">CONTINUE policy</link> described below.</para>
</section>
</section>
<section id="Policy" xreflabel="/etc/shorewall/policy">
<title>/etc/shorewall/policy Configuration</title>
<para>This file is used to describe the firewall policy regarding
establishment of connections. Connection establishment is described in
terms of <emphasis>clients</emphasis> who initiate connections and
<emphasis>servers</emphasis> who receive those connection requests.
Policies defined in <filename>/etc/shorewall/policy </filename>describe
which zones are allowed to establish connections with other zones.</para>
<para>Policies established in <filename>/etc/shorewall/policy
</filename>can be viewed as default policies. If no rule in
/etc/shorewall/rules applies to a particular connection request then the
policy from <filename>/etc/shorewall/policy</filename> is applied.</para>
<para>Five policies are defined:</para>
<variablelist>
<varlistentry>
<term>ACCEPT</term>
<listitem>
<para>The connection is allowed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DROP</term>
<listitem>
<para>The connection request is ignored.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REJECT</term>
<listitem>
<para>The connection request is rejected with an RST (TCP) or an
ICMP destination-unreachable packet being returned to the
client.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>QUEUE</term>
<listitem>
<para>Send the connection request to a user-space process via the
iptables QUEUE target (useful when you are using
Snort-inline).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CONTINUE</term>
<listitem>
<para>The connection is neither ACCEPTed, DROPped nor REJECTed.
CONTINUE may be used when one or both of the zones named in the
entry are sub-zones of or intersect with another zone. For more
information, see below.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NONE</term>
<listitem>
<para>(Added in version 1.4.1) - Shorewall should not set up any
infrastructure for handling traffic from the SOURCE zone to the DEST
zone. When this policy is specified, the <emphasis role="bold">LOG
LEVEL</emphasis> and <emphasis role="bold">BURST:LIMIT</emphasis>
columns must be left blank.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For each policy specified in /etc/shorewall/policy, you can indicate
that you want a message sent to your system log each time that the policy
is applied.</para>
<para>Entries in /etc/shorewall/policy have four columns as
follows:</para>
<variablelist>
<varlistentry>
<term>SOURCE</term>
<listitem>
<para>The name of a client zone (a zone defined in the <xref
linkend="Zones" /> file , the <link linkend="Conf">name of the
firewall zone</link> or <quote>all</quote>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEST</term>
<listitem>
<para>The name of a destination zone (a zone defined in the <xref
linkend="Zones" /> file , the <link linkend="Conf">name of the
firewall zone</link> or <quote>all</quote>). Shorewall automatically
allows all traffic from the firewall to itself so the <link
linkend="Conf">name of the firewall zone</link> cannot appear in
both the SOURCE and DEST columns.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>POLICY</term>
<listitem>
<para>The default policy for connection requests from the SOURCE
zone to the DESTINATION zone.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOG LEVEL</term>
<listitem>
<para>Optional. If left empty, no log message is generated when the
policy is applied. Otherwise, this column should contain an integer
or name indicating a <ulink url="shorewall_logging.html">syslog
level</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LIMIT:BURST - optional</term>
<listitem>
<para>If left empty, TCP connection requests from the <emphasis
role="bold">SOURCE</emphasis> zone to the <emphasis
role="bold">DEST</emphasis> zone will not be rate-limited.
Otherwise, this column specifies the maximum rate at which TCP
connection requests will be accepted followed by a colon
(<quote>:</quote>) followed by the maximum burst size that will be
tolerated. Example: <emphasis role="bold">10/sec:40</emphasis>
specifies that the maximum rate of TCP connection requests allowed
will be 10 per second and a burst of 40 connections will be
tolerated. Connection requests in excess of these limits will be
dropped. See the <link linkend="Rules">rules file
documentation</link> for an explanation of how rate limiting
works.</para>
</listitem>
</varlistentry>
</variablelist>
<para>In the SOURCE and DEST columns, you can enter <quote>all</quote> to
indicate all zones.</para>
<para>The default <filename>/etc/shorewall/policy</filename> file is as
follows.</para>
<programlisting>#SOURCE DEST POLICY LOG LEVEL LIMIT:BURST
loc net ACCEPT
net all DROP info
all all REJECT info</programlisting>
<para>This table may be interpreted as follows:</para>
<itemizedlist>
<listitem>
<para>All connection requests from the local network to hosts on the
internet are accepted.</para>
</listitem>
<listitem>
<para>All connection requests originating from the internet are
ignored and logged at level KERNEL.INFO.</para>
</listitem>
<listitem>
<para>All other connection requests are rejected and logged.</para>
</listitem>
</itemizedlist>
<warning>
<para>The firewall script processes the
<filename>/etc/shorewall/policy</filename> file from top to bottom and
<emphasis role="bold">uses the first applicable policy that it
finds</emphasis>. For example, in the following policy file, the policy
for (loc, loc) connections would be ACCEPT as specified in the first
entry even though the third entry in the file specifies REJECT.</para>
<programlisting>#SOURCE DEST POLICY LOG LEVEL LIMIT:BURST
loc all ACCEPT
net all DROP info
loc loc REJECT info</programlisting>
</warning>
<section>
<title>Intra-Zone Traffic</title>
<para>Shorewall allows a zone to be associated with more than one
interface or with multiple networks that interface through a single
interface. Beginning with Shorewall 1.4.1, Shorewall will ACCEPT all
traffic from a zone to itself provided that there is no explicit policy
governing traffic from that zone to itself (an explicit policy does not
specify <quote>all</quote> in either the SOURCE or DEST column) and that
there are no rules concerning connections from that zone to itself. If
there is an explicit policy or if there are one or more rules, then
traffic within the zone is handled just like traffic between zones
is.</para>
<para>The idea is this:</para>
<orderedlist>
<listitem>
<para>A zone should be homogeneous with respect to security
requirements.</para>
</listitem>
<listitem>
<para>Traffic within a zone should not require rules or
policies.</para>
</listitem>
<listitem>
<para>Shorewall will not restrict traffic within a zone.</para>
</listitem>
</orderedlist>
<para>UNLESS the user defines the zone badly so that intra-zone rules
are required. In that case, Shorewall will not try to guess what the
user's intentions are and will treat traffic within the affected zone(s)
just like any other traffic.</para>
<para>Any time that you have multiple interfaces associated with a
single zone, you should ask yourself if you really want traffic routed
between those interfaces. Cases where you might not want that behavior
are:</para>
<orderedlist>
<listitem>
<para>Multiple <quote>net</quote> interfaces to different ISPs. You
don't want to route traffic from one ISP to the other through your
firewall.</para>
</listitem>
<listitem>
<para>Multiple VPN clients. You don't necessarily want them to all
be able to communicate between themselves using your
gateway/router.</para>
</listitem>
</orderedlist>
<para>Beginning with Shorewall 2.0.0, you can control the traffic from
the firewall to itself. As with any zone, fw-&gt;fw traffic is enabled
by default. It is not necessary to define the loopback interface (lo) in
<link linkend="Interfaces">/etc/shorewall/interfaces</link> in order to
define fw-&gt;fw rules or a fw-&gt;fw policy.</para>
<caution>
<para>So long as there are no intra-zone rules for a zone, all
intra-zone traffic for that zone is accepted. As soon as you add a
single rule from the zone to itself, then ALL traffic from that zone
to itself is controlled by the rules and the first policy in
<filename>/etc/shorewall/policy</filename> that matches the zone to
itself.</para>
</caution>
</section>
<section id="CONTINUE">
<title>The CONTINUE policy</title>
<para>Where zones are <link linkend="Nested">nested or
overlapping</link>, the CONTINUE policy allows hosts that are within
multiple zones to be managed under the rules of all of these zones.
Let's look at an example:</para>
<para><filename>/etc/shorewall/zones</filename>:</para>
<programlisting>#ZONE DISPLAY COMMENTS
sam Sam Sam's system at home
net Internet The Internet
loc Local Local Network</programlisting>
<para><filename>/etc/shorewall/interfaces</filename>:</para>
<programlisting>#ZONE INTERFACE BROADCAST OPTIONS
- eth0 detect dhcp,norfc1918
loc eth1 detect</programlisting>
<para><filename>/etc/shorewall/hosts</filename>:</para>
<programlisting>#ZONE HOST(S) OPTIONS
net eth0:0.0.0.0/0
sam eth0:206.191.149.197</programlisting>
<note>
<para>Sam's home system is a member of both the <emphasis
role="bold">sam</emphasis> zone and the <emphasis
role="bold">net</emphasis> zone and <link linkend="Nested">as
described above</link> , that means that <emphasis
role="bold">sam</emphasis> must be listed before <emphasis
role="bold">net</emphasis> in
<filename>/etc/shorewall/zones</filename>.</para>
</note>
<para><filename>/etc/shorewall/policy</filename>:</para>
<programlisting>#SOURCE DEST POLICY LOG LEVEL
loc net ACCEPT
sam all CONTINUE
net all DROP info
all all REJECT info</programlisting>
<para>The second entry above says that when Sam is the client,
connection requests should first be process under rules where the source
zone is <emphasis role="bold">sam</emphasis> and if there is no match
then the connection request should be treated under rules where the
source zone is <emphasis role="bold">net</emphasis>. It is important
that this policy be listed BEFORE the next policy (<emphasis
role="bold">net</emphasis> to <emphasis
role="bold">all</emphasis>).</para>
<para>Partial <filename>/etc/shorewall/rules</filename>:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
...
DNAT sam loc:192.168.1.3 tcp ssh
DNAT net loc:192.168.1.5 tcp www
...</programlisting>
<para>Given these two rules, Sam can connect to the firewall's internet
interface with ssh and the connection request will be forwarded to
192.168.1.3. Like all hosts in the <emphasis role="bold">net</emphasis>
zone, Sam can connect to the firewall's internet interface on TCP port
80 and the connection request will be forwarded to 192.168.1.5. The
order of the rules is not significant.</para>
<para id="Exclude">Sometimes it is necessary to suppress port forwarding
for a sub-zone. For example, suppose that all hosts can SSH to the
firewall and be forwarded to 192.168.1.5 EXCEPT Sam. When Sam connects
to the firewall's external IP, he should be connected to the firewall
itself. Because of the way that Netfilter is constructed, this requires
two rules as follows:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
...
DNAT sam fw tcp ssh
DNAT net loc:192.168.1.3 tcp ssh
...</programlisting>
<para>The first rule allows Sam SSH access to the firewall. The second
rule says that any clients from the net zone with the exception of those
in the <quote>sam</quote> zone should have their connection port
forwarded to 192.168.1.3. If you need to exclude more than one zone in
this way, you can list the zones separated by commas (e.g.,
net!sam,joe,fred). This technique also may be used when the ACTION is
REDIRECT.</para>
</section>
</section>
<section id="Rules" xreflabel="/etc/shorewall/rules">
<title>/etc/shorewall/rules</title>
<para>The <filename>/etc/shorewall/rules</filename> file defines
exceptions to the policies established in the
<filename>/etc/shorewall/policy</filename> file. There is one entry in
/etc/shorewall/rules for each of these rules. Entries in this file only
govern the establishment of new connections — packets that are part of an
existing connection or that establish a connection that is related to an
existing connection are automatically accepted.</para>
<para>Rules for each pair of zones (source zone, destination zone) are
evaluated in the order that they appear in the file — the first match
determines the disposition of the connection request with a couple of
caveats:</para>
<itemizedlist>
<listitem>
<para>LOG rules cause the connection request to be logged then
processing continues with the next rule in the file.</para>
</listitem>
<listitem>
<para>QUEUE rules cause the connection request to be passed to
user-space -- the user-space application can later insert them back
into the stream for further processing by following rules.</para>
</listitem>
<listitem>
<para>CONTINUE rules may cause the connection request to be
reprocessed using a different (source zone, destination zone)
pair.</para>
</listitem>
</itemizedlist>
<para>Entries in the file have the following columns:</para>
<variablelist>
<varlistentry>
<term>ACTION</term>
<listitem>
<variablelist>
<varlistentry>
<term>ACCEPT, DROP, REJECT, CONTINUE</term>
<listitem>
<para>These have the same meaning here as in the policy file
above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ACCEPT+</term>
<listitem>
<para>Added in Shorewall 2.0.2 Beta 2. Works like ACCEPT but
also exempts the connection from matching DNAT and REDIRECT
rules later in the file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NONAT</term>
<listitem>
<para>Added in Shorewall 2.0.2 Beta 2. Exempts matching
connections from DNAT and REDIRECT rules later in the
file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DNAT</term>
<listitem>
<para>Causes the connection request to be forwarded to the
system specified in the DEST column (port forwarding).
<quote>DNAT</quote> stands for <quote><emphasis
role="bold">D</emphasis>estination <emphasis
role="bold">N</emphasis>etwork <emphasis
role="bold">A</emphasis>ddress <emphasis
role="bold">T</emphasis>ranslation</quote></para>
</listitem>
</varlistentry>
<varlistentry>
<term>DNAT-</term>
<listitem>
<para>The above ACTION (DNAT) generates two iptables
rules:</para>
<orderedlist>
<listitem>
<para>a header-rewriting rule in the Netfilter
<quote>nat</quote> table</para>
</listitem>
<listitem>
<para>an ACCEPT rule in the Netfilter
<quote>filter</quote> table.</para>
</listitem>
</orderedlist>
<para>DNAT- works like DNAT but only generates the
header-rewriting rule.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SAME</term>
<listitem>
<para>Added in Shorewall 2.2.4. SAME is useful when more than
one server IP address (an address range, for example) is given
in the DEST column below. SAME works similar to DNAT with the
exception that when multiple connections from an internet host
match a SAME rule then all of the connections will be sent to
the same internal server.</para>
<note>
<para>Unlike when using DNAT rules, SAME rules may not alter
the destination port number used for the connection.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>SAME-</term>
<listitem>
<para>Added in Shorewall 2.2.4. SAME generates two iptables
rules:</para>
<orderedlist>
<listitem>
<para>a header-rewriting rule in the Netfilter
<quote>nat</quote> table</para>
</listitem>
<listitem>
<para>an ACCEPT rule in the Netfilter
<quote>filter</quote> table.</para>
</listitem>
</orderedlist>
<para>SAME- works like SAME but only generates the
header-rewriting rule.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REDIRECT</term>
<listitem>
<para>Causes the connection request to be redirected to a port
on the local (firewall) system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REDIRECT-</term>
<listitem>
<para>The above ACTION (REDIRECT) generates two iptables
rules:</para>
<orderedlist>
<listitem>
<para>a header-rewriting rule in the Netfilter
<quote>nat</quote> table</para>
</listitem>
<listitem>
<para>an ACCEPT rule in the Netfilter
<quote>filter</quote> table.</para>
</listitem>
</orderedlist>
<para>REDIRECT- works like REDIRECT but only generates the
header-rewriting rule.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOG</term>
<listitem>
<para>Log the packet -- requires a syslog level (see
below).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>QUEUE</term>
<listitem>
<para>Forward the packet to a user-space application. This
facility is provided to allow interfacing to <ulink
url="http://p2pwall.sourceforge.net">ftwall</ulink> for <ulink
url="Shorewall_and_Kazaa.html">Kazaa filtering</ulink>.</para>
<note>
<para>When the protocol specified in the PROTO column is TCP
(<quote>tcp</quote>, <quote>TCP</quote> or
<quote>6</quote>), Shorewall will only pass connection
requests (SYN packets) to user space. This is for
compatibility with ftwall.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="Actions.html">&lt;defined
action&gt;</ulink></term>
<listitem>
<para>(Shorewall 1.4.9 and later) - An action defined in the
<filename><ulink
url="Actions.html">/etc/shorewall/actions</ulink></filename>
or <filename>/usr/share/shorewall/actions.std</filename>
files.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The ACTION may optionally be followed by <quote>:</quote> and
a <ulink url="shorewall_logging.html">syslog level</ulink> (example:
REJECT:info or ACCEPT:debug). This causes the packet to be logged at
the specified level prior to being processed according to the
specified ACTION. Note: if the ACTION is LOG then you MUST specify a
syslog level. Beginning with Shorewall version 2.0.2 Beta 1, a
<firstterm>log tag</firstterm> may be specified. A log tag is a
string of alphanumeric characters and is specified by following the
log level with ":" and the log tag. Example:<programlisting>ACCEPT:info:ftp net dmz tcp 21
</programlisting>The log tag is appended to the log prefix generated by the
LOGPREFIX variable in <filename><link
linkend="Conf">/etc/shorewall/conf</link></filename>. If
"ACCEPT:info" generates the log prefix "Shorewall:net2dmz:ACCEPT:"
then "ACCEPT:info:ftp" will generate "Shorewall:net2dmz:ACCEPT:ftp "
(note the trailing blank). The maximum length of a log prefix
supported by iptables is 29 characters; if a larger prefix is
generated, Shorewall will issue a warning message and will truncate
the prefix to 29 characters.</para>
<para>Specifying a log level for a &lt;<emphasis>defined
action</emphasis>&gt; will log all invocations of the action. For
example:</para>
<programlisting>AllowFTP:info net dmz</programlisting>
<para>will log all net-&gt;dmz traffic that has not been handled by
earlier rules. That's probably not what you want. If you want to log
the FTP connections that are actually accepted, you need to log
within the action itself. One way to do that would be to copy
<filename>/usr/share/shorewall/action.AllowFTP</filename> to
<filename class="directory">/etc/shorewall</filename> and modify the
copy as follows:</para>
<programlisting>#TARGET SOURCE DEST PROTO DEST SOURCE RATE USER/
# PORT PORT(S) LIMIT GROUP
ACCEPT<emphasis role="bold">:info</emphasis> - - tcp 21
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
<para>The use of DNAT or REDIRECT requires that you have NAT enabled
in your <ulink url="kernel.htm">kernel configuration</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SOURCE</term>
<listitem>
<para>Describes the source hosts to which the rule applies.. The
contents of this field must begin with the name of a zone defined in
/etc/shorewall/zones, $FW, <quote>all</quote> or "none". If the
ACTION is DNAT or REDIRECT, sub-zones may be excluded from the rule
by following the initial zone name with <quote>!</quote> and a
comma-separated list of those sub-zones to be excluded. There is an
<link linkend="Exclude">example</link> above.</para>
<para>If the source is "none" then the rule is ignored. This is most
commonly used with <ulink
url="http://shorewall.net/configuration_file_basics.htm#Variables">Shell
Variables</ulink> where a shell variable is set to "none" if a rule
is to be omitted.</para>
<para>If the source is not <quote>all</quote> then the source may be
further restricted by adding a colon (<quote>:</quote>) followed by
a comma-separated list of qualifiers. Qualifiers are may
include:</para>
<variablelist>
<varlistentry>
<term>interface name</term>
<listitem>
<para>refers to any connection requests arriving on the
specified interface (example loc:eth4). Beginning with
Shorwall 1.3.9, the interface name may optionally be followed
by a colon (<quote>:</quote>) and an IP address or subnet
(examples: loc:eth4:192.168.4.22,
net:eth0:192.0.2.0/24).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IP address</term>
<listitem>
<para>refers to a connection request from the host with the
specified address (example net:155.186.235.151). If the ACTION
is DNAT, this must not be a DNS name.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MAC Address</term>
<listitem>
<para>in <ulink
url="configuration_file_basics.htm#MAC">Shorewall
format</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>subnet</term>
<listitem>
<para>refers to a connection request from any host in the
specified subnet (example net:155.186.235.0/24). Beginning
with Shorewall 2.1.0, IP address ranges of the form
&lt;<emphasis>first address</emphasis>&gt;-&lt;<emphasis>last
address</emphasis>&gt; may be specified. This requires that
your kernel and iptables have iprange match support.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term>DEST</term>
<listitem>
<para>Describes the destination host(s) to which the rule applies.
May take most of the forms described above for SOURCE plus the
following two additional forms:</para>
<itemizedlist>
<listitem>
<para>An IP address followed by a colon and the port <emphasis
role="bold">number</emphasis> that the server is listening on
(service names from /etc/services are not allowed - example
loc:192.168.1.3:80).</para>
</listitem>
<listitem>
<para>A single port number (again, service names are not
allowed) -- this form is only allowed if the ACTION is REDIRECT
and refers to a server running on the firewall itself and
listening on the specified port.</para>
</listitem>
</itemizedlist>
<para>Restrictions:</para>
<itemizedlist>
<listitem>
<para>MAC addresses may not be specified.</para>
</listitem>
<listitem>
<para>In DNAT rules, only IP addresses may be given -- DNS names
are not permitted.</para>
</listitem>
<listitem>
<para>You may not specify both an IP address and an interface
name in the DEST column.</para>
</listitem>
</itemizedlist>
<para>Like in the SOURCE column, a range of IP addresses may be
specified in the DEST column as &lt;<emphasis>first
address</emphasis>&gt;-&lt;<emphasis>last address</emphasis>&gt;.
When the ACTION is DNAT or DNAT-, connections will be assigned to
the addresses in the range in a round-robin fashion
(load-balancing). <emphasis role="bold">This feature is available
with DNAT rules only with Shorewall 1.4.6 and later versions; it is
available with DNAT- rules in all versions that support DNAT-. It is
available with SAME and SAME- rules in all versions that support
those actions.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>PROTO</term>
<listitem>
<para>Protocol. Must be a protocol name from /etc/protocols, a
number, or <quote>all</quote>. Specifies the protocol of the
connection request.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEST PORT(S)</term>
<listitem>
<para>Port or port range (&lt;low port&gt;:&lt;high port&gt;) being
connected to. May only be specified if the protocol is tcp, udp or
icmp. For icmp, this column's contents are interpreted as an icmp
type. If you don't want to specify DEST PORT(S) but need to include
information in one of the columns to the right, enter
<quote>-</quote> in this column. You may give a list of ports and/or
port ranges separated by commas. Port numbers may be either integers
or service names from /etc/services.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SOURCE PORTS(S)</term>
<listitem>
<para>May be used to restrict the rule to a particular client port
or port range (a port range is specified as &lt;low port
number&gt;:&lt;high port number&gt;). If you don't want to restrict
client ports but want to specify something in the next column, enter
<quote>-</quote> in this column. If you wish to specify a list of
port number or ranges, separate the list elements with commas (with
no embedded white space). Port numbers may be either integers or
service names from /etc/services.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ORIGINAL DEST</term>
<listitem>
<para>This column may only be non-empty if the ACTION is DNAT or
REDIRECT.</para>
<para>If DNAT or REDIRECT is the ACTION and the ORIGINAL DEST column
is left empty, any connection request arriving at the firewall from
the SOURCE that matches the rule will be forwarded or redirected.
This works fine for connection requests arriving from the internet
where the firewall has only a single external IP address. When the
firewall has multiple external IP addresses or when the SOURCE is
other than the internet, there will usually be a desire for the rule
to only apply to those connection requests directed to particular IP
addresses (see Example 2 below for another usage). Those IP
addresses are specified in the ORIGINAL DEST column as a
comma-separated list.</para>
<para>If this list begins with <quote>!</quote> then the rule will
only apply if the original destination address matches none of the
addresses listed.</para>
<para>The IP address(es) may be optionally followed by
<quote>:</quote> and a second IP address. This latter address, if
present, is used as the source address for packets forwarded to the
server (This is called <quote>Source NAT</quote> or SNAT.</para>
<warning>
<para>Specifying SNAT in a DNAT rule is deprecated and this
feature was removed from Shorewall in version 2.1.0. An entry in
<link linkend="Masq">/etc/shorewall/masq</link> can serve the same
purpose and is the preferred method of performing SNAT with
Shorewall. See <ulink url="FAQ.htm#faq2">FAQ 2</ulink> for an
example.</para>
</warning>
<note>
<para>When using SNAT, it is a good idea to qualify the source
with an IP address or subnet. Otherwise, it is likely that SNAT
will occur on connections other than those described in the rule.
The reason for this is that SNAT occurs in the Netfilter
POSTROUTING hook where it is not possible to restrict the scope of
a rule by incoming interface.</para>
<example>
<title></title>
<programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL
# PORT(S) PORT(S) DEST
DNAT loc:<emphasis role="bold">192.168.1.0/24</emphasis> loc:192.168.1.3 tcp www - 206.124.146.179:192.168.1.3</programlisting>
</example>
</note>
<para>If SNAT is not used (no <quote>:</quote> and second IP
address), the original source address is used. If you want any
destination address to match the rule but want to specify SNAT,
simply use a colon followed by the SNAT address.</para>
<important>
<para>Shorewall does not take any steps to ensure that IP
addresses entered in this column are added to the appropriate
firewall interface. Unless traffic for this address is
automatically routed to the firewall by another router, it is your
responsibility to add the address using your distributions network
configuration facilities. See <ulink
url="Shorewall_and_Aliased_Interfaces.html">this article</ulink>
for additional information.</para>
</important>
</listitem>
</varlistentry>
<varlistentry>
<term>RATE LIMIT</term>
<listitem>
<para>Beginning with Shorewall version 1.4.7, you may rate-limit
ACCEPT, DNAT[-], REDIRECT[-] or LOG rules with an entry in this
column. Entries have the form</para>
<programlisting>&lt;rate&gt;/&lt;interval&gt;[:&lt;burst&gt;]</programlisting>
<para>where &lt;rate&gt; is the number of connections per
&lt;interval&gt; (<quote>sec</quote> or <quote>min</quote>) and
&lt;burst&gt; is the largest burst permitted. If no burst value is
given, a value of 5 is assumed.</para>
<para>There may be no whitespace embedded in the
specification.</para>
<example>
<title>Let's take</title>
<programlisting>ACCEPT&lt;2/sec:4&gt; net dmz tcp 80</programlisting>
<para>The first time this rule is reached, the packet will be
accepted; in fact, since the burst is 4, the first four packets
will be accepted. After this, it will be 500ms (1 second divided
by the rate of 2) before a packet will be accepted from this rule,
regardless of how many packets reach it. Also, every 500ms which
passes without matching a packet, one of the bursts will be
regained; if no packets hit the rule for 2 second, the burst will
be fully recharged; back where we started.</para>
</example>
<warning>
<para>When rate limiting is specified on a rule with
<quote>all</quote> in the SOURCE or DEST fields below, the limit
will apply to each pair of zones individually rather than as a
single limit for all pairs of zones covered by the rule.</para>
</warning>
<para>If you want to specify any following columns but no rate
limit, place <quote>-</quote> in this column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>USER/GROUP</term>
<listitem>
<para>Beginning with Shorewall release 1.4.7, output rules from the
firewall itself may be restricted to a particular set of users
and/or user groups. See the <ulink url="UserSets.html">User Set
Documentation</ulink> for details.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>You wish to forward all ssh connection requests from the internet
to local system 192.168.1.3. You wish to limit the number of connections
to 4/minute with a burst of 8 (Shorewall 1.4.7 and later only):</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT&lt;4/min:8&gt; net loc:192.168.1.3 tcp ssh</programlisting>
</example>
<example>
<title>You want to redirect all local www connection requests EXCEPT
those to your own http server (206.124.146.177) to a Squid transparent
proxy running on the firewall and listening on port 3128. Squid will of
course require access to remote web servers. This example shows yet
another use for the ORIGINAL DEST column; here, connection requests that
were NOT (notice the <quote>!</quote>) originally destined to
206.124.146.177 are redirected to local port 3128.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST
REDIRECT loc 3128 tcp www - !206.124.146.177
ACCEPT fw net tcp www</programlisting>
</example>
<example>
<title>You want to run a web server at 155.186.235.222 in your DMZ and
have it accessible remotely and locally. the DMZ is managed by Proxy ARP
or by classical sub-netting.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT net dmz:155.186.235.222 tcp www
ACCEPT loc dmz:155.186.235.222 tcp www</programlisting>
</example>
<example>
<title>You want to run wu-ftpd on 192.168.2.2 in your masqueraded DMZ.
Your internet interface address is 155.186.235.151 and you want the FTP
server to be accessible from the internet in addition to the local
192.168.1.0/24 and dmz 192.168.2.0/24 subnetworks.</title>
<para><note>
<para>since the server is in the 192.168.2.0/24 subnetwork, we can
assume that access to the server from that subnet will not involve
the firewall (<ulink url="FAQ.htm#faq2">but see FAQ
2</ulink>)</para>
</note><note>
<para>unless you have more than one external IP address, you can
leave the ORIGINAL DEST column blank in the first rule. You cannot
leave it blank in the second rule though because then all ftp
connections originating in the local subnet 192.168.1.0/24 would be
sent to 192.168.2.2 regardless of the site that the user was trying
to connect to. That is clearly not what you want.</para>
</note></para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST
DNAT net dmz:192.168.2.2 tcp ftp
DNAT loc:192.168.1.0/24 dmz:192.168.2.2 tcp ftp - 155.186.235.151</programlisting>
<para>If you are running wu-ftpd, you should restrict the range of
passive in your /etc/ftpaccess file. I only need a few simultaneous FTP
sessions so I use port range 65500-65535. In /etc/ftpaccess, this entry
is appropriate:</para>
<programlisting>passive ports 0.0.0.0/0 65500 65534</programlisting>
<para>If you are running pure-ftpd, you would include <quote>-p
65500:65534</quote> on the pure-ftpd runline.</para>
<para>The important point here is to ensure that the port range used for
FTP passive connections is unique and will not overlap with any usage on
the firewall system.</para>
</example>
<example>
<title>You wish to allow unlimited DMZ access to the host with MAC
address 02:00:08:E3:FA:55.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT loc:~02-00-08-E3-FA-55 dmz all</programlisting>
</example>
<example>
<title>You wish to allow access to the SMTP server in your DMZ from all
zones.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT all dmz tcp 25</programlisting>
<para><note>
<para>When <quote>all</quote> is used as a source or destination,
intra-zone traffic is not affected. In this example, if there were
two DMZ interfaces then the above rule would NOT enable SMTP traffic
between hosts on these interfaces.</para>
</note></para>
</example>
<example>
<title>Your firewall's external interface has several IP addresses but
you only want to accept SSH connections on address
206.124.146.176.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT net fw:206.124.146.176 tcp 22</programlisting>
</example>
<example>
<title>(For advanced users running Shorewall version 1.3.13 or later).
From the internet, you with to forward tcp port 25 directed to
192.0.2.178 and 192.0.2.179 to host 192.0.2.177 in your DMZ. You also
want to allow access from the internet directly to tcp port 25 on
192.0.2.177.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST
DNAT- net dmz:192.0.2.177 tcp 25 - 192.0.2.178
DNAT- net dmz:192.0.2.177 tcp 25 - 192.0.2.179
ACCEPT net dmz:192.0.2.177 tcp 25</programlisting>
<para>Using <quote>DNAT-</quote> rather than <quote>DNAT</quote> avoids
two extra copies of the third rule from being generated.</para>
</example>
<example>
<title>(Shorewall version 1.4.6 or later). You have 9 http servers
behind a Shorewall firewall and you want connection requests to be
distributed among your servers. The servers are
192.168.1.101-192.168.1.109.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT net loc:192.168.1.101-192.168.1.109 tcp 80</programlisting>
</example>
<example>
<title>(Shorewall 2.0.2 Beta 2 and Later). You want to redirect all
local www connection requests EXCEPT those from 192.168.1.4 and
192.168.1.199 to a Squid transparent proxy running on the firewall and
listening on port 3128.</title>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST
NONAT loc:192.168.1.4,192.168.1.199 \
net tcp www
REDIRECT loc 3128 tcp www -
ACCEPT fw net tcp www</programlisting>
<para>The reason that NONAT is used in the above example rather than
ACCEPT+ is that the example is assuming the usual ACCEPT loc-&gt;net
policy. Since traffic from the local zone to the internet zone is
accepted anyway, adding an additional ACCEPT rule is unnecessary and all
that is required is to avoid the REDIRECT rule for HTTP connection
requests from the two listed IP addresses.</para>
</example>
<para><ulink url="ports.htm">Look here for information on other
services.</ulink></para>
</section>
<section id="Masq" xreflabel="/etc/shorewall/masq">
<title>/etc/shorewall/masq</title>
<para>The /etc/shorewall/masq file is used to define classical IP
Masquerading and Source Network Address Translation (SNAT). There is one
entry in the file for each subnet that you want to masquerade. In order to
make use of this feature, you must have NAT enabled.</para>
<para>Columns are:</para>
<variablelist>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>The interface that will masquerade the subnet; this is
normally your internet interface. This interface name can be
optionally qualified by adding <quote>:</quote> and a subnet or host
IP. When this qualification is added, only packets addressed to that
host or subnet will be masqueraded. Beginning with Shorewall version
1.4.10, the interface name can be qualified with ":" followed by a
comma separated list of hosts and/or subnets. If this list begins
with <quote>!</quote> (e.g.,
<quote>eth0:!192.0.2.8/29,192.0.2.32/29</quote>) then only packets
addressed to destinations <emphasis role="bold">not</emphasis>
listed will be masqueraded; otherwise (e.g.,
<quote>eth0:192.0.2.8/29,192.0.2.32/29</quote>), traffic will be
masqueraded if it <emphasis role="bold">does</emphasis> match one of
the listed addresses.</para>
<para>Beginning with Shorewall version 1.3.14, if you have set
ADD_SNAT_ALIASES=Yes in <xref linkend="Conf" />, you can cause
Shorewall to create an alias <emphasis>label</emphasis> of the form
<emphasis>interfacename:digit</emphasis> (e.g., eth0:0) by placing
that label in this column. See example 5 below. Alias labels created
in this way allow the alias to be visible to the ipconfig utility.
<emphasis role="bold">THAT IS THE ONLY THING THAT THIS LABEL IS GOOD
FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN YOUR SHOREWALL
CONFIGURATION.</emphasis></para>
<para>Normally MASQUERADE/SNAT rules are evaluated after one-to-one
NAT rules defined in the <link
linkend="NAT"><filename>/etc/shorewall/nat</filename></link> file.
Beginning with Shorewall 2.1.1, if you preceed the interface name
with a plus sign ("+") then the rule will be evaluated before
one-to-one NAT.</para>
<para>Examples:</para>
<programlisting>+eth0
+eth1:192.0.2.32/27</programlisting>
<para>Also new in the Shorewall 2.1 series, the effect of
ADD_SNAT_ALIASES=Yes can be negated for an entry by following the
interface name by ":" but no digit.</para>
<para>Examples:</para>
<programlisting>eth0:
eth1::192.0.2.32/27
+eth3</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>SUBNET</term>
<listitem>
<para>The subnet that you want to have masqueraded through the
INTERFACE. This may be expressed as a single IP address, a subnet or
an interface name. In the latter instance, the interface must be
configured and started before Shorewall is started as Shorewall will
determine the subnet based on information obtained from the
<quote>ip</quote> utility.</para>
<caution>
<para>When using Shorewall 1.3.13 or earlier, when an interface
name is specified, Shorewall will only masquerade traffic from the
first subnetwork on the named interface; if the interface
interfaces to more that one subnetwork, you will need to add
additional entries to this file for each of those other
subnetworks. Beginning with Shorewall 1.3.14, shorewall will
masquerade/SNAT traffic from any host that is routed through the
named interface.</para>
</caution>
<para>The subnet may be optionally followed by <quote>!</quote> and
a comma-separated list of addresses and/or subnets that are to be
excluded from masquerading.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ADDRESS</term>
<listitem>
<para>The source address to be used for outgoing packets. This
column is optional and if left blank, the current primary IP address
of the interface in the first column is used. If you have a static
IP on that interface, listing it here makes processing of output
packets a little less expensive for the firewall. If you specify an
address in this column, it must be an IP address configured on the
INTERFACE or you must have ADD_SNAT_ALIASES enabled in <xref
linkend="Conf" />. Beginning with Shorewall version 1.4.6, you may
include a range of IP addresses in this column to indicate that
Netfilter should use the addresses in the range in round-robin
fashion. Beginning with Shorewall version 1.4.7, you may include a
list of ranges and/or addresses in this column; again, Netfilter
will use all listed ranges/addresses in rounded-robin
fashion.</para>
<para>Beginning with Shorewall 2.2.0, you may also specify the
source port range to be used (the PROTO column must specify tcp or
udp) by following the address or address range if any with ":" and
the port range (in the format &lt;<emphasis>low
port</emphasis>&gt;-&lt;<emphasis>high port</emphasis>&gt;).</para>
<para>Examples:</para>
<programlisting>#INTERFACE SUBNET ADDRESS PROTO
eth0 10.0.0.0/8 192.0.2.44:7000-8000 udp</programlisting>
<programlisting>#INTERFACE SUBNET ADDRESS PROTO
eth0 192.168.1.0/24 :4000-5000 tcp</programlisting>
<para>Some internet application that establish multiple connections
from a client assume that when SNAT is being used that all
connections between the client and a particular client and a remote
server will appear to the server to come from the same external IP
address. Beginning with Shorewall 2.2.4, you can ensure that this is
the case by preceding the ADDRESS range by "SAME:".</para>
<para>Example:</para>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 10.0.0.0/8 SAME:192.0.2.44-192.168.2.50</programlisting>
<para>If you want all connections from an internal system to use the
same external IP address regardless of the remote server that they
are connecting to then precede the ADDRESS range by
"SAME:nodst:".</para>
<para>Example:</para>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 10.0.0.0/8 SAME:nodst:192.0.2.44-192.168.2.50</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>PROTO (Added in Shorewall version 2.0.2 Beta 1)</term>
<listitem>
<para>If specified, must be a protocol number of a protocol name
from /etc/protocols. Restricts the SNAT or Masquerade to that
protocol.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PORT(S) (Added in Shorewall version 2.0.2 Beta 1)</term>
<listitem>
<para>If the PROTO column specifies TCP (6) or UDP (17) then this
column may be used to restrict to SNAT or Masquerade to traffic with
a certain destination port or a set of destination ports. The column
may contain:</para>
<itemizedlist>
<listitem>
<para>A port number or a port name from /etc/services.</para>
</listitem>
<listitem>
<para>A comma-separated list of port numbers and/or port names.
Your kernel must have Multiport match support. You can tell if
your kernel has this support by issuing a <command>shorewall
check</command> command and looking at the output under
<quote>Shorewall has detected the following iptables/netfilter
capabilities:</quote>.</para>
</listitem>
<listitem>
<para>A range of port numbers of the form &lt;<emphasis>low
port</emphasis>&gt;:&lt;<emphasis>high
port</emphasis>&gt;</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
<varlistentry>
<term>IPSEC (Added in Shorewall version 2.2.0)</term>
<listitem>
<para>If you specify a value other than "-" in this column, you must
be running kernel 2.6 and your kernel and iptables must include
policy match support.</para>
<para>The value in this column is a comma-separated list of options
from the following. Only packets that will be encrypted via an SA
that matches these options will have their source address
changed.</para>
<itemizedlist>
<listitem>
<para>Yes or yes ― Match any SA. Normally used as the only
option.</para>
</listitem>
<listitem>
<para>reqid=&lt;<emphasis>number</emphasis>&gt; where
&lt;<emphasis>number</emphasis>&gt; is specified using setkey(8)
using the 'unique:&lt;<emphasis>number</emphasis>&gt;' option
for the SPD level.</para>
</listitem>
<listitem>
<para>spi=&lt;<emphasis>number</emphasis>&gt; where
&lt;<emphasis>number</emphasis>&gt; is the SPI of the SA.</para>
</listitem>
<listitem>
<para>proto=ah|esp|ipcomp</para>
</listitem>
<listitem>
<para>mode=transport|tunnel</para>
</listitem>
<listitem>
<para>tunnel-src=&lt;<emphasis>address</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;]
(only available with mode=tunnel)</para>
</listitem>
<listitem>
<para>tunnel-dst=&lt;<emphasis>address</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;]
(only available with mode=tunnel)</para>
</listitem>
<listitem>
<para>strict — Means that packets must match all rules.</para>
</listitem>
<listitem>
<para>next — Separates rules; can only be used with
strict.</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>You have eth0 connected to a cable modem and eth1 connected to
your local subnetwork 192.168.9.0/24. Your /etc/shorewall/masq file
would look like:</title>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 192.168.9.0/24</programlisting>
</example>
<example>
<title>You have a number of IPSEC tunnels through ipsec0 and you want to
masquerade traffic from your 192.168.9.0/24 subnet to the remote subnet
10.1.0.0/16 only.</title>
<programlisting>#INTERFACE SUBNET ADDRESS
ipsec0:10.1.0.0/16 192.168.9.0/24</programlisting>
</example>
<example>
<title>You have a DSL line connected on eth0 and a local network
(192.168.10.0/24) connected to eth1. You want all local-&gt;net
connections to use source address 206.124.146.176.</title>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 192.168.10.0/24 206.124.146.176</programlisting>
</example>
<example>
<title>Same as example 3 except that you wish to exclude 192.168.10.44
and 192.168.10.45 from the SNAT rule.</title>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 192.168.10.0/24!192.168.10.44,192.168.10.45 206.124.146.176</programlisting>
</example>
<example>
<title><emphasis role="bold">(Shorewall version &gt;=
1.3.14):</emphasis> You have a second IP address (206.124.146.177)
assigned to you and wish to use it for SNAT of the subnet
192.168.12.0/24. You want to give that address the name eth0:0. You must
have ADD_SNAT_ALIASES=Yes in <xref linkend="Conf" />.</title>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0:0 192.168.12.0/24 206.124.146.177</programlisting>
</example>
<example>
<title><emphasis role="bold">(Shorewall version &gt;= 1.4.7):</emphasis>
You want to use both 206.124.146.177 and 206.124.146.179 for SNAT of the
subnet 192.168.12.0/24. Each address will be used on alternate outbound
connections.</title>
<programlisting>#INTERFACE SUBNET ADDRESS
eth0 192.168.12.0/24 206.124.146.177,206.124.146.179</programlisting>
</example>
<example>
<title><emphasis role="bold">(Shorewall version &gt;= 2.0.2 Beta
1):</emphasis> You want all outgoing SMTP traffic entering the firewall
on eth1 to be sent from eth0 with source IP address 206.124.146.177. You
want all other outgoing traffic from eth1 to be sent from eth0 with
source IP address 206.124.146.176.</title>
<programlisting>#INTERFACE SUBNET ADDRESS PROTO PORT(S)
eth0 eth1 206.124.146.177 tcp 25
eth0 eth1 206.124.146.176</programlisting>
<para>Note that the order of the entries in the above example is
important.</para>
</example>
</section>
<section id="ProxyArp" xreflabel="/etc/shorewall/proxyarp">
<title>/etc/shorewall/proxyarp</title>
<para>If you want to use proxy ARP on an entire sub-network, I suggest
that you look at the <ulink
url="http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/">Proxy ARP Subnet
Mini HOWTO</ulink>. If you decide to use the technique described in that
HOWTO, you can set the proxy_arp flag for an interface
(<filename>/proc/sys/net/ipv4/conf/</filename>&lt;<emphasis>interface</emphasis>&gt;<filename>/proxy_arp</filename>)
by including the <emphasis role="bold">proxyarp</emphasis> option in the
interface's record in <xref linkend="Interfaces" />. When using Proxy ARP
sub-netting, you do <emphasis role="bold">NOT</emphasis> include any
entries in /etc/shorewall/proxyarp.</para>
<para>The <filename>/etc/shorewall/proxyarp </filename>file is used to
define <ulink url="ProxyARP.htm">Proxy ARP</ulink>. The file is typically
used for enabling Proxy ARP on a small set of systems since you need one
entry in this file for each system using proxy ARP. Columns are:</para>
<variablelist>
<varlistentry>
<term>ADDRESS</term>
<listitem>
<para>address of the system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>the interface that connects to the system. If the interface is
obvious from the subnetting, you may enter <quote>-</quote> in this
column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EXTERNAL</term>
<listitem>
<para>the external interface that you want to honor ARP requests for
the ADDRESS specified in the first column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HAVEROUTE</term>
<listitem>
<para>If you already have a route through INTERFACE to ADDRESS, this
column should contain <quote>Yes</quote> or <quote>yes</quote>. If
you want Shorewall to add the route, the column should contain
<quote>No</quote> or <quote>no</quote>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PERSISTENT</term>
<listitem>
<para>If you specify "No" or "no" in the HAVEROUTE column, Shorewall
will automatically add a route to the host in the ADDRESS column
through the interface in the INTERFACE column. If you enter
<quote>No</quote> or <quote>no</quote> in the PERSISTENT column or
if you leave the column empty, that route will be deleted if you
issue a <command>shorewall stop</command> or <command>shorewall
clear</command> command. If you place <quote>Yes</quote> or
<quote>yes</quote> in the PERSISTENT column, then those commands
will not cause the route to be deleted.</para>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>After you have made a change to the
<filename>/etc/shorewall/proxyarp file</filename>, you may need to flush
the ARP cache of all routers on the LAN segment connected to the
interface specified in the EXTERNAL column of the change/added entry(s).
If you are having problems communicating between an individual host (A)
on that segment and a system whose entry has changed, you may need to
flush the ARP cache on host A as well.</para>
<para>ISPs typically have ARP configured with long TTL (hours!) so if
your ISPs router has a stale cache entry (as seen using <quote>tcpdump
-nei &lt;external interface&gt; host &lt;IP addr&gt;</quote>), it may
take a long while to time out. I personally have had to contact my ISP
and ask them to delete a stale entry in order to restore a system to
working order after changing my proxy ARP settings.</para>
</note>
<example>
<title>You have public IP addresses 155.182.235.0/28. You configure your
firewall as follows:</title>
<programlisting>eth0 - 155.186.235.1 (internet connection) eth1 -
192.168.9.0/24 (masqueraded local systems) eth2 - 192.168.10.1
(interface to your DMZ)</programlisting>
<para>In your DMZ, you want to install a Web/FTP server with public
address 155.186.235.4. On the Web server, you subnet just like the
firewall's eth0 and you configure 155.186.235.1 as the default gateway.
In your <filename>/etc/shorewall/proxyarp</filename> file, you will
have:</para>
<programlisting>#ADDRESS INTERFACE EXTERNAL HAVEROUTE
155.186.235.4 eth2 eth0 NO</programlisting>
<para><tip>
<para>You may want to configure the servers in your DMZ with a
subnet that is smaller than the subnet of your internet interface.
See the <ulink
url="http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/">Proxy ARP
Subnet Mini HOWTO</ulink> for details. In this case you will want to
place <quote>Yes</quote> in the HAVEROUTE column.</para>
</tip></para>
</example>
</section>
<section id="NAT" xreflabel="/etc/shorewall/nat">
<title>/etc/shorewall/nat</title>
<para>The <filename>/etc/shorewall/nat</filename> file is used to define
one-to-one NAT. There is one entry in the file for each one-to-one NAT
relationship that you wish to define. In order to make use of this
feature, you must have NAT enabled.</para>
<important>
<para>If all you want to do is forward ports to servers behind your
firewall, you do NOT want to use one-to-one NAT. Port forwarding can be
accomplished with simple entries in the <link linkend="Rules">rules
file</link>. Also, in most cases <link linkend="ProxyArp">Proxy
ARP</link> provides a superior solution to one-to-one NAT because the
internal systems are accessed using the same IP address internally and
externally.</para>
</important>
<para>Columns in an entry are:</para>
<variablelist>
<varlistentry>
<term>EXTERNAL</term>
<listitem>
<para>External IP address</para>
<caution>
<para>This should NOT be the primary IP address of the interface
named in the next column.</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>Interface that you want the EXTERNAL IP address to appear on.
Beginning with Shorewall version 1.3.14, if you have set
ADD_IP_ALIASES=Yes in <xref linkend="Conf" />, you can specify an
alias label of the form <emphasis>interfacename:digit</emphasis>
(e.g., eth0:0) and Shorewall will create the alias with that label.
Alias labels created in this way allow the alias to be visible to
the ipconfig utility. <emphasis role="bold">THAT IS THE ONLY THING
THAT THIS LABEL IS GOOD FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN
YOUR SHOREWALL CONFIGURATION.</emphasis></para>
<para>Beginning with Shorewall 2.1.1, the effect of
ADD_IP_ALIASES=Yes can be negated for an entry by following the
interface name by ":" but no digit.</para>
<para>Example:</para>
<programlisting>eth0:</programlisting>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERNAL</term>
<listitem>
<para>Internal IP address.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ALL INTERFACES</term>
<listitem>
<para>If <quote>Yes</quote> or <quote>yes</quote>, NAT will be
effective from all hosts. If <quote>No</quote> or <quote>no</quote>
(or if left empty) then NAT will be effective only through the
interface named in the INTERFACE column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOCAL</term>
<listitem>
<para>If Yes or yes, NAT will be effective from the firewall system.
Note that with Shorewall 2.0.1 and earlier versions, this column was
ignored if the ALL INTERFACES column did not contain "Yes" or "yes".
Beginning with Shorewall 2.0.2 Beta 1, this column's contents are
independent of the value in ALL INTERFACES.</para>
<note>
<para>For this to work, you must be running kernel 2.4.19 or later
and iptables 1.2.6a or later and you must have enabled <emphasis
role="bold">CONFIG_IP_NF_NAT_LOCAL</emphasis> in your
kernel.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para><ulink url="NAT.htm">Look here for additional information and an
example.</ulink></para>
</section>
<section id="Tunnels" xreflabel="/etc/shorewall/tunnels">
<title>/etc/shorewall/tunnels</title>
<para>The /etc/shorewall/tunnels file allows you to define IPSec, GRE,
IPIP, <ulink url="http://openvpn.sourceforge.net/">OpenVPN</ulink>, PPTP,
6to4 and other tunnels with end-points on your firewall.</para>
<para>For an overview of Shorewall's VPN support, try <ulink
url="VPNBasics.html">this article</ulink>.</para>
<para>Instructions for setting up <ulink url="IPSEC.htm">IPSEC
tunnels</ulink> may be found here (if you are using kernel 2.6 with native
IPSEC support, look <ulink url="IPSEC-2.6.html">here</ulink>),
instructions for <ulink url="IPIP.htm">IPIP and GRE tunnels</ulink> are
here, instructions for <ulink url="OPENVPN.html">OpenVPN tunnels</ulink>
are here, instructions for <ulink url="PPTP.htm">PPTP tunnels</ulink> are
here, instructions for <ulink url="6to4.htm">6to4 tunnels</ulink> are
here, and instructions for <ulink url="GenericTunnels.html">integrating
Shorewall with other types of tunnels</ulink> are here.</para>
</section>
<section id="Conf" xreflabel="/etc/shorewall/shorewall.conf">
<title>/etc/shorewall/shorewall.conf</title>
<para>This file is used to set the following firewall parameters:</para>
<variablelist>
<varlistentry>
<term>STARTUP_ENABLED</term>
<listitem>
<para>(Added at version 2.2.0) - When set to Yes or yes, Shorewall
may be started. Used as guard against Shorewall being accidentally
started before it has been configured.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MACLIST_TTL</term>
<listitem>
<para>(Added at version 2.2.0) The performance of configurations
with a large numbers of entries in /etc/shorewall/maclist can be
improved by setting the MACLIST_TTL variable in
/etc/shorewall/shorewall.conf.</para>
<para>If your iptables and kernel support the "Recent Match" (see
the output of "shorewall check" near the top), you can cache the
results of a 'maclist' file lookup and thus reduce the overhead
associated with <ulink url="MAC_Validation.html">MAC
Verification</ulink>.</para>
<para>When a new connection arrives from a 'maclist' interface, the
packet passes through then list of entries for that interface in
/etc/shorewall/maclist. If there is a match then the source IP
address is added to the 'Recent' set for that interface. Subsequent
connection attempts from that IP address occurring within
$MACLIST_TTL seconds will be accepted without having to scan all of
the entries. After $MACLIST_TTL from the first accepted connection
request from an IP address, the next connection request from that IP
address will be checked against the entire list.</para>
<para>If MACLIST_TTL is not specified or is specified as empty (e.g,
MACLIST_TTL="" or is specified as zero then 'maclist' lookups will
not be cached).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RFC1918_STRICT</term>
<listitem>
<para>(Added at version 2.2.2) — Traditionally, the RETURN target in
the 'rfc1918' file has caused <link
linkend="Interfaces">norfc1918</link> processing to cease for a
packet if the packet's source IP address matches the rule. Thus, if
you have this entry in <link
linkend="rfc1918">/etc/shorewall/rfc1918</link>:</para>
<programlisting>#SUBNETS TARGET
192.168.1.0/24 RETURN</programlisting>
<para>then traffic from 192.168.1.4 to 10.0.3.9 will be accepted
even though you also have:</para>
<programlisting>#SUBNETS TARGET
10.0.0.0/8 logdrop</programlisting>
<para>Setting RFC1918_STRICT=Yes in shorewall.conf will cause such
traffic to be logged and dropped since while the packet's source
matches the RETURN rule, the packet's destination matches the
'logdrop' rule.</para>
<para>If not specified or specified as empty (e.g.,
RFC1918_STRICT="") then RFC1918_STRICT=No is assumed.</para>
<warning>
<para>RFC1918_STRICT=Yes requires that your kernel and iptables
support 'Connection Tracking' match.</para>
</warning>
</listitem>
</varlistentry>
<varlistentry>
<term>DROPINVALID</term>
<listitem>
<para>(Added at version 2.2.0 and backported into version 2.0.16) —
Recent 2.6 kernels include code that evaluates TCP packets based on
TCP Window analysis. This can cause packets that were previously
classified as NEW or ESTABLISHED to be classified as INVALID.</para>
<para>The new kernel code can be disabled by including this command
in your <ulink
url="shorewall_extension_scripts.htm">/etc/shorewall/init</ulink>
file:</para>
<programlisting>echo 1 &gt; /proc/sys/net/ipv4/netfilter/ip_conntrack_tcp_be_liberal</programlisting>
<para>Additional kernel logging about INVALID TCP packets may be
obtained by adding this command to /etc/shorewall/init:</para>
<programlisting>echo 1 &gt; /proc/sys/net/ipv4/netfilter/ip_conntrack_log_invalid</programlisting>
<para>Traditionally, Shorewall has dropped INVALID TCP packets
early. The DROPINVALID option allows INVALID packets to be passed
through the normal rules chains by setting DROPINVALID=No. If not
specified or if specified as empty (e.g., DROPINVALID="") then
DROPINVALID=Yes is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGALLNEW</term>
<listitem>
<para>(Aded at version 2.2.0)- When set to a log level, this option
causes Shorewall to generate a logging rule as the first rule in
each builtin chain.</para>
<itemizedlist>
<listitem>
<para>The table name is used as the chain name in the log
prefix.</para>
</listitem>
<listitem>
<para>The chain name is used as the target in the log
pref</para>
</listitem>
</itemizedlist>
<para>Example: Using the default LOGFORMAT, the log prefix for
logging from the nat table's PREROUTING chain is:</para>
<programlisting>Shorewall:nat:PREROUTING</programlisting>
<important>
<para>There is no rate limiting on these logging rules so use
LOGALLNEW at your own risk; it may cause high CPU and disk
utilization and you may not be able to control your firewall after
you enable this option.</para>
</important>
<caution>
<para><emphasis role="bold">DO NOT USE THIS OPTION IF THE
RESULTING LOG MESSAGES WILL BE SENT TO ANOTHER
SYSTEM.</emphasis></para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term>DYNAMIC_ZONES</term>
<listitem>
<para>(Added at version 2.0.2) - When set to Yes or yes, enables
<ulink url="IPSEC.htm">dynamic zones</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CONFIG_PATH</term>
<listitem>
<para>(Added at version 2.0.2) - Specifies where configuration files
other than <filename>shorewall.conf</filename> may be found.
CONFIG_PATH is specifies as a list of directory names separated by
colons (":"). When looking for a configuration file other than
shorewall.conf:</para>
<itemizedlist>
<listitem>
<para>If the command is "try" or if "-c &lt;configuration
directory&gt;" was specified in the command then the directory
given in the command is searched first.</para>
</listitem>
<listitem>
<para>Next, each directory in the CONFIG_PATH setting is
searched in sequence.</para>
</listitem>
</itemizedlist>
<para>If CONFIG_PATH is not given or if it is set to the empty value
then the contents of
<filename>/usr/share/shorewall/configpath</filename> are used. As
released from shorewall.net, that file sets the CONFIG_PATH to
<emphasis role="bold">/etc/shorewall:/usr/share/shorewall
</emphasis>but your particular distribution may set it
differently.</para>
<para>Note that the setting in
<filename>/usr/share/shorewall/configpath</filename> is always used
to locate <filename>shorewall.conf</filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PKTTYPE</term>
<listitem>
<para>(Added at Version 2.0.6) - Normally Shorewall attempts to use
the iptables packet type match extension to determine broadcast and
multicast packets.</para>
<orderedlist>
<listitem>
<para>This can cause a message to appear during
<command>shorewall start</command> (modprobe: cant locate module
ipt_pkttype).</para>
</listitem>
<listitem>
<para>Some users have found problems with the packet match
extension with the result that their firewall log is flooded
with messages relating to broadcast packets.</para>
</listitem>
</orderedlist>
<para>If you are experiencing either of these problems, setting
PKTTYPE=No will prevent Shorewall from trying to use the packet type
match extension and to use IP address matching to determine which
packets are broadcasts or multicasts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RESTOREFILE</term>
<listitem>
<para>(Added at version 2.0.3 Beta 1) - The simple name of a file
in<filename> /var/lib/shorewall</filename> to be used as the default
restore script in the shorewall save, shorewall restore, shorewall
forget and shorewall -f start commands. See the <ulink
url="starting_and_stopping_shorewall.htm">Saved Configuration
documentation</ulink> for details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BRIDGING</term>
<listitem>
<para>(Added at version 2.0.1) - When set to Yes or yes, enables
<ulink url="bridge.html">Shorewall Bridging support</ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SMURF_LOG_LEVEL</term>
<listitem>
<para>(Added at version 2.0.0) - Specifies the logging level for
smurf packets (see the <emphasis role="bold">nosmurfs</emphasis>
option in <link
linkend="Interfaces">/etc/shorewall/interfaces</link>). If set to
the empty value ( SMURF_LOG_LEVEL="" ) then smurfs are not
logged.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MODULE_SUFFIX</term>
<listitem>
<para>(Added at version 1.4.9) - The value of this variable
determines the possible file extensions of kernel modules. The
default value is "o gz ko and o.gz". See <xref linkend="modules" />
for more details.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ADMINISABSENTMINDED</term>
<listitem>
<para>(Added at version 1.4.7) - The value of this variable affects
Shorewall's <ulink url="starting_and_stopping_shorewall.htm">stopped
state</ulink>. When ADMINISABSENTMINDES=No, only traffic to/from
those addresses listed in /etc/shorewall/routestopped is accepted
when Shorewall is stopped. When ADMINISABSENTMINDED=Yes, in addition
to traffic to/from addresses in
<filename>/etc/shorewall/routestopped</filename>, connections that
were active when Shorewall stopped continue to work and all new
connections from the firewall system itself are allowed. If this
variable is not set or is given the empty value then
ADMINISABSENTMINDED=No is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SHOREWALL_SHELL</term>
<listitem>
<para>(Added at version 1.4.6) - This parameter is used to specify
the shell program to be used to interpret the firewall script
(/usr/share/shorewall/firewall). If not specified or specified as a
null value, /bin/sh is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IPTABLES</term>
<listitem>
<para>(Added at version 2.2.0) — This parameter names the iptables
executable to be used by Shorewall. If not specified or if specified
as a null value, then the iptables executable located using the PATH
option is used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGFORMAT</term>
<listitem>
<para>(Added at version 1.4.4) - The value of this variable generate
the --log-prefix setting for Shorewall logging rules. It contains a
<quote>printf</quote> formatting template which accepts three
arguments (the chain name, logging rule number (optional) and the
disposition). To use LOGFORMAT with <ulink
url="http://www.fireparse.com">fireparse</ulink>, set it as:</para>
<programlisting>LOGFORMAT="fp=%s:%d a=%s "</programlisting>
<para>If the LOGFORMAT value contains the substring
<quote>%d</quote> then the logging rule number is calculated and
formatted in that position; if that substring is not included then
the rule number is not included. If not supplied or supplied as
empty (LOGFORMAT="") then <quote>Shorewall:%s:%s:</quote> is
assumed.</para>
<caution>
<para><command>/sbin/shorewall</command> uses the leading part of
the LOGFORMAT string (up to but not including the first
<quote>%</quote>) to find log messages in the <quote>show
log</quote>, <quote>status</quote> and <quote>hits</quote>
commands. This part should not be omitted (the LOGFORMAT should
not begin with <quote>%</quote>) and the leading part should be
sufficiently unique for <command>/sbin/shorewall</command> to
identify Shorewall messages.</para>
</caution>
</listitem>
</varlistentry>
<varlistentry>
<term>CLEAR_TC</term>
<listitem>
<para>(Added at version 1.3.13) - If this option is set to
<quote>No</quote> then Shorewall won't clear the current traffic
control rules during [re]start. This setting is intended for use by
people that prefer to configure traffic shaping when the network
interfaces come up rather than when the firewall is started. If that
is what you want to do, set TC_ENABLED=Yes and CLEAR_TC=No and do
not supply an <filename>/etc/shorewall/tcstart</filename> file. That
way, your traffic shaping rules can still use the
<quote>fwmark</quote> classifier based on packet marking defined in
/etc/shorewall/tcrules. If not specified, CLEAR_TC=Yes is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MARK_IN_FORWARD_CHAIN</term>
<listitem>
<para>(Added at version 1.3.12) - If your kernel has a FORWARD chain
in the mangle table, you may set MARK_IN_FORWARD_CHAIN=Yes to cause
the marking specified in the <ulink
url="traffic_shaping.htm#tcrules">tcrules file</ulink> to occur in
that chain rather than in the PREROUTING chain. This permits you to
mark inbound traffic based on its destination address when SNAT or
Masquerading are in use. To determine if your kernel has a FORWARD
chain in the mangle table, use the <quote><command>/sbin/shorewall
show mangle</command></quote> command; if a FORWARD chain is
displayed then your kernel will support this option. If this option
is not specified or if it is given the empty value (e.g.,
MARK_IN_FORWARD_CHAIN="") then MARK_IN_FORWARD_CHAIN=No is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RFC1918_LOG_LEVEL</term>
<listitem>
<para>(Added at version 1.3.12) - This parameter determines the
level at which packets logged under the <link
linkend="rfc1918"><quote>norfc1918</quote> mechanism</link> are
logged. The value must be a valid <ulink
url="shorewall_logging.html">syslog level</ulink> and if no level is
given, then info is assumed. Prior to Shorewall version 1.3.12,
these packets are always logged at the info level.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BOGON_LOG_LEVEL</term>
<listitem>
<para>(Added at version 2.0.1) - This parameter determines the level
at which packets logged under the <link
linkend="rfc1918"><quote>nobogons</quote> mechanism</link> are
logged. The value must be a valid <ulink
url="shorewall_logging.html">syslog level</ulink> and if no level is
given, then info is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TCP_FLAGS_DISPOSITION</term>
<listitem>
<para>(Added in Version 1.3.11) - Determines the disposition of TCP
packets that fail the checks enabled by the <link
linkend="Interfaces">tcpflags</link> interface option and must have
a value of ACCEPT (accept the packet), REJECT (send an RST response)
or DROP (ignore the packet). If not set or if set to the empty value
(e.g., TCP_FLAGS_DISPOSITION="") then TCP_FLAGS_DISPOSITION=DROP is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TCP_FLAGS_LOG_LEVEL</term>
<listitem>
<para>(Added in Version 1.3.11) - Determines the <ulink
url="shorewall_logging.html">syslog level</ulink> for logging
packets that fail the checks enabled by the <link
linkend="Interfaces">tcpflags</link> interface option. The value
must be a valid syslogd log level. If you don't want to log these
packets, set to the empty value (e.g.,
TCP_FLAGS_LOG_LEVEL="").</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MACLIST_DISPOSITION</term>
<listitem>
<para>(Added in Version 1.3.10) - Determines the disposition of
connections requests that fail <ulink url="MAC_Validation.html">MAC
Verification</ulink> and must have the value ACCEPT (accept the
connection request anyway), REJECT (reject the connection request)
or DROP (ignore the connection request). If not set or if set to the
empty value (e.g., MACLIST_DISPOSITION="") then
MACLIST_DISPOSITION=REJECT is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>MACLIST_LOG_LEVEL</term>
<listitem>
<para>(Added in Version 1.3.10) - Determines the <ulink
url="shorewall_logging.html">syslog level</ulink> for logging
connection requests that fail <ulink url="MAC_Validation.html">MAC
Verification</ulink>. The value must be a valid syslogd log level.
If you don't want to log these connection requests, set to the empty
value (e.g., MACLIST_LOG_LEVEL="").</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NEWNOTSYN</term>
<listitem>
<para>(Added in Version 1.3.8) - When set to <quote>Yes</quote> or
<quote>yes</quote>, Shorewall will filter TCP packets that are not
part of an established connection and that are not SYN packets (SYN
flag on - ACK flag off). If set to <quote>No</quote>, Shorewall will
silently drop such packets. If not set or set to the empty value
(e.g., <quote>NEWNOTSYN=</quote>), NEWNOTSYN=No is assumed.</para>
<para>If you have a HA setup with failover to another firewall, you
should have NEWNOTSYN=Yes on both firewalls. You should also select
NEWNOTSYN=Yes if you have asymmetric routing.</para>
<note>
<para>I find that NEWNOTSYN=No tends to result in lots of "stuck"
connections because any network timeout during TCP session tear
down results in retries being dropped (Netfilter has removed the
connection from the conntrack table but the end-points haven't
completed shutting down the connection). I therefore have chosen
NEWNOTSYN=Yes as the default value and I advise caution in using
NEWNOTSYN=Yes.</para>
<para>If you are looking for a way to defeat "stealth TCP scans"
then I recommend the <emphasis role="bold">tcpflags</emphasis>
interface option in <link
linkend="Interfaces">/etc/shorewall/interfaces</link> rather than
NEWNOTSYN=No.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGNEWNOTSYN</term>
<listitem>
<para>(Added in Version 1.3.6) - Beginning with version 1.3.6,
Shorewall drops non-SYN TCP packets that are not part of an existing
connection. If you would like to log these packets, set LOGNEWNOTSYN
to the <ulink url="shorewall_logging.html">syslog level</ulink> at
which you want the packets logged. Example:
LOGNEWNOTSYN=ULOG|</para>
<note>
<para>Packets logged under this option are usually the result of a
"stuck" connection rather than as the result of an attempt to
breach your firewall.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>LOG_MARTIANS</term>
<listitem>
<para>(Added in Version 2.2.0) - If set to Yes or yes, sets
<filename>/proc/sys/net/ipv4/conf/all/log_martians</filename> and
<filename>/proc/sys/net/ipv4/conf/default/log_martians</filename> to
1. Default is which sets both of the above to zero. If you do not
enable martian logging for all interfaces, you may still enable it
for individual interfaces using the <emphasis
role="bold">logmartians</emphasis> interface option in <link
linkend="Interfaces">/etc/shorewall/interfaces</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DETECT_DNAT_ADDRS</term>
<listitem>
<para>(Added in Version 1.3.4) - If set to <quote>Yes</quote> or
<quote>yes</quote>, Shorewall will detect the first IP address of
the interface to the source zone and will include this address in
DNAT rules as the original destination IP address. If set to
<quote>No</quote> or <quote>no</quote>, Shorewall will not detect
this address and any destination IP address will match the DNAT
rule. If not specified or empty,
<quote>DETECT_DNAT_ADDRS=Yes</quote> is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NAT_BEFORE_RULES</term>
<listitem>
<para>If set to <quote>No</quote> or <quote>no</quote>, port
forwarding rules can override the contents of the <xref
linkend="NAT" /> file. If set to <quote>Yes</quote> or
<quote>yes</quote>, port forwarding rules cannot override one-to-one
NAT. If not set or set to an empty value, <quote>Yes</quote> is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>FW</term>
<listitem>
<para>This parameter specifies the name of the firewall zone. If not
set or if set to an empty string, the value <quote>fw</quote> is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SUBSYSLOCK</term>
<listitem>
<para>This parameter should be set to the name of a file that the
firewall should create if it starts successfully and remove when it
stops. Creating and removing this file allows Shorewall to work with
your distribution's initscripts. For RedHat, this should be set to
/var/lock/subsys/shorewall. For Debian, the value is
/var/state/shorewall and in LEAF it is /var/run/shorwall. Example:
SUBSYSLOCK=/var/lock/subsys/shorewall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>STATEDIR</term>
<listitem>
<para>This parameter specifies the name of a directory where
Shorewall stores state information. If the directory doesn't exist
when Shorewall starts, it will create the directory. Example:
STATEDIR=/tmp/shorewall.</para>
<note>
<para>If you change the STATEDIR variable while the firewall is
running, create the new directory if necessary then copy the
contents of the old directory to the new directory.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>MODULESDIR</term>
<listitem>
<para>This parameter specifies the directory where your kernel
netfilter modules may be found. If you leave the variable empty,
Shorewall will supply the value "/lib/modules/`uname
-r`/kernel/net/ipv4/netfilter.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGRATE and LOGBURST</term>
<listitem>
<para>These parameters set the match rate and initial burst size for
logged packets. Please see the iptables man page for a description
of the behavior of these parameters (the iptables option --limit is
set by LOGRATE and --limit-burst is set by LOGBURST). If both
parameters are set empty, no rate-limiting will occur.</para>
<example>
<title></title>
<programlisting>LOGRATE=10/minute
LOGBURST=5</programlisting>
<para>For each logging rule, the first time the rule is reached,
the packet will be logged; in fact, since the burst is 5, the
first five packets will be logged. After this, it will be 6
seconds (1 minute divided by the rate of 10) before a message will
be logged from the rule, regardless of how many packets reach it.
Also, every 6 seconds which passes without matching a packet, 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>
</example>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGFILE</term>
<listitem>
<para>This parameter tells the /sbin/shorewall program where to look
for Shorewall messages when processing the <quote>show log</quote>,
<quote>monitor</quote>, <quote>status</quote> and
<quote>hits</quote> commands. If not assigned or if assigned an
empty value, /var/log/messages is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>IP_FORWARDING</term>
<listitem>
<para>This parameter determines whether Shorewall enables or
disables IPV4 Packet Forwarding (/proc/sys/net/ipv4/ip_forward).
Possible values are:</para>
<variablelist>
<varlistentry>
<term>On or on</term>
<listitem>
<para>packet forwarding will be enabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Off or off</term>
<listitem>
<para>packet forwarding will be disabled.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Keep or keep</term>
<listitem>
<para>Shorewall will neither enable nor disable packet
forwarding.</para>
</listitem>
</varlistentry>
</variablelist>
<para>If this variable is not set or is given an empty value
(IP_FORWARD="") then IP_FORWARD=On is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ADD_IP_ALIASES</term>
<listitem>
<para>This parameter determines whether Shorewall automatically adds
the <emphasis>external</emphasis> address(es) in <xref
linkend="NAT" />. If the variable is set to <quote>Yes</quote> or
<quote>yes</quote> then Shorewall automatically adds these aliases.
If it is set to <quote>No</quote> or <quote>no</quote>, you must add
these aliases yourself using your distribution's network
configuration tools.</para>
<para>If this variable is not set or is given an empty value
(ADD_IP_ALIASES="") then ADD_IP_ALIASES=Yes is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ADD_SNAT_ALIASES</term>
<listitem>
<para>This parameter determines whether Shorewall automatically adds
the SNAT <emphasis>ADDRESS</emphasis> in <xref linkend="Masq" />. If
the variable is set to <quote>Yes</quote> or <quote>yes</quote> then
Shorewall automatically adds these addresses. If it is set to
<quote>No</quote> or <quote>no</quote>, you must add these addresses
yourself using your distribution's network configuration
tools.</para>
<para>If this variable is not set or is given an empty value
(ADD_SNAT_ALIASES="") then ADD_SNAT_ALIASES=No is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>RETAIN_ALIASES</term>
<listitem>
<para>(Added in 2.2.0) - During "shorewall start", IP addresses to
be added as a consequence of ADD_IP_ALIASES=Yes and
ADD_SNAT_ALIASES=Yes are quietly deleted when <link
linkend="NAT">/etc/shorewall/nat</link> and <link
linkend="Masq">/etc/shorewall/masq</link> are processed then are
re-added later. This is done to help ensure that the addresses can
be added with the specified labels but can have the undesirable side
effect of causing routes to be quietly deleted. When RETAIN_ALIASES
is set to Yes, existing addresses will not be deleted. Regardless of
the setting of RETAIN_ALIASES, addresses added during "shorewall
start" are still deleted at a subsequent "shorewall stop" or
"shorewall restart".</para>
</listitem>
</varlistentry>
<varlistentry>
<term>LOGUNCLEAN</term>
<listitem>
<para>This parameter determines the logging level of mangled/invalid
packets controlled by the <quote>dropunclean" and
"logunclean</quote> interface options. If LOGUNCLEAN is empty
(LOGUNCLEAN=) then packets selected by <quote>dropclean</quote> are
dropped silently (<quote>logunclean</quote> packets are logged under
the <quote>info</quote> log level). Otherwise, these packets are
logged at the specified level (Example: LOGUNCLEAN=debug).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BLACKLIST_DISPOSITION</term>
<listitem>
<para>This parameter determines the disposition of packets from
blacklisted hosts. It may have the value DROP if the packets are to
be dropped or REJECT if the packets are to be replied with an ICMP
port unreachable reply or a TCP RST (tcp only). If you do not assign
a value or if you assign an empty value then DROP is assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>BLACKLIST_LOGLEVEL</term>
<listitem>
<para>This parameter determines if packets from blacklisted hosts
are logged and it determines the syslog level that they are to be
logged at. Its value is a <ulink url="shorewall_logging.html">syslog
level</ulink> (Example: BLACKLIST_LOGLEVEL=debug). If you do not
assign a value or if you assign an empty value then packets from
blacklisted hosts are not logged.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DELAYBLACKLISTLOAD</term>
<listitem>
<para>(Added in Shorewall 2.2.0) - Users with a large static black
list (<filename>/etc/shorewall/blacklist</filename>) may want to set
the DELAYBLACKLISTLOAD option to Yes. When DELAYBLACKLISTLOAD=Yes,
Shorewall will enable new connections before loading the blacklist
rules. While this may allow connections from blacklisted hosts to
slip by during construction of the blacklist, it can substantially
reduce the time that all new connections are disabled during
<command>shorewall [re]start</command>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CLAMPMSS</term>
<listitem>
<para>This parameter enables the TCP Clamp MSS to PMTU feature of
Netfilter and is usually required when your internet connection is
through PPPoE or PPTP. If set to <quote>Yes</quote> or
<quote>yes</quote>, the feature is enabled. If left blank or set to
<quote>No</quote> or <quote>no</quote>, the feature is not
enabled.</para>
<note>
<para>This option requires CONFIG_IP_NF_TARGET_TCPMSS <ulink
url="kernel.htm">in your kernel</ulink>.</para>
</note>
<para>Beginning with Shorewall version 2.2.0, you may also set
CLAMPMSS to a numeric value (e.g., CLAMPMSS=1400). This will set the
MSS field in TCP SYN packets going through the firewall to the value
that you specify.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ROUTE_FILTER</term>
<listitem>
<para>If this parameter is given the value <quote>Yes</quote> or
<quote>yes</quote> then route filtering (anti-spoofing) is enabled
on all network interfaces which are brought up while Shorewall is in
the started state. The default value is <quote>no</quote>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section id="modules" xreflabel="/etc/shorewall/modules">
<title>/etc/shorewall/modules Configuration</title>
<para>The file <filename>/etc/shorewall/modules</filename> contains
commands for loading the kernel modules required by Shorewall-defined
firewall rules. Shorewall will source this file during start/restart
provided that it exists and that the directory specified by the MODULESDIR
parameter exists (see <xref linkend="Conf" /> above).</para>
<para>The file that is released with Shorewall calls the Shorewall
function <quote>loadmodule</quote> for the set of modules that I
load.</para>
<para>The <emphasis>loadmodule</emphasis> function is called as
follows:</para>
<programlisting>loadmodule &lt;<emphasis>modulename</emphasis>&gt; [ &lt;<emphasis>module parameters</emphasis>&gt; ]</programlisting>
<para>where</para>
<variablelist>
<varlistentry>
<term>&lt;<emphasis>modulename</emphasis>&gt;</term>
<listitem>
<para>is the name of the modules without the trailing
<quote>.o</quote> (example ip_conntrack).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&lt;<emphasis>module parameters</emphasis>&gt;</term>
<listitem>
<para>Optional parameters to the insmod utility.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The function determines if the module named by
&lt;<emphasis>modulename</emphasis>&gt; is already loaded and if not then
the function determines if the <quote>.o</quote> file corresponding to the
module exists in the <emphasis>&lt;moduledirectory&gt;</emphasis>; if so,
then the following command is executed:</para>
<programlisting>insmod <emphasis>&lt;moduledirectory</emphasis>&gt;/&lt;<emphasis>modulename</emphasis>&gt;.o &lt;<emphasis>module parameters</emphasis>&gt;</programlisting>
<para>If the file doesn't exist, the function determines of the
<quote>.o.gz</quote> file corresponding to the module exists in the
<emphasis>moduledirectory</emphasis>. If it does, the function assumes
that the running configuration supports compressed modules and execute the
following command:</para>
<programlisting>insmod <emphasis>&lt;moduledirectory</emphasis>&gt;/&lt;<emphasis>modulename</emphasis>&gt;.o.gz &lt;<emphasis>module parameters</emphasis>&gt;</programlisting>
<para>Beginning with the 1.4.9 Shorewall release, the value of the
MODULE_SUFFIX option in determines which files the loadmodule function
looks for if the named module doesn't exist. For each file
<emphasis>&lt;extension&gt;</emphasis> listed in MODULE_SUFFIX (default "o
gz ko o.gz"), the function will append a period (".") and the extension
and if the resulting file exists then the following command will be
executed:</para>
<programlisting>insmod <emphasis>moduledirectory</emphasis>/&lt;<emphasis>modulename</emphasis>&gt;.<emphasis>&lt;extension&gt;</emphasis> &lt;<emphasis>module parameters</emphasis>&gt;</programlisting>
</section>
<section id="TOS" xreflabel="/etc/shorewall/tos">
<title>/etc/shorewall/tos Configuration</title>
<para>The <filename>/etc/shorewall/tos</filename> file allows you to set
the Type of Service field in packet headers based on packet source, packet
destination, protocol, source port and destination port. In order for this
file to be processed by Shorewall, you must have mangle support
enabled.</para>
<para>Entries in the file have the following columns:</para>
<variablelist>
<varlistentry>
<term>SOURCE</term>
<listitem>
<para>The source zone. May be qualified by following the zone name
with a colon (<quote>:</quote>) and either an IP address, an IP
subnet, a MAC address <ulink
url="configuration_file_basics.htm#MAC">in Shorewall Format</ulink>
or the name of an interface. This column may also contain the name
of the firewall zone to indicate packets originating on the firewall
itself or <quote>all</quote> to indicate any source.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEST</term>
<listitem>
<para>The destination zone. May be qualified by following the zone
name with a colon (<quote>:</quote>) and either an IP address or an
IP subnet. Because packets are marked prior to routing, you may not
specify the name of an interface. This column may also contain
<quote>all</quote> to indicate any destination.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PROTOCOL</term>
<listitem>
<para>The name of a protocol in <filename>/etc/protocols
</filename>or the protocol's number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>SOURCE PORT(S)</term>
<listitem>
<para>The source port or a port range. For all ports, place a hyphen
(<quote>-</quote>) in this column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DEST PORT(S)</term>
<listitem>
<para>The destination port or a port range. To indicate all ports,
place a hyphen (<quote>-</quote>) in this column.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TOS</term>
<listitem>
<para>The type of service. Must be one of the following:</para>
<simplelist>
<member>Minimize-Delay (16)</member>
<member>Maximize-Throughput (8)</member>
<member>Maximize-Reliability (4)</member>
<member>Minimize-Cost (2)</member>
<member>Normal-Service (0)</member>
</simplelist>
</listitem>
</varlistentry>
</variablelist>
<para><filename>/etc/shorewall/tos</filename> file that is included with
Shorewall</para>
<programlisting>#SOURCE DEST PROTOCOL SOURCE PORTS(S) DEST PORTS(S) TOS
all all tcp - ssh 16
all all tcp ssh - 16
all all tcp - ftp 16
all all tcp ftp - 16
all all tcp - ftp-data 8
all all tcp ftp-data - 8</programlisting>
<warning>
<para>Users have reported that odd routing problems result from adding
the ESP and AH protocols to the <filename>/etc/shorewall/tos</filename>
file.</para>
</warning>
</section>
<section id="Blacklist" xreflabel="/etc/shorewall/blacklist">
<title>/etc/shorewall/blacklist</title>
<para>Each line in <filename>/etc/shorewall/blacklist</filename> contains
an IP address, a MAC address in Shorewall Format or subnet address.</para>
<example>
<title></title>
<programlisting>130.252.100.69
206.124.146.0/24</programlisting>
</example>
<para>Packets <emphasis role="bold">from</emphasis> hosts listed in the
blacklist file will be disposed of according to the value assigned to the
<link linkend="Conf">BLACKLIST_DISPOSITION</link> and <link
linkend="Conf">BLACKLIST_LOGLEVEL</link> variables in
/etc/shorewall/shorewall.conf. Only packets arriving on interfaces that
have the <quote><link linkend="Interfaces">blacklist</link></quote> option
in <filename>/etc/shorewall/interfaces</filename> are checked against the
blacklist. The black list is designed to prevent listed hosts/subnets from
accessing services on <emphasis role="bold">your</emphasis>
network.</para>
<para>Beginning with Shorewall 1.3.8, the blacklist file has three
columns:</para>
<variablelist>
<varlistentry>
<term>ADDRESS/SUBNET</term>
<listitem>
<para>As described above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PROTOCOL</term>
<listitem>
<para>Optional. If specified, only packets specifying this protocol
will be blocked.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PORTS</term>
<listitem>
<para>Optional; may only be given if PROTOCOL is tcp, udp or icmp.
Expressed as a comma-separated list of port numbers or service names
(from /etc/services). If present, only packets destined for the
specified protocol and one of the listed ports are blocked. When the
PROTOCOL is icmp, the PORTS column contains a comma-separated list
of ICMP type numbers or names (see <quote>iptables -h
icmp</quote>).</para>
</listitem>
</varlistentry>
</variablelist>
<para>Shorewall also has a <ulink url="blacklisting_support.htm">dynamic
blacklist capability</ulink>.</para>
<important>
<para>The Shorewall blacklist file is <emphasis
role="bold">NOT</emphasis> designed to police your users' web browsing
-- to do that, I suggest that you install and configure <ulink
url="http://www.squid-cache.org">Squid</ulink> with <ulink
url="http://www.squidguard.org/">SquidGuard</ulink>.</para>
</important>
</section>
<section id="rfc1918" xreflabel="/etc/shorewall/rfc1918">
<title>/etc/shorewall/rfc1918 — Moved to /usr/share/shorewall in Version
2.0.0</title>
<para>This file lists the subnets affected by the <link
linkend="Interfaces">norfc1918 interface option</link>. Columns in the
file are:</para>
<variablelist>
<varlistentry>
<term>SUBNET</term>
<listitem>
<para>The subnet using VLSM notation (e.g., 192.168.0.0/16).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TARGET</term>
<listitem>
<para>What to do with packets to/from the SUBNET:</para>
<variablelist>
<varlistentry>
<term>RETURN</term>
<listitem>
<para>Process the packet normally thru the rules and policies.
See also <link linkend="Conf">RFC1918_STRICT</link>
above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DROP</term>
<listitem>
<para>Silently drop the packet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>logdrop</term>
<listitem>
<para>Log then drop the packet -- see the <link
linkend="Conf">RFC1918_LOG_LEVEL</link> parameter
above.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>If you want to modify this file, DO NOT MODIFY
<filename>/usr/share/shorewall/rfc1918</filename>. Rather copy that file
to <filename>/etc/shorewall/rfc1918 </filename>and modify the copy.</para>
</section>
<section id="Bogons" xreflabel="/etc/shorewall/rfc1918">
<title>/usr/share/shorewall/bogons — Added in Version 2.0.1</title>
<para>This file lists the subnets affected by the <link
linkend="Interfaces">nobogons interface option</link> and <link
linkend="Hosts">nobogons hosts option</link>. Columns in the file
are:</para>
<variablelist>
<varlistentry>
<term>SUBNET</term>
<listitem>
<para>The subnet using VLSM notation (e.g., 192.168.0.0/16).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>TARGET</term>
<listitem>
<para>What to do with packets to/from the SUBNET:</para>
<variablelist>
<varlistentry>
<term>RETURN</term>
<listitem>
<para>Process the packet normally thru the rules and
policies.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DROP</term>
<listitem>
<para>Silently drop the packet.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>logdrop</term>
<listitem>
<para>Log then drop the packet -- see the <link
linkend="Conf">BOGONS_LOG_LEVEL</link> parameter above.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
<para>If you want to modify this file, DO NOT MODIFY
<filename>/usr/share/shorewall/bogons</filename>. Rather copy that file to
<filename>/etc/shorewall/bogons </filename>and modify the copy.</para>
</section>
<section id="Netmap">
<title>/etc/shorewall/netmap (Added in Version 2.0.1)</title>
<para>Network mapping is defined using the
<filename>/etc/shorewall/netmap</filename> file. Columns in this file
are:</para>
<variablelist>
<varlistentry>
<term>TYPE</term>
<listitem>
<para>Must be DNAT or SNAT.</para>
<para>If DNAT, traffic entering INTERFACE and addressed to NET1 has
it's destination address rewritten to the corresponding address in
NET2.</para>
<para>If SNAT, traffic leaving INTERFACE with a source address in
NET1 has it's source address rewritten to the corresponding address
in NET2.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NET1</term>
<listitem>
<para>Must be expressed in CIDR format (e.g.,
192.168.1.0/24).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>A firewall interface. This interface must have been defined in
<ulink
url="Documentation.htm#Interfaces"><filename>/etc/shorewall/interfaces</filename></ulink>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>NET2</term>
<listitem>
<para>A second network expressed in CIDR format.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For more information, see the <ulink url="netmap.html">Network
Mapping documentation</ulink>.</para>
</section>
<section id="Routestopped" xreflabel="/etc/shorewall/routestopped">
<title>/etc/shorewall/routestopped (Added in Version 1.3.4)</title>
<para>This file defines the hosts that are accessible from the firewall
when the firewall is stopped. Beginning with Shorewall version 2.2.3,
entries in this file are also active while Shorewall is being
[re]started.</para>
<para>Columns in the file are:</para>
<variablelist>
<varlistentry>
<term>INTERFACE</term>
<listitem>
<para>The firewall interface through which the host(s) communicate
with the firewall.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HOST(S) - (Optional)</term>
<listitem>
<para>A comma-separated list of IP/Subnet addresses. If not supplied
or supplied as <quote>-</quote> then 0.0.0.0/0 is assumed.</para>
</listitem>
</varlistentry>
</variablelist>
<example>
<title>When your firewall is stopped, you want firewall accessibility
from local hosts 192.168.1.0/24 and from your DMZ. Your DMZ interfaces
through eth1 and your local hosts through eth2.</title>
<programlisting>#INTERFACE HOST(S)
eth2 192.168.1.0/24
eth1 -</programlisting>
</example>
<para></para>
<note>
<para>Prior to Shorewall version 2.2.3, the contents of the
<filename>/etc/shorewall/routestopped</filename> file did NOT affect
connection attempts occurring during the processing of the
<command>shorewall start</command> and <command>shorewall
restart</command> commands. Beginning with version 2.2.3, Shorewall
allows connections defined by the contents of
<filename>/etc/shorewall/routestopped</filename> during the potentially
lengthy processing of those commands.</para>
</note>
</section>
<section id="Maclist" xreflabel="/etc/shorewall/maclist">
<title>/etc/shorewall/maclist (Added in Version 1.3.10)</title>
<para>This file is described in the <ulink url="MAC_Validation.html">MAC
Validation Documentation</ulink>.</para>
</section>
<section id="ECN" xreflabel="/etc/shorewall/ecn">
<title>/etc/shorewall/ecn (Added in Version 1.4.0)</title>
<para>This file is described in the <ulink url="ECN.html">ECN Control
Documentation</ulink>.</para>
</section>
<section id="Accounting" xreflabel="/usr/shorewall/accounting">
<title>/etc/shorewall/accounting</title>
<para>This file is described in the <ulink url="Accounting.html">Traffic
Accounting Documentation</ulink>.</para>
</section>
<section id="Ipsec">
<title>/etc/shorewall/ipsec (Added in Version 2.1.6)</title>
<para>This file is used to identify the Security Associations used to
encrypt traffic to hosts in a zone and to decrypt traffic from hosts in a
zone. Use of this file requires a 2.6 kernel that includes the
IPSEC-Netfilter patches and the policy match patch. Your iptables must
also support policy match. For additional information, see the <ulink
url="IPSEC-2.6.html">Shorewall Kernel 2.6 IPSEC
documentation</ulink>.</para>
<para></para>
<para>Columns are:</para>
<glosslist>
<glossentry>
<glossterm>ZONE</glossterm>
<glossdef>
<para>The name of a zone defined in /etc/shorewall/zones.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>IPSEC</glossterm>
<glossdef>
<simplelist>
<member>Yes - All traffic to/from this zone is encrypted.</member>
<member>No - Only traffic to/from some of the hosts in this zone
is encrypted. Those encrypted hosts are designated using the
<emphasis role="bold">ipsec</emphasis> option in <link
linkend="Hosts">/etc/shorewall/hosts</link>.</member>
</simplelist>
</glossdef>
</glossentry>
<glossentry>
<glossterm>OPTIONS, IN OPTIONS, OUT OPTIONS</glossterm>
<glossdef>
<para>Optional parameters that identify the security policy and
security associations used in communication with hosts in this zone.
A comma-separated list of the following:</para>
<simplelist>
<member><emphasis
role="bold">proto[!]=ah|esp|ipcomp</emphasis></member>
<member><emphasis
role="bold">mode[!]=transport|tunnel</emphasis></member>
<member><emphasis
role="bold">reqid[!]=&lt;<emphasis>number</emphasis>&gt;</emphasis>
— A number assigned to a security policy using the
unique:&lt;number&gt; as the SPD level. See setkey(8).</member>
<member><emphasis
role="bold">tunnel-src[!]=&lt;<emphasis>address</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;]</emphasis>
— Tunnel Source; may only be included with mode=tunnel. Since
tunnel source and destination are dependent on the direction of
the traffic, this option and the following one should only be
included in the IN OPTIONS and OUT OPTIONS columns.</member>
<member><emphasis
role="bold">tunnel-dst[!]=&lt;<emphasis>address</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;]
</emphasis>— Tunnel Destination; may only be included with
mode=tunnel.</member>
<member><emphasis role="bold">mss</emphasis>=&lt;number&gt; — Sets
the MSS field in TCP syn packets forwarded to/from this zone. May
be used to compensate for the lack of IPSEC pseudo-devices with
their own MTU in the 2.6 Kernel IPSEC implementation. If specified
in the IN OPTIONS, TCP SYN packets from the zone will have MSS
altered; if specified in the OUT OPTIONS, TCP SYN packets to the
zone will have MSS altered.</member>
<member><emphasis
role="bold">spi[!]=&lt;<emphasis>number</emphasis>&gt;</emphasis>
— The security parameter index of the Security Association. Since
a different SA is used for incoming and outgoing traffic, this
option should only be listed in the IN OPTIONS and OUT OPTIONS
columns.</member>
<member><emphasis role="bold">strict</emphasis> — Must be
specified when SPD rules are used (e.g., esp encapsulated with
ah).</member>
<member><emphasis role="bold">next</emphasis> — Separates rules
when strict is used.</member>
</simplelist>
</glossdef>
</glossentry>
</glosslist>
<para>See the<ulink url="IPSEC-2.6.html"> IPSEC with 2.6 Kernel
documentation</ulink> for further information.</para>
</section>
<appendix>
<title>Revision History</title>
<para><revhistory>
<revision>
<revnumber>1.24</revnumber>
<date>2005-03-15</date>
<authorinitials>TE</authorinitials>
<revremark>Update for use of /etc/shorewall/routestopped during
[re]start.</revremark>
</revision>
<revision>
<revnumber>1.23</revnumber>
<date>2005-03-10</date>
<authorinitials>TE</authorinitials>
<revremark>Changes for Shorewall 2.2.2.</revremark>
</revision>
<revision>
<revnumber>1.20</revnumber>
<date>2004-10-25</date>
<authorinitials>TE</authorinitials>
<revremark>Changes for Shorewall 2.2 Beta 1.</revremark>
</revision>
<revision>
<revnumber>1.19</revnumber>
<date>2004-09-12</date>
<authorinitials>TE</authorinitials>
<revremark>Changes for Shorewall 2.1.</revremark>
</revision>
<revision>
<revnumber>1.18</revnumber>
<date>2004-08-22</date>
<authorinitials>TE</authorinitials>
<revremark>Add /etc/shorewall/ipsec documentation.</revremark>
</revision>
<revision>
<revnumber>1.17</revnumber>
<date>2004-04-05</date>
<authorinitials>TE</authorinitials>
<revremark>Update for Shorewall 2.0.2</revremark>
</revision>
<revision>
<revnumber>1.16</revnumber>
<date>2004-03-17</date>
<authorinitials>TE</authorinitials>
<revremark>Clarified LOGBURST and LOGLIMIT.</revremark>
</revision>
<revision>
<revnumber>1.15</revnumber>
<date>2004-02-16</date>
<authorinitials>TE</authorinitials>
<revremark>Move the rfc1918 file to
/usr/share/shorewall.</revremark>
</revision>
<revision>
<revnumber>1.14</revnumber>
<date>2004-02-13</date>
<authorinitials>TE</authorinitials>
<revremark>Add a note about the order of rules.</revremark>
</revision>
<revision>
<revnumber>1.13</revnumber>
<date>2004-02-03</date>
<authorinitials>TE</authorinitials>
<revremark>Update for Shorewall 2.0.</revremark>
</revision>
<revision>
<revnumber>1.12</revnumber>
<date>2004-01-21</date>
<authorinitials>TE</authorinitials>
<revremark>Add masquerade destination list.</revremark>
</revision>
<revision>
<revnumber>1.12</revnumber>
<date>2004-01-18</date>
<authorinitials>TE</authorinitials>
<revremark>Correct typo.</revremark>
</revision>
<revision>
<revnumber>1.11</revnumber>
<date>2004-01-05</date>
<authorinitials>TE</authorinitials>
<revremark>Standards Compliance</revremark>
</revision>
<revision>
<revnumber>1.10</revnumber>
<date>2004-01-05</date>
<authorinitials>TE</authorinitials>
<revremark>Improved formatting of DNAT- and REDIRECT- for
clarity</revremark>
</revision>
<revision>
<revnumber>1.9</revnumber>
<date>2003-12-25</date>
<authorinitials>MN</authorinitials>
<revremark>Initial Docbook Conversion Complete</revremark>
</revision>
</revhistory></para>
</appendix>
</article>
View Git Blame Copy Permalink