shorewall_code/docs/Documentation.xml

<?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 3.x Reference</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate>2006-05-07</pubdate>

    <copyright>
      <year>2001-2006</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>

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 3.0 and
    later. If you are running a version of Shorewall earlier than Shorewall
    3.0.0 then please see the documentation for that
    release</emphasis>.</para>
  </caution>

  <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="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="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><ulink url="traffic_shaping.htm">tcdevices</ulink></term>

        <listitem>
          <para>a parameter file in <filename
          class="directory">/etc/shorewall</filename> used to define the
          bandwidth for interfaces on which you want traffic shaping to be
          enabled.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><ulink url="traffic_shaping.htm">tcclasses</ulink></term>

        <listitem>
          <para>a parameter file in <filename
          class="directory">/etc/shorewall</filename> used to define classes
          for traffic shaping.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><ulink url="traffic_shaping.htm">tcstart</ulink></term>

        <listitem>
          <para>a set of shell functions used by Shorewall to setup traffic
          shaping.This file is installed in <filename
          class="directory">/usr/share/shorewall</filename>.</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.</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="CompiledPrograms.html">capabilities</ulink></term>

        <listitem>
          <para>file in /etc/shorewall that is used to define the
          iptables/kernel capabilities of a remote system. The file allows
          firewall scripts compiled on one system to be taylored for a remote
          system where the script will ultimately run.</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 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>TYPE</term>

        <listitem>
          <simplelist>
            <member><emphasis role="bold">ipsec</emphasis> - All traffic
            to/from this zone is encrypted.</member>

            <member><emphasis role="bold">ipv4</emphasis> - By default,
            traffic to/from some of the hosts in this zone is not encrypted.
            Any encrypted hosts are designated using the <emphasis
            role="bold">ipsec</emphasis> option in <link
            linkend="Hosts">/etc/shorewall/hosts</link>.</member>

            <member><emphasis role="bold">firewall</emphasis> - Designates the
            firewall itself. You must have exactly one 'firewall' zone. No
            options are permitted with a 'firewall' zone.</member>
          </simplelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OPTIONS, IN OPTIONS, OUT OPTIONS</term>

        <listitem>
          <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>
        </listitem>
      </varlistentry>
    </variablelist>

    <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>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>arp_ignore[=&lt;<emphasis>number</emphasis>&gt;]</term>

              <listitem>
                <para>respond to arp requests based on the value of
                &lt;<emphasis>number</emphasis>&gt;.</para>

                <para>1 - reply only if the target IP address is local address
                configured on the incoming interface</para>

                <para>2 - reply only if the target IP address is local address
                configured on the incoming interface and both with the
                sender's IP address are part from same subnet on this
                interface</para>

                <para>3 - do not reply for local addresses configured with
                scope host, only resolutions for global and link addresses are
                replied</para>

                <para>4-7 - reserved</para>

                <para>8 - do not reply for all local addresses</para>

                <para>If no &lt;<emphasis>number</emphasis>&gt; is given then
                the value 1 is assumed</para>

                <para><warning>
                    <para><emphasis role="bold">DO NOT SPECIFY arp_ignore FOR
                    ANY INTERFACE INVOLVED IN PROXY ARP</emphasis>.</para>
                  </warning></para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>routeback</term>

              <listitem>
                <para>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>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>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>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>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>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>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>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>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>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>/accept_source_route
                to 1).<emphasis role="bold">Only set this option if you know
                what you are you doing</emphasis>. This might represent a
                security risk and is not usually needed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>upnp</term>

              <listitem>
                <para>Incoming requests from this interface may be remapped
                via <ulink url="UPnP.html">UPNP</ulink> (upnpd).</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; 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>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OPTIONS</term>

        <listitem>
          <para>A comma-separated list of option</para>

          <variablelist>
            <varlistentry>
              <term>routeback</term>

              <listitem>
                <para>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>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</term>

              <listitem>
                <para>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 (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 -- 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>nosmurfs (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>

            <varlistentry>
              <term>ipsec</term>

              <listitem>
                <para>The hosts are accessed via a <ulink
                url="IPSEC-2.6.html">kernel 2.6 ipsec SA</ulink>. Note that if
                the zone named in the ZONE column is specified as an IPSEC
                zone in the <link linkend="Zones">/etc/shorewall/zones</link>
                file then you do NOT need to specify 'ipsec' here.</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,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>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. 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).</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>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>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>
    </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    TYPE        OPTION
$FW      firewall
sam      ipv4
net      ipv4
loc      ipv4</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)
...
ACCEPT+   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,
      simply use multiple ACCEPT+ rules. 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>The /etc/shorewall/rules file may now be into
    <firstterm>sections</firstterm>. Each section is introduced by a line that
    begins with the keyword SECTION which is followed by the section name.
    Sections are as listed below and must appear in the order shown.</para>

    <variablelist>
      <varlistentry>
        <term>ESTABLISHED</term>

        <listitem>
          <para>Rules in this section apply to packets in the ESTABLISHED
          state.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RELATED</term>

        <listitem>
          <para>Rules in this section apply to packets in the RELATED
          state.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NEW</term>

        <listitem>
          <para>Rules in this section apply to packets in the NEW and INVALID
          states.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Rules in the ESTABLISHED and RELATED sections are limited to the
    following ACTIONs:</para>

    <blockquote>
      <para>ACCEPT, DROP, REJECT, QUEUE, LOG and User-defined actions.</para>
    </blockquote>

    <para>Macros may be used in these sections provided that they expand to
    only these ACTIONs. At the end of the ESTABLISHED and RELATED sections,
    there is an implicit ACCEPT rule.</para>

    <para>RESTRICTION: If you specify FASTACCEPT=Yes in
    /etc/shorewall.shorewall.conf then the ESTABLISHED and RELATED sections
    must be empty.</para>

    <caution>
      <para>Unless you understand Netfilter well enough to be comfortable with
      the difference between ESTABLISHED, RELATED, INVALID and NEW connection
      tracking states, you should omit the ESTABLISHED and RELATED sections
      and place all of your rules in the NEW section.</para>
    </caution>

    <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>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>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>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>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>With Shorewall versions prior to 3.2.0, 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>

                  <para>With Shorewall version 3.2.0 and later, this special
                  treatment no longer applies. Rather, use tcp:syn in the
                  PROTOCOL column to acheive this behavior.</para>
                </note>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><ulink url="Actions.html">&lt;defined
              action&gt;</ulink></term>

              <listitem>
                <para>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>

            <varlistentry>
              <term>&lt;macro&gt;</term>

              <listitem>
                <para>The name of a macro defined using a file with name
                macro.&lt;name&gt;. Macro files are usually placed in
                /etc/shorewall but may reside in any directory on the
                CONFIG_PATH.</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. The log level may be optionally followed by a
          <firstterm>log tag</firstterm>. 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".</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). 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). 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).</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>

          <para>In the ESTABLISHED and RELATED sections, may also be "ipp2p",
          "ipp2p:udp", "ipp2p:all"; requires ipp2p match support in your
          kernel and iptables.</para>

          <para>Beginning with Shorewall 3.1, you may also specify "tcp:syn"
          in this column. This is equivalent to "tcp" but also requires that
          the SYN flag be set and the FIN, ACK and RST flags be reset.</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>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RATE LIMIT</term>

        <listitem>
          <para>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 net dmz tcp 80 - - 2/sec:4</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>Output rules from the firewall itself may be restricted to a
          particular user or group.</para>

          <para>The column may contain:</para>

          <programlisting>       [!][&lt;user name or number&gt;][:&lt;group name or number&gt;][+&lt;program name&gt;]</programlisting>

          <para>When this column is non-empty, the rule applies only if the
          program generating the output is running under the effective
          &lt;user&gt; and/or &lt;group&gt; specified (or is NOT running under
          that id if "!" is given).</para>

          <para>Examples:</para>

          <programlisting>joe     #program must be run by joe
:kids   #program must be run by a member of the 'kids' group
!:kids  #program must not be run by a member of the 'kids' group
+upnpd  #program named upnpd (This feature was removed from Netfilter in kernel version 2.6.14).</programlisting>
        </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:</title>

      <programlisting>#ACTION        SOURCE      DEST             PROTO      DEST PORT(S)    ORIGINAL    RATE LIMIT       
#                                                                      DEST
DNAT           net         loc:192.168.1.3  tcp        ssh             -           4/min:8</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). 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>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>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. 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>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.
          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>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>

          <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" />. 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>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. 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</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)</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</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>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>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>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.
          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>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".
          This column's contents are independent of the value in ALL
          INTERFACES.</para>
        </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>VERBOSITY (Added in version 3.2.0)</term>

        <listitem>
          <para>Shorewall has traditionally been very noisy (produced lots of
          output). You may now set the default level of verbosity using the
          VERBOSITY OPTION.</para>

          <para>Values are:</para>

          <simplelist>
            <member>0 — Silent. You may make it more verbose using the -v
            option</member>

            <member>1 — Major progress messages displayed</member>

            <member>2 — All progress messages displayed (old default
            behavior)</member>
          </simplelist>

          <para>If not specified, then 2 is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>IMPLICIT_CONTINUE (Added in version 3.2.0)</term>

        <listitem>
          <para>When this option is set to "Yes", it causes subzones to be
          treated differently with respect to policies.</para>

          <para>Subzones are defined by following their name with ":" and a
          list of parent zones (in /etc/shorewall/zones). Normally, you want
          to have a set of special rules for the subzone and if a connection
          doesn't match any of those subzone-specific rules then you want the
          parent zone rules and policies to be applied. With
          IMPLICIT_CONTINUE=Yes, that happens automatically.</para>

          <para>If IMPLICIT_CONTINUE=No or if IMPLICIT_CONTINUE is not set,
          then subzones are not subject to this special treatment. With
          IMPLICIT_CONTINUE=Yes, an implicit CONTINUE policy may be overridden
          by including an explicit policy (one that does not specify "all" in
          either the SOURCE or the DEST columns).</para>

          <para>Example:</para>

          <blockquote>
            <para><filename>/etc/shorewall/zones</filename>:</para>

            <programlisting>#ZONE      TYPE
prnt       ipv4
chld:prnt  ipv4</programlisting>

            <para>Traffic to/from the <emphasis role="bold">chld</emphasis>
            zone will first pass through the applicable <emphasis
            role="bold">chld</emphasis> rules and if none of those rules match
            then it will be passed through the appropriate <emphasis
            role="bold">prnt</emphasis> rules. If the connection request does
            not match any of the <emphasis role="bold">prnt</emphasis> rules
            then the relevant <emphasis role="bold">prnt</emphasis> policy is
            applied.</para>

            <para>If you want the <emphasis
            role="bold">fw</emphasis>-&gt;<emphasis
            role="bold">chld</emphasis> policy to be ACCEPT, simply add this
            entry to <filename>/etc/shorewall/policy</filename>:</para>

            <programlisting>#SOURCE  DESTINATION        POLICY
$FW      chld               ACCEPT</programlisting>

            <para>Traffic from all other zones to 'chld' will be subject to
            the implicit CONTINUE policy.</para>
          </blockquote>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>HIGH_ROUTE_MARKS (Added in version 3.2.0)</term>

        <listitem>
          <para>Prior to version 3.2.0, it was not possible to use connection
          marking in <filename>/etc/shorewall/tcrules</filename> if you have a
          multi-ISP configuration that uses the <emphasis
          role="bold">track</emphasis> option.</para>

          <para>Beginning with release 3.2.0, you may now set
          HIGH_ROUTE_MARKS=Yes in to effectively divide the packet mark and
          connection mark into two 8-byte mark fields.</para>

          <para>When you do this:</para>

          <orderedlist numeration="loweralpha">
            <listitem>
              <para>The MARK field in the <filename>providers</filename> file
              must have a value that is less than 65536 and that is a multiple
              of 256 (using hex representation, the values are 0x0100-0xFF00
              with the low-order 8 bits being zero).</para>
            </listitem>

            <listitem>
              <para>You may only set those mark values in the PREROUTING
              chain.</para>
            </listitem>

            <listitem>
              <para>Marks used for traffic shaping must still be in the range
              of 1-255 and may still not be set in the PREROUTING
              chain.</para>
            </listitem>

            <listitem>
              <para>When you SAVE or RESTORE in tcrules, only the TC mark
              value is saved or restored. Shorewall handles saving and
              restoring the routing (provider) marks.</para>
            </listitem>
          </orderedlist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FASTACCEPT</term>

        <listitem>
          <para>Normally, Shorewall accepting ESTABLISHED/RELATED packets
          until these packets reach the chain in which the original connection
          was accepted. So for packets going from the 'loc' zone to the 'net'
          zone, ESTABLISHED/RELATED packets are ACCEPTED in the 'loc2net'
          chain.</para>

          <para>If you set FASTACCEPT=Yes, then ESTABLISHED/RELEATED packets
          are accepted early in the INPUT, FORWARD and OUTPUT chains. If you
          set FASTACCEPT=Yes then you may not include rules in the ESTABLISHED
          or RELATED sections of /etc/shorewall/rules.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>STARTUP_ENABLED</term>

        <listitem>
          <para>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>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>MACLIST_TABLE</term>

        <listitem>
          <para>Normally, MAC verification occurs in the filter table (INPUT
          and FORWARD) chains. When forwarding a packet from an interface with
          MAC verification to a bridge interface, that doesn't work.</para>

          <para>This problem can be worked around by setting
          MACLIST_TABLE=mangle which will cause Mac verification to occur out
          of the PREROUTING chain. Because REJECT isn't available in that
          environment, you may not specify MACLIST_DISPOSITION=REJECT with
          MACLIST_TABLE=mangle.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RFC1918_STRICT</term>

        <listitem>
          <para>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>LOGALLNEW</term>

        <listitem>
          <para>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>When set to Yes or yes, enables <ulink url="IPSEC.htm">dynamic
          zones</ulink>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>CONFIG_PATH</term>

        <listitem>
          <para>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>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>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>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>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>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>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>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>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>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>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>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>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.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>TCP_FLAGS_DISPOSITION</term>

        <listitem>
          <para>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>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>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>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>LOG_MARTIANS</term>

        <listitem>
          <para>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>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>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>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>

          <warning>
            <para>Addresses added by ADD_IP_ALIASES=Yes are deleted and
            re-added during <command>shorewall restart</command>. As a
            consequence, connections using those addresses may be
            severed.</para>
          </warning>
        </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>

          <warning>
            <para>Addresses added by ADD_SNAT_ALIASES=Yes are deleted and
            re-added during <command>shorewall restart</command>. As a
            consequence, connections using those addresses may be
            severed.</para>
          </warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RETAIN_ALIASES</term>

        <listitem>
          <para>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>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[=&lt;value&gt;]</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>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>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>Here's a sample <filename>/etc/shorewall/tos</filename> file:</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>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 destination port numbers or
          service names (from /etc/services). If present, only packets
          matching the specified protocol and one of the listed destination
          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>

      <varlistentry>
        <term>OPTIONS</term>

        <listitem>
          <para>(Optional) A comma-separated list of options. The
          currently-supported options are:</para>

          <itemizedlist>
            <listitem>
              <para>routeback - Set up a rule to ACCEPT traffic from these
              hosts back to themselves.</para>
            </listitem>

            <listitem>
              <para>source - Allow traffic from these hosts to ANY
              destination. Without this option or the 'dest option, only
              traffic from this host to other listed hosts (and the firewall)
              is allowed. If 'source' is specified then 'routeback' is
              redundant.</para>
            </listitem>

            <listitem>
              <para>dest - Allow traffic to these hosts from ANY source.
              Without this option or the 'source' option, only traffic from
              this host to other listed hosts (and the firewall) is allowed.
              If 'dest' is specified then 'routeback' is redundant.</para>
            </listitem>

            <listitem>
              <para>critical - Allow traffic between the firewall and these
              hosts throughout '[re]start', 'stop' and 'clear'. Specifying
              'critical' on one or more entries will cause your firewall to be
              "totally open" for a brief window during each of those
              operations.</para>
            </listitem>
          </itemizedlist>

          <note>
            <para>The 'source' and 'dest' options work best when used in
            conjunction with ADMINISABSENTMINDED=Yes in
            /etc/shorewall/shorewall.conf.</para>
          </note>
        </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>/usr/share/shorewall/rfc1918</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="Netmap">
    <title>/etc/shorewall/netmap</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</title>

    <para>This file defines the hosts that are accessible from the firewall
    when the firewall is stopped. Entries in this file are also active while
    Shorewall is being stopped or [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>

    <note>
      <para>Shorewall allows connections defined by the contents of
      <filename>/etc/shorewall/routestopped</filename> during the potentially
      lengthy processing of the commands <command>shorewall start</command>,
      <command>shorewall restart</command>, <command>shorewall try
      </command>and <command>shorewall stop</command>.</para>
    </note>
  </section>

  <section id="Maclist" xreflabel="/etc/shorewall/maclist">
    <title>/etc/shorewall/maclist</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</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>

  <appendix>
    <title>Revision History</title>

    <para><revhistory>
        <revision>
          <revnumber>1.25</revnumber>

          <date>2005-08-28</date>

          <authorinitials>TE</authorinitials>

          <revremark>Changes for 3.0.</revremark>
        </revision>

        <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>