<?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 1.4 Reference</title>

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

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

    <pubdate>2004-01-22</pubdate>

    <copyright>
      <year>2001-2004</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation License</ulink></quote>.</para>
    </legalnotice>

    <abstract>
      <para>This documentation is intended primarily for reference.
      Step-by-step instructions for configuring Shorewall in common setups may
      be found in the <ulink url="shorewall_quickstart_guide.htm">QuickStart
      Guides</ulink>.</para>
    </abstract>
  </articleinfo>

  <section>
    <title>Components</title>

    <para>Shorewall consists of the following components:</para>

    <variablelist>
      <varlistentry>
        <term><link linkend="Variables">params</link></term>

        <listitem>
          <para>a parameter file installed in /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall/ that establishes
          overall firewall policy.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><link linkend="Rules">rules</link></term>

        <listitem>
          <para>a parameter file installed in /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall prior to
          version 1.3.2, in /var/lib/shorewall in version s 1.3.2-1.3.8 and in
          /usr/lib/shorewall in later versions.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><link linkend="modules">modules</link></term>

        <listitem>
          <para>a parameter file installed in /etc/shorewall 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 /etc/shorewall that is used to
          specify how the Type of Service (TOS) field in packets is to be set.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>common.def</term>

        <listitem>
          <para>a parameter file installed in in /etc/shorewall that defines
          firewall-wide rules that are applied before a DROP or REJECT policy
          is applied.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>init.sh</term>

        <listitem>
          <para>a shell script installed in /etc/init.d to automatically start
          Shorewall during boot.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><link linkend="Interfaces">interfaces</link></term>

        <listitem>
          <para>a parameter file installed in /etc/shorewall/ 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 /etc/shorewall/ 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 /etc/shorewall 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 /etc/shorewall.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>firewall</term>

        <listitem>
          <para>a shell program that reads the configuration files in
          /etc/shorewall and configures your firewall. This file is installed
          in /usr/share/shorewall.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><link linkend="NAT">nat</link></term>

        <listitem>
          <para>a parameter file in /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall 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 /etc/shorewall used to define rules for
          classifying packets for <ulink url="traffic_shaping.htm">Traffic
          Shaping/Control</ulink>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><link linkend="Tunnels">tunnels</link></term>

        <listitem>
          <para>a parameter file in /etc/shorewall 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 /sbin
          or in /usr/sbin (the install.sh script and the rpm install this file
          in /sbin).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><ulink url="Accounting.html">accounting</ulink></term>

        <listitem>
          <para>a parameter file in /etc/shorewall used to define traffic
          accounting rules. This file was added in version 1.4.7.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>version</term>

        <listitem>
          <para>a file created in /etc/shorewall/ (/var/lib/shorewall in
          version 1.3.2-1.3.8 and /usr/lib/shorewall beginning in version
          1.3.9) that describes the version of Shorewall installed on your
          system.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><ulink url="UserSets.html">users and usersets</ulink></term>

        <listitem>
          <para>files in /etc/shorewall allowing connections originating on
          the firewall to be policed by the user id and/or group id of the
          user.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><ulink url="User_defined_Actions.html">actions and
        action.template</ulink></term>

        <listitem>
          <para>files in /etc/shorewall that allow you to define your own
          actions for rules in /etc/shorewall/rules.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="Variables" xreflabel="/etc/shorewall/params">
    <title>/etc/shorewall/params</title>

    <para>You may use the file <filename>/etc/shorewall/params</filename> file
    to set shell variables that you can then use in some of the other
    configuration files.</para>

    <para>It is suggested that variable names begin with an upper case letter
    to distinguish them from variables used internally within the Shorewall
    programs</para>

    <example>
      <title>shell variables</title>

      <programlisting>NET_IF=eth0 NET_BCAST=130.252.100.255
NET_OPTIONS=blacklist,norfc1918</programlisting>
    </example>

    <example>
      <title>/etc/shorewall/interfaces record</title>

      <programlisting>net $NET_IF $NET_BCAST $NET_OPTIONS</programlisting>
    </example>

    <para>The result will be the same as if the record had been written</para>

    <programlisting>net eth0 130.252.100.255 blacklist,norfc1918</programlisting>

    <para>Variables may be used anywhere in the other configuration files.</para>
  </section>

  <section id="Zones" xreflabel="/etc/shorewall/zones">
    <title>/etc/shorewall/zones</title>

    <para>This file is used to define the network zones. There is one entry in
    <filename>/etc/shorewall/zones</filename> for each zone; Columns in an
    entry are:</para>

    <variablelist>
      <varlistentry>
        <term>ZONE</term>

        <listitem>
          <para>short name for the zone. The name should be 5 characters or
          less in length (4 characters or less if you are running Shorewall
          1.4.4 or later) and consist of lower-case letters or numbers. Short
          names must begin with a letter and the name assigned to the firewall
          is reserved for use by Shorewall itself. Note that the output
          produced by iptables is much easier to read if you select short
          names that are three characters or less in length. The name
          <quote>all</quote> may not be used as a zone name nor may the zone
          name assigned to the firewall itself via the FW variable in <xref
          linkend="Conf" />.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DISPLAY</term>

        <listitem>
          <para>The name of the zone as displayed during Shorewall startup.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>COMMENTS</term>

        <listitem>
          <para>Any comments that you want to make about the zone. Shorewall
          ignores these comments.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <programlisting>#ZONE      DISPLAY        COMMENTS
net        Net            Internet
loc        Local          Local networks
dmz        DMZ            Demilitarized zone</programlisting>

    <para>You may add, delete and modify entries in the <filename>/etc/shorewall/zones</filename>
    file as desired so long as you have at least one zone defined.</para>

    <warning>
      <para>If you rename or delete a zone, you should perform <quote><command>shorewall
      stop; shorewall start</command></quote> to install the change rather
      than <quote><command>shorewall restart</command></quote>.</para>
    </warning>

    <warning>
      <para>The order of entries in the <filename>/etc/shorewall/zones</filename>
      file is significant <link linkend="Nested">in some cases</link>.</para>
    </warning>
  </section>

  <section id="Interfaces" xreflabel="/etc/shorewall/interfaces">
    <title>/etc/shorewall/interfaces</title>

    <para>This file is used to tell the firewall which of your firewall&#39;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>

          <warning>
            <para><emphasis role="bold">DO NOT INCLUDE THE LOOPBACK INTERFACE
            (lo) IN THIS FILE!!!</emphasis></para>
          </warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>BROADCAST</term>

        <listitem>
          <para>the broadcast address(es) for the sub-network(s) attached to
          the interface. This should be left empty for P-T-P interfaces (ppp*,
          ippp*); if you need to specify options for such an interface, enter
          <quote>-</quote> in this column. If you supply the special value
          <quote>detect</quote> in this column, the firewall will
          automatically determine the broadcast address. In order to use
          <quote>detect</quote>:</para>

          <itemizedlist>
            <listitem>
              <para>the interface must be up before you start your firewall</para>
            </listitem>

            <listitem>
              <para>the interface must only be attached to a single
              sub-network (i.e., there must have a single broadcast address).</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OPTIONS</term>

        <listitem>
          <para>a comma-separated list of options. Possible options include:</para>

          <variablelist>
            <varlistentry>
              <term>arp_filter</term>

              <listitem>
                <para>(Added in version 1.4.7) - This option causes
                <filename>/proc/sys/net/ipv4/conf/&#60;interface&#62;/arp_filter</filename>
                to be set with the result that this interface will only answer
                ARP <quote>who-has</quote> requests from hosts that are routed
                out of that interface. Setting this option facilitates testing
                of your firewall where multiple firewall interfaces are
                connected to the same HUB/Switch (all interface connected to
                the single HUB/Switch should have this option specified). Note
                that using such a configuration in a production environment is
                strongly recommended against.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>newnotsyn</term>

              <listitem>
                <para>(Added in version 1.4.6) - This option overrides <link
                linkend="Conf">NEWNOTSYN=No</link> for packets arriving on
                this interface. In other words, packets coming in on this
                interface are processed as if NEWNOTSYN=Yes had been specified
                in <xref linkend="Conf" />.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>routeback</term>

              <listitem>
                <para>(Added in version 1.4.2) - This option causes Shorewall
                to set up handling for routing packets that arrive on this
                interface back out the same interface. If this option is
                specified, the ZONE column may not contain <quote>-</quote>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>tcpflags</term>

              <listitem>
                <para>(added in version 1.3.11) - This option causes Shorewall
                to make sanity checks on the header flags in TCP packets
                arriving on this interface. Checks include Null flags,
                SYN+FIN, SYN+RST and FIN+URG+PSH; these flag combinations are
                typically used for <quote>silent</quote> port scans. Packets
                failing these checks are logged according to the
                TCP_FLAGS_LOG_LEVEL option in <xref linkend="Conf" /> and are
                disposed of according to the TCP_FLAGS_DISPOSITION option.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>blacklist</term>

              <listitem>
                <para>This option causes incoming packets on this interface to
                be checked against the <link linkend="Blacklist">blacklist</link>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>dhcp</term>

              <listitem>
                <para>The interface is assigned an IP address via DHCP or is
                used by a DHCP server running on the firewall. The firewall
                will be configured to allow DHCP traffic to and from the
                interface even when the firewall is stopped. You may also wish
                to use this option if you have a static IP but you are on a
                LAN segment that has a lot of Laptops that use DHCP and you
                select the <emphasis role="bold">norfc1918</emphasis> option
                (see below).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>norfc1918</term>

              <listitem>
                <para>Packets arriving on this interface and that have a
                source address that is reserved in RFC 1918 or in other RFCs
                will be dropped after being optionally logged. If <link
                linkend="Conf">packet mangling is enabled in
                <filename>/etc/shorewall/shorewall.conf</filename></link> ,
                then packets arriving on this interface that have a
                destination address that is reserved by one of these RFCs will
                also be logged and dropped.</para>

                <para>Addresses blocked by the standard <link
                linkend="rfc1918">rfc1918 file</link> include those addresses
                reserved by RFC1918 plus other ranges reserved by the IANA or
                by other RFCs.</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&#39;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>dropunclean</term>

              <listitem>
                <para>Packets from this interface that are selected by the
                <quote>unclean</quote> match target in iptables will be
                optionally logged and then dropped.</para>

                <warning>
                  <para>This feature requires that UNCLEAN match support be
                  configured in your kernel, either in the kernel itself or as
                  a module. UNCLEAN support is broken in some versions of the
                  kernel but appears to work ok in 2.4.17-rc1.</para>

                  <para><emphasis role="bold">Update 12/17/2001:</emphasis>
                  The unclean match patch from 2.4.17-rc1 is <ulink
                  url="ftp://ftp.shorewall.net/pub/shorewall/misc/unclean.patch">available
                  for download</ulink>. I am currently running this patch
                  applied to kernel 2.4.16.</para>

                  <para><emphasis role="bold">Update 12/20/2001:</emphasis>
                  I&#39;ve seen a number of tcp connection requests with OPT
                  (020405B4<emphasis role="bold">0000080A</emphasis>...) being
                  dropped in the <emphasis>badpkt</emphasis> chain. This
                  appears to be a bug in the remote TCP stack whereby it is
                  8-byte aligning a timestamp (TCP option 8) but rather than
                  padding with 0x01 it is padding with 0x00. It&#39;s a tough
                  call whether to deny people access to your servers because
                  of this rather minor bug in their networking software. If
                  you wish to disable the check that causes these connections
                  to be dropped, <ulink
                  url="ftp://ftp.shorewall.net/pub/shorewall/misc/unclean1.patch">here&#39;s
                  a kernel patch</ulink> against 2.4.17-rc2.</para>
                </warning>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>logunclean</term>

              <listitem>
                <para>This option works like <emphasis role="bold">dropunclean</emphasis>
                with the exception that packets selected by the
                <quote>unclean</quote> match target in iptables are logged
                <emphasis>but not dropped</emphasis>. The level at which the
                packets are logged is determined by the setting of LOGUNCLEAN
                and if LOGUNCLEAN has not been set, <quote>info</quote> is
                assumed.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>proxyarp</term>

              <listitem>
                <para>(Added in version 1.3.5) - This option causes Shorewall
                to set /proc/sys/net/ipv4/conf/&#60;<emphasis>interface</emphasis>&#62;/proxy_arp
                and is used when implementing Proxy ARP Sub-netting as
                described at <ulink
                url="http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/">http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/</ulink>.
                Do <emphasis role="bold">not</emphasis> set this option if you
                are implementing Proxy ARP through entries in <xref
                linkend="ProxyArp" />.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>maclist</term>

              <listitem>
                <para>(Added in version 1.3.10) - If this option is specified,
                all connection requests from this interface are subject to
                <ulink url="MAC_Validation.html">MAC Verification</ulink>. May
                only be specified for ethernet interfaces.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <variablelist>
            <varlistentry>
              <term>detectnets</term>

              <listitem>
                <para>(Added in version 1.4.10) - If this option is specified,
                the zone named in the ZONE column will contain only the hosts
                routed through the interface named in the INTERFACE column.
                <emphasis role="bold">Do not set this option on your external
                (Internet) interface!</emphasis> The interface must be in the
                UP state when Shorewall is [re]started.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <para>My recommendations concerning options:</para>

          <itemizedlist>
            <listitem>
              <para>External Interface -- <emphasis role="bold">tcpflags,blacklist,norfc1918,routefilter</emphasis></para>
            </listitem>

            <listitem>
              <para>Wireless Interface -- <emphasis role="bold">maclist,routefilter,tcpflags,detectnets</emphasis></para>
            </listitem>

            <listitem>
              <para>Don&#39;t use <emphasis role="bold">dropunclean</emphasis>
              -- It&#39;s broken in my opinion</para>
            </listitem>

            <listitem>
              <para>Use <emphasis role="bold">logunclean</emphasis> only when
              you are trying to debug a problem</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 times that you need entries in <filename>/etc/shorewall/hosts</filename>
      are:</para>

      <orderedlist>
        <listitem>
          <para>You have <ulink url="Multiple_Zones.html">more than one zone
          connecting through a single interface</ulink>; or</para>
        </listitem>

        <listitem>
          <para>You have a <ulink url="Shorewall_and_Aliased_Interfaces.html">zone
          that has multiple subnetworks that connect through a single
          interface</ulink> and you want the Shorewall box to route traffic
          between those subnetworks.</para>
        </listitem>
      </orderedlist>

      <para><emphasis role="bold">IF YOU DON&#39;T HAVE EITHER OF THOSE
      SITUATIONS THEN DON&#39;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 a network interface followed by a colon (<quote>:</quote>)
          followed by a comma-separated list either:</para>

          <orderedlist>
            <listitem>
              <para>An IP address (example - eth1:192.168.1.3)</para>
            </listitem>

            <listitem>
              <para>A subnet in CIDR notation (example - eth2:192.168.2.0/24)</para>
            </listitem>
          </orderedlist>

          <para>The interface name much match an entry in
          <filename>/etc/shorewall/interfaces</filename>.</para>

          <warning>
            <para>If you are running a version of Shorewall earlier than
            1.4.6, only a single host/subnet address may be specified in an
            entry in <filename>/etc/shorewall/hosts</filename>.</para>
          </warning>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OPTIONS</term>

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

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

              <listitem>
                <para>(Added in version 1.4.2) - This option causes Shorewall
                to set up handling for routing packets sent by this host group
                back back to the same group.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>maclist</term>

              <listitem>
                <para>Added in version 1.3.10. If specified, connection
                requests from the hosts specified in this entry are subject to
                <ulink url="MAC_Validation.html">MAC Verification</ulink>.
                This option is only valid for ethernet interfaces.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>If you don&#39;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&#39;T want to specify any hosts for your internet
      zone since the hosts that you specify will be the only ones that you
      will be able to access without adding additional rules.</para>
    </note>

    <example>
      <title>Your local interface is eth1 and you have two groups of local
      hosts that you want to make into separate zones:</title>

      <programlisting>192.168.1.0/25 192.168.1.128/25</programlisting>

      <para>Your /etc/shorewall/interfaces file might look like:</para>

      <programlisting>#ZONE    INTERFACE    BROADCAST    OPTIONS
net      eth0         detect       dhcp,norfc1918
-        eth1         192.168.1.127,192.168.1.255</programlisting>

      <para>The <quote>-</quote> in the ZONE column for eth1 tells Shorewall
      that eth1 interfaces to multiple zones.</para>

      <programlisting>#ZONE       HOST(S)               OPTIONS
loc1        eth1:192.168.1.0/25
loc2        eth1:192.168.1.128/25</programlisting>
    </example>

    <example>
      <title>You have local interface eth1 with two IP addresses -
      192.168.1.1/24 and 192.168.12.1/24</title>

      <para>Your /etc/shorewall/interfaces file might look like:</para>

      <programlisting>#ZONE    INTERFACE    BROADCAST    OPTIONS
net      eth0         detect       dhcp,norfc1918
-        eth1         192.168.1.255,192.168.12.255</programlisting>

      <para>Your /etc/shorewall/hosts file might look like:</para>

      <programlisting>#ZONE       HOST(S)               OPTIONS
loc         eth1:192.168.1.0/24
loc         eth1:192.168.12.0/24</programlisting>

      <para>If you are running Shorewall 1.4.6 or later, your hosts file may
      look like:</para>

      <programlisting>#ZONE       HOST(S)               OPTIONS
loc         eth1:192.168.1.0/24,192.168.12.0/24</programlisting>
    </example>

    <section id="Nested">
      <title>Nested and Overlapping Zones</title>

      <para>The <filename>/etc/shorewall/interfaces</filename> and
      <filename>/etc/shorewall/hosts</filename> file allow you to define
      nested or overlapping zones. Such overlapping/nested zones are allowed
      and Shorewall processes zones in the order that they appear in the
      <filename>/etc/shorewall/zones</filename> file. So if you have nested
      zones, you want the sub-zone to appear before the super-zone and in the
      case of overlapping zones, the rules that will apply to hosts that
      belong to both zones is determined by which zone appears first in
      <filename>/etc/shorewall/zones</filename>.</para>

      <para>Hosts that belong to more than one zone may be managed by the
      rules of all of those zones. This is done through use of the special
      <link linkend="CONTINUE">CONTINUE policy</link> described below.</para>
    </section>
  </section>

  <section id="Policy" xreflabel="/etc/shorewall/policy">
    <title>/etc/shorewall/policy Configuration</title>

    <para>This file is used to describe the firewall policy regarding
    establishment of connections. Connection establishment is described in
    terms of <emphasis>clients</emphasis> who initiate connections and
    <emphasis>servers</emphasis> who receive those connection requests.
    Policies defined in <filename>/etc/shorewall/policy </filename>describe
    which zones are allowed to establish connections with other zones.</para>

    <para>Policies established in <filename>/etc/shorewall/policy </filename>can
    be viewed as default policies. If no rule in /etc/shorewall/rules applies
    to a particular connection request then the policy from
    <filename>/etc/shorewall/policy</filename> is applied.</para>

    <para>Five policies are defined:</para>

    <variablelist>
      <varlistentry>
        <term>ACCEPT</term>

        <listitem>
          <para>The connection is allowed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DROP</term>

        <listitem>
          <para>The connection request is ignored.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>REJECT</term>

        <listitem>
          <para>The connection request is rejected with an RST (TCP) or an
          ICMP destination-unreachable packet being returned to the client.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>CONTINUE</term>

        <listitem>
          <para>The connection is neither ACCEPTed, DROPped nor REJECTed.
          CONTINUE may be used when one or both of the zones named in the
          entry are sub-zones of or intersect with another zone. For more
          information, see below.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NONE</term>

        <listitem>
          <para>(Added in version 1.4.1) - Shorewall should not set up any
          infrastructure for handling traffic from the SOURCE zone to the DEST
          zone. When this policy is specified, the <emphasis role="bold">LOG
          LEVEL</emphasis> and <emphasis role="bold">BURST:LIMIT</emphasis>
          columns must be left blank.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>For each policy specified in /etc/shorewall/policy, you can indicate
    that you want a message sent to your system log each time that the policy
    is applied.</para>

    <para>Entries in /etc/shorewall/policy have four columns as follows:</para>

    <variablelist>
      <varlistentry>
        <term>SOURCE</term>

        <listitem>
          <para>The name of a client zone (a zone defined in the <xref
          linkend="Zones" /> file , the <link linkend="Conf">name of the
          firewall zone</link> or <quote>all</quote>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DEST</term>

        <listitem>
          <para>The name of a destination zone (a zone defined in the <xref
          linkend="Zones" /> file , the <link linkend="Conf">name of the
          firewall zone</link> or <quote>all</quote>). Shorewall automatically
          allows all traffic from the firewall to itself so the <link
          linkend="Conf">name of the firewall zone</link> cannot appear in
          both the SOURCE and DEST columns.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>POLICY</term>

        <listitem>
          <para>The default policy for connection requests from the SOURCE
          zone to the DESTINATION zone.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>LOG LEVEL</term>

        <listitem>
          <para>Optional. If left empty, no log message is generated when the
          policy is applied. Otherwise, this column should contain an integer
          or name indicating a <ulink url="shorewall_logging.html">syslog
          level</ulink>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>LIMIT:BURST - optional</term>

        <listitem>
          <para>If left empty, TCP connection requests from the <emphasis
          role="bold">SOURCE</emphasis> zone to the <emphasis role="bold">DEST</emphasis>
          zone will not be rate-limited. Otherwise, this column specifies the
          maximum rate at which TCP connection requests will be accepted
          followed by a colon (<quote>:</quote>) followed by the maximum burst
          size that will be tolerated. Example: <emphasis role="bold">10/sec:40</emphasis>
          specifies that the maximum rate of TCP connection requests allowed
          will be 10 per second and a burst of 40 connections will be
          tolerated. Connection requests in excess of these limits will be
          dropped. See the <link linkend="Rules">rules file documentation</link>
          for an explaination 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>IntraZone Traffic</title>

      <para>Shorewall allows a zone to be associated with more than one
      interface or with multiple networks that interface through a single
      interface. Beginning with Shorewall 1.4.1, Shorewall will ACCEPT all
      traffic from a zone to itself provided that there is no explicit policy
      governing traffic from that zone to itself (an explicit policy does not
      specify <quote>all</quote> in either the SOURCE or DEST column) and that
      there are no rules concerning connections from that zone to itself. If
      there is an explicit policy or if there are one or more rules, then
      traffic within the zone is handled just like traffic between zones is.</para>

      <para>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&#39;t want to route traffic from one ISP to the other through
          your firewall.</para>
        </listitem>

        <listitem>
          <para>Multiple VPN clients. You don&#39;t necessarily want them to
          all be able to communicate between themselves using your
          gateway/router.</para>
        </listitem>
      </orderedlist>
    </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&#39;s look at an
      example:</para>

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

      <programlisting>#ZONE    DISPLAY     COMMENTS
sam      Sam         Sam&#39;s system at home
net      Internet    The Internet
loc      Local       Local Network</programlisting>

      <para><filename>/etc/shorewall/interfaces</filename>:</para>

      <programlisting>#ZONE     INTERFACE     BROADCAST     OPTIONS
-         eth0          detect        dhcp,norfc1918
loc       eth1          detect</programlisting>

      <para><filename>/etc/shorewall/hosts</filename>:</para>

      <programlisting>#ZONE     HOST(S)                     OPTIONS
net       eth0:0.0.0.0/0
sam       eth0:206.191.149.197</programlisting>

      <note>
        <para>Sam&#39;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&#39;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&#39;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&#39;s external IP, he should be connected to the
      firewall itself. Because of the way that Netfilter is constructed, this
      requires two rules as follows:</para>

      <programlisting>#ACTION   SOURCE    DEST            PROTO    DEST PORT(S)
...
DNAT      sam       fw              tcp      ssh
DNAT      net       loc:192.168.1.3 tcp      ssh
...</programlisting>

      <para>The first rule allows Sam SSH access to the firewall. The second
      rule says that any clients from the net zone with the exception of those
      in the <quote>sam</quote> zone should have their connection port
      forwarded to 192.168.1.3. If you need to exclude more than one zone in
      this way, you can list the zones separated by commas (e.g.,
      net!sam,joe,fred). This technique also may be used when the ACTION is
      REDIRECT.</para>
    </section>
  </section>

  <section id="Rules" xreflabel="/etc/shorewall/rules">
    <title>/etc/shorewall/rules</title>

    <para>The <filename>/etc/shorewall/rules</filename> file defines
    exceptions to the policies established in the <filename>/etc/shorewall/policy</filename>
    file. There is one entry in /etc/shorewall/rules for each of these rules.
    Entries in this file only govern the establishment of new connections —
    packets that are part of an existing connection or that establish a
    connection that is related to an existing connection are automatically
    accepted.</para>

    <para>Shorewall automatically enables firewall-&#62;firewall traffic over
    the loopback interface (lo) -- that traffic cannot be regulated using
    rules and any rule that tries to regulate such traffic will generate a
    warning and will be ignored.</para>

    <para>Rules for each pair of zones (source zone, destination zone) are
    evaluated in the order that they appear in the file — the first match
    determines the disposition of the connection request with a couple of
    caveats:</para>

    <itemizedlist>
      <listitem>
        <para>LOG rules cause the connection request to be logged then
        processing continues with the next rule in the file.</para>
      </listitem>

      <listitem>
        <para>QUEUE rules cause the connection request to be passed to
        user-space -- the user-space application can later insert them back
        into the stream for further processing by following rules.</para>
      </listitem>

      <listitem>
        <para>CONTINUE rules may cause the connection request to be
        reprocessed using a different (source zone, destination zone) pair.</para>
      </listitem>
    </itemizedlist>

    <para>Entries in the file have the following columns:</para>

    <variablelist>
      <varlistentry>
        <term>ACTION</term>

        <listitem>
          <variablelist>
            <varlistentry>
              <term>ACCEPT, DROP, REJECT, CONTINUE</term>

              <listitem>
                <para>These have the same meaning here as in the policy file
                above.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>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>REDIRECT</term>

              <listitem>
                <para>Causes the connection request to be redirected to a port
                on the local (firewall) system.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>REDIRECT-</term>

              <listitem>
                <para>The above ACTION (REDIRECT) generates two iptables
                rules:</para>

                <orderedlist>
                  <listitem>
                    <para>a header-rewriting rule in the Netfilter
                    <quote>nat</quote> table</para>
                  </listitem>

                  <listitem>
                    <para>an ACCEPT rule in the Netfilter <quote>filter</quote>
                    table.</para>
                  </listitem>
                </orderedlist>

                <para>REDIRECT- works like REDIRECT but only generates the
                header-rewriting rule.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>LOG</term>

              <listitem>
                <para>Log the packet -- requires a syslog level (see below).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>QUEUE</term>

              <listitem>
                <para>Forward the packet to a user-space application. This
                facility is provided to allow interfacing to <ulink
                url="http://p2pwall.sourceforge.net">ftwall</ulink> for <ulink
                url="Shorewall_and_Kazaa.html">Kazaa filtering</ulink>.</para>

                <note>
                  <para>When the protocol specified in the PROTO column is TCP
                  (<quote>tcp</quote>, <quote>TCP</quote> or <quote>6</quote>),
                  Shorewall will only pass connection requests (SYN packets)
                  to user space. This is for compatibility with ftwall.</para>
                </note>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><ulink url="User_defined_Actions.html">&#60;user-defined
              action&#62;</ulink></term>

              <listitem>
                <para>(Shorewall 1.4.9 and later)</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <para>Beginning with Shorewall version 1.4.7, you may rate-limit the
          rule by optionally following ACCEPT, DNAT[-], REDIRECT[-] or LOG
          with</para>

          <programlisting>      &#60; <emphasis>&#60;rate&#62;</emphasis>/<emphasis>&#60;interval&#62;</emphasis>[:<emphasis>&#60;burst&#62;</emphasis>] &#62;</programlisting>

          <para>where <emphasis>&#60;rate&#62;</emphasis> is the number of
          connections per <emphasis>&#60;interval&#62;</emphasis> (<quote>sec</quote>
          or <quote>min</quote>) and <emphasis>&#60;burst&#62;</emphasis> 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>rate-limit</title>

            <programlisting>ACCEPT&#60;2/sec:4&#62; net dmz tcp 80</programlisting>

            <para>The first time this rule is reached, the packet will be
            accepted; in fact, since the burst is 4, the first four packets
            will be accepted. After this, it will be 500ms (1 second divided
            by the rate of 2) before a packet will be accepted from this rule,
            regardless of how many packets reach it. Also, every 500ms which
            passes without matching a packet, one of the bursts will be
            regained; if no packets hit the rule for 2 second, the burst will
            be fully recharged; back where we started.</para>
          </example>

          <warning>
            <para>When rate limiting is specified on a rule with
            <quote>all</quote> in the SOURCE or DEST fields below, the limit
            will apply to each pair of zones individually rather than as a
            single limit for all pairs of zones covered by the rule.</para>
          </warning>

          <para>Rate limiting may also be specified in the RATE LIMIT column
          below; in that case, it must not be specified as part of the ACTION
          column.</para>

          <para>The ACTION (and rate limit) may optionally be followed by
          <quote>:</quote> and a <ulink url="shorewall_logging.html">syslog
          level</ulink> (example: REJECT:info or
          ACCEPT&#60;2/sec:4&#62;:debugging). 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.</para>

          <para>The use of DNAT or REDIRECT requires that you have NAT
          enabled.</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 or <quote>all</quote>. If the ACTION is
          DNAT or REDIRECT, sub-zones may be excluded from the rule by
          following the initial zone name with <quote>!</quote> and a
          comma-separated list of those sub-zones to be excluded. There is an
          <link linkend="Exclude">example</link> above.</para>

          <para>If the source is not <quote>all</quote> then the source may be
          further restricted by adding a colon (<quote>:</quote>) followed by
          a comma-separated list of qualifiers. Qualifiers are may include:</para>

          <variablelist>
            <varlistentry>
              <term>interface name</term>

              <listitem>
                <para>refers to any connection requests arriving on the
                specified interface (example loc:eth4). Beginning with
                Shorwall 1.3.9, the interface name may optionally be followed
                by a colon (<quote>:</quote>) and an IP address or subnet
                (examples: loc:eth4:192.168.4.22, net:eth0:192.0.2.0/24).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>IP address</term>

              <listitem>
                <para>refers to a connection request from the host with the
                specified address (example net:155.186.235.151). If the ACTION
                is DNAT, this must not be a DNS name.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>MAC Address</term>

              <listitem>
                <para>in <ulink url="configuration_file_basics.htm#MAC">Shorewall
                format</ulink>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>subnet</term>

              <listitem>
                <para>refers to a connection request from any host in the
                specified subnet (example net:155.186.235.0/24).</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>Unlike in the SOURCE column, a range of IP addresses may be
          specified in the DEST column as &#60;<emphasis>first address</emphasis>&#62;-&#60;<emphasis>last
          address</emphasis>&#62;. When the ACTION is DNAT or DNAT-,
          connections will be assigned to the addresses in the range in a
          round-robin fashion (load-balancing). <emphasis role="bold">This
          feature is available with DNAT rules only with Shorewall 1.4.6 and
          later versions; it is available with DNAT- rules in all versions
          that support DNAT-.</emphasis></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>PROTO</term>

        <listitem>
          <para>Protocol. Must be a protocol name from /etc/protocols, a
          number or <quote>all</quote>. Specifies the protocol of the
          connection request.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DEST PORT(S)</term>

        <listitem>
          <para>Port or port range (&#60;low port&#62;:&#60;high port&#62;)
          being connected to. May only be specified if the protocol is tcp,
          udp or icmp. For icmp, this column&#39;s contents are interpreted as
          an icmp type. If you don&#39;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 &#60;low port
          number&#62;:&#60;high port number&#62;). If you don&#39;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>The IP address(es) may be optionally followed by
          <quote>:</quote> and a second IP address. This latter address, if
          present, is used as the source address for packets forwarded to the
          server (This is called <quote>Source NAT</quote> or SNAT.</para>

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

          <note>
            <para>When using SNAT, it is a good idea to qualify the source
            with an IP address or subnet. Otherwise, it is likely that SNAT
            will occur on connections other than those described in the rule.
            The reason for this is that SNAT occurs in the Netfilter
            POSTROUTING hook where it is not possible to restrict the scope of
            a rule by incoming interface.</para>

            <example>
              <title></title>

              <programlisting>#ACTION SOURCE             DEST            PROTO  DEST    SOURCE  ORIGINAL
#                                                 PORT(S) PORT(S) DEST
DNAT    loc:<emphasis role="bold">192.168.1.0/24</emphasis> loc:192.168.1.3 tcp    www     -       206.124.146.179:192.168.1.3</programlisting>
            </example>
          </note>

          <para>If SNAT is not used (no <quote>:</quote> and second IP
          address), the original source address is used. If you want any
          destination address to match the rule but want to specify SNAT,
          simply use a colon followed by the SNAT address.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>Beginning with Shorewall version 1.4.7, you may rate-limit
          ACCEPT, DNAT[-], REDIRECT[-] or LOG rules with an entry in this
          column. Entries have the form</para>

          <programlisting>&#60;rate&#62;/&#60;interval&#62;[:&#60;burst&#62;]</programlisting>

          <para>where &#60;rate&#62; is the number of connections per
          &#60;interval&#62; (<quote>sec</quote> or <quote>min</quote>) and
          &#60;burst&#62; 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&#39;s take</title>

            <programlisting>ACCEPT&#60;2/sec:4&#62; net dmz tcp 80</programlisting>

            <para>The first time this rule is reached, the packet will be
            accepted; in fact, since the burst is 4, the first four packets
            will be accepted. After this, it will be 500ms (1 second divided
            by the rate of 2) before a packet will be accepted from this rule,
            regardless of how many packets reach it. Also, every 500ms which
            passes without matching a packet, one of the bursts will be
            regained; if no packets hit the rule for 2 second, the burst will
            be fully recharged; back where we started.</para>
          </example>

          <warning>
            <para>When rate limiting is specified on a rule with
            <quote>all</quote> in the SOURCE or DEST fields below, the limit
            will apply to each pair of zones individually rather than as a
            single limit for all pairs of zones covered by the rule.</para>
          </warning>

          <para>Rate limiting may also be specified in the ACTION column
          above; in that case, it must not be specified as part of the RATE
          LIMIT column.</para>

          <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 SET</term>

        <listitem>
          <para>Beginning with Shorewall release 1.4.7, output rules from the
          firewall itself may be restricted to a particular set of users
          and/or user groups. See the User Set Documentation for details.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <example>
      <title>You wish to forward all ssh connection requests from the internet
      to local system 192.168.1.3. You wish to limit the number of connections
      to 4/minute with a burst of 8 (Shorewall 1.4.7 and later only):</title>

      <programlisting>#ACTION        SOURCE      DEST             PROTO      DEST PORT(S)
DNAT&#60;4/min:8&#62;  net         loc:192.168.1.3  tcp        ssh</programlisting>
    </example>

    <example>
      <title>You want to redirect all local www connection requests EXCEPT
      those to your own http server (206.124.146.177) to a Squid transparent
      proxy running on the firewall and listening on port 3128. Squid will of
      course require access to remote web servers. This example shows yet
      another use for the ORIGINAL DEST column; here, connection requests that
      were NOT (notice the <quote>!</quote>) originally destined to
      206.124.146.177 are redirected to local port 3128.</title>

      <programlisting>#ACTION  SOURCE  DEST   PROTO   DEST PORT(S)   SOURCE   ORIGINAL
#                                              PORT(S)  DEST
REDIRECT loc     3128   tcp     www            -        !206.124.146.177
ACCEPT   fw      net    tcp     www</programlisting>
    </example>

    <example>
      <title>You want to run a web server at 155.186.235.222 in your DMZ and
      have it accessible remotely and locally. the DMZ is managed by Proxy ARP
      or by classical sub-netting.</title>

      <programlisting>#ACTION        SOURCE      DEST                PROTO      DEST PORT(S)
ACCEPT         net         dmz:155.186.235.222 tcp        www
ACCEPT         loc         dmz:155.186.235.222 tcp        www</programlisting>
    </example>

    <example>
      <title>You want to run wu-ftpd on 192.168.2.2 in your masqueraded DMZ.
      Your internet interface address is 155.186.235.151 and you want the FTP
      server to be accessible from the internet in addition to the local
      192.168.1.0/24 and dmz 192.168.2.0/24 subnetworks.</title>

      <para><note><para>since the server is in the 192.168.2.0/24 subnetwork,
      we can assume that access to the server from that subnet will not
      involve the firewall (<ulink url="FAQ.htm#faq2">but see FAQ 2</ulink>)</para></note><note><para>unless
      you have more than one external IP address, you can leave the ORIGINAL
      DEST column blank in the first rule. You cannot leave it blank in the
      second rule though because then all ftp connections originating in the
      local subnet 192.168.1.0/24 would be sent to 192.168.2.2 regardless of
      the site that the user was trying to connect to. That is clearly not
      what you want.</para></note></para>

      <programlisting>#ACTION  SOURCE             DEST             PROTO  DEST PORT(S)   SOURCE   ORIGINAL
#                                                                  PORT(S)  DEST
DNAT     net                dmz:192.168.2.2  tcp    ftp
DNAT     loc:192.168.1.0/24 dmz:192.168.2.2  tcp    ftp            -        155.186.235.151</programlisting>

      <para>If you are running wu-ftpd, you should restrict the range of
      passive in your /etc/ftpaccess file. I only need a few simultaneous FTP
      sessions so I use port range 65500-65535. In /etc/ftpaccess, this entry
      is appropriate:</para>

      <programlisting>passive ports 0.0.0.0/0 65500 65534</programlisting>

      <para>If you are running pure-ftpd, you would include <quote>-p
      65500:65534</quote> on the pure-ftpd runline.</para>

      <para>The important point here is to ensure that the port range used for
      FTP passive connections is unique and will not overlap with any usage on
      the firewall system.</para>
    </example>

    <example>
      <title>You wish to allow unlimited DMZ access to the host with MAC
      address 02:00:08:E3:FA:55.</title>

      <programlisting>#ACTION  SOURCE                  DEST PROTO DEST PORT(S)
ACCEPT   loc:~02-00-08-E3-FA-55  dmz  all</programlisting>
    </example>

    <example>
      <title>You wish to allow access to the SMTP server in your DMZ from all
      zones.</title>

      <programlisting>#ACTION  SOURCE   DEST PROTO DEST PORT(S)
ACCEPT   all      dmz  tcp   25</programlisting>

      <para><note><para>When <quote>all</quote> is used as a source or
      destination, intra-zone traffic is not affected. In this example, if
      there were two DMZ interfaces then the above rule would NOT enable SMTP
      traffic between hosts on these interfaces.</para></note></para>
    </example>

    <example>
      <title>Your firewall&#39;s external interface has several IP addresses
      but you only want to accept SSH connections on address 206.124.146.176.</title>

      <programlisting>#ACTION  SOURCE   DEST               PROTO DEST PORT(S)
ACCEPT   net      fw:206.124.146.176 tcp   22</programlisting>
    </example>

    <example>
      <title>(For advanced users running Shorewall version 1.3.13 or later).
      From the internet, you with to forward tcp port 25 directed to
      192.0.2.178 and 192.0.2.179 to host 192.0.2.177 in your DMZ. You also
      want to allow access from the internet directly to tcp port 25 on
      192.0.2.177.</title>

      <programlisting>#ACTION  SOURCE   DEST             PROTO  DEST PORT(S)   SOURCE   ORIGINAL
#                                                        PORT(S)  DEST
DNAT-    net      dmz:192.0.2.177  tcp    25             -        192.0.2.178
DNAT-    net      dmz:192.0.2.177  tcp    25             -        192.0.2.179
ACCEPT   net      dmz:192.0.2.177  tcp    25</programlisting>

      <para>Using <quote>DNAT-</quote> rather than <quote>DNAT</quote> avoids
      two extra copies of the third rule from being generated.</para>
    </example>

    <example>
      <title>(Shorewall version 1.4.6 or later). You have 9 http servers
      behind a Shorewall firewall and you want connection requests to be
      distributed among your servers. The servers are
      192.168.1.101-192.168.1.109.</title>

      <programlisting>#ACTION  SOURCE   DEST                            PROTO DEST PORT(S)
DNAT     net      loc:192.168.1.101-192.168.1.109 tcp   80</programlisting>
    </example>

    <para><ulink url="ports.htm">Look here for information on other services.</ulink></para>
  </section>

  <section id="Common" xreflabel="/etc/shorewall/common">
    <title>/etc/shorewall/common</title>

    <para>Shorewall allows definition of rules that apply between all zones.
    By default, these rules are defined in the file <filename>/etc/shorewall/common.def</filename>
    but may be modified to suit individual requirements. Rather than modify
    <filename>/etc/shorewall/common.def</filename>, you should copy that file
    to <filename>/etc/shorewall/common</filename> and modify that file.</para>

    <para>The <filename>/etc/shorewall/common</filename> file is expected to
    contain iptables commands; rather than running iptables directly, you
    should run it indirectly using the Shorewall function <quote><command>run_iptables</command></quote>.
    That way, if iptables encounters an error, the firewall will be safely
    stopped.</para>
  </section>

  <section id="Masq" xreflabel="/etc/shorewall/masq">
    <title>/etc/shorewall/masq</title>

    <para>The /etc/shorewall/masq file is used to define classical IP
    Masquerading and Source Network Address Translation (SNAT). There is one
    entry in the file for each subnet that you want to masquerade. In order to
    make use of this feature, you must have NAT enabled.</para>

    <para>Columns are:</para>

    <variablelist>
      <varlistentry>
        <term>INTERFACE</term>

        <listitem>
          <para>The interface that will masquerade the subnet; this is
          normally your internet interface. This interface name can be
          optionally qualified by adding <quote>:</quote> and a subnet or host
          IP. When this qualification is added, only packets addressed to that
          host or subnet will be masqueraded. Beginning with Shorewall version
          1.4.10, the interface name can be qualified with &#34;:&#34;
          followed by a comma separated list of hosts and/or subnets. If this
          list begins with <quote>!</quote> (e.g., <quote>eth0:!192.0.2.8/29,192.0.2.32/29</quote>)
          then only packets addressed to destinations <emphasis role="bold">not</emphasis>
          listed will be masqueraded; otherwise (e.g., <quote>eth0:192.0.2.8/29,192.0.2.32/29</quote>),
          traffic will be masqueraded if it <emphasis role="bold">does</emphasis>
          match one of the listed addresses.</para>

          <para>Beginning with Shorewall version 1.3.14, if you have set
          ADD_SNAT_ALIASES=Yes in <xref linkend="Conf" />, you can cause
          Shorewall to create an alias <emphasis>label</emphasis> of the form
          <emphasis>interfacename:digit</emphasis> (e.g., eth0:0) by placing
          that label in this column. See example 5 below. Alias labels created
          in this way allow the alias to be visible to the ipconfig utility.
          <emphasis role="bold">THAT IS THE ONLY THING THAT THIS LABEL IS GOOD
          FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN YOUR SHOREWALL
          CONFIGURATION.</emphasis></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>SUBNET</term>

        <listitem>
          <para>The subnet that you want to have masqueraded through the
          INTERFACE. This may be expressed as a single IP address, a subnet or
          an interface name. In the latter instance, the interface must be
          configured and started before Shorewall is started as Shorewall will
          determine the subnet based on information obtained from the
          <quote>ip</quote> utility.</para>

          <caution>
            <para>When using Shorewall 1.3.13 or earlier, when an interface
            name is specified, Shorewall will only masquerade traffic from the
            first subnetwork on the named interface; if the interface
            interfaces to more that one subnetwork, you will need to add
            additional entries to this file for each of those other
            subnetworks. Beginning with Shorewall 1.3.14, shorewall will
            masquerade/SNAT traffic from any host that is routed through the
            named interface.</para>
          </caution>

          <para>The subnet may be optionally followed by <quote>!</quote> and
          a comma-separated list of addresses and/or subnets that are to be
          excluded from masquerading.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ADDRESS</term>

        <listitem>
          <para>The source address to be used for outgoing packets. This
          column is optional and if left blank, the current primary IP address
          of the interface in the first column is used. If you have a static
          IP on that interface, listing it here makes processing of output
          packets a little less expensive for the firewall. If you specify an
          address in this column, it must be an IP address configured on the
          INTERFACE or you must have ADD_SNAT_ALIASES enabled in <xref
          linkend="Conf" />. Beginning with Shorewall version 1.4.6, you may
          include a range of IP addresses in this column to indicate that
          Netfilter should use the addresses in the range in round-robin
          fashion. Beginning with Shorewall version 1.4.7, you may include a
          list of ranges and/or addresses in this column; again, Netfilter
          will use all listed ranges/addresses in rounde-robin fashion.</para>
        </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-&#62;net
      connections to use source address 206.124.146.176.</title>

      <programlisting>#INTERFACE          SUBNET           ADDRESS
eth0                192.168.10.0/24  206.124.146.176</programlisting>
    </example>

    <example>
      <title>Same as example 3 except that you wish to exclude 192.168.10.44
      and 192.168.10.45 from the SNAT rule.</title>

      <programlisting>#INTERFACE SUBNET                                      ADDRESS
eth0       192.168.10.0/24!192.168.10.44,192.168.10.45 206.124.146.176</programlisting>
    </example>

    <example>
      <title><emphasis role="bold">(Shorewall version &#62;= 1.3.14):</emphasis>
      You have a second IP address (206.124.146.177) assigned to you and wish
      to use it for SNAT of the subnet 192.168.12.0/24. You want to give that
      address the name eth0:0. You must have ADD_SNAT_ALIASES=Yes in <xref
      linkend="Conf" />.</title>

      <programlisting>#INTERFACE           SUBNET           ADDRESS
eth0:0               192.168.12.0/24  206.124.146.177</programlisting>
    </example>

    <example>
      <title><emphasis role="bold">(Shorewall version &#62;= 1.4.7):</emphasis>
      You want to use both 206.124.146.177 and 206.124.146.179 for SNAT of the
      subnet 192.168.12.0/24. Each address will be used on alternate outbound
      connections.</title>

      <programlisting>#INTERFACE            SUBNET          ADDRESS
eth0                  192.168.12.0/24 206.124.146.177,206.124.146.179</programlisting>
    </example>
  </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>&#60;<emphasis>interface</emphasis>&#62;<filename>/proxy_arp</filename>)
    by including the <emphasis role="bold">proxyarp</emphasis> option in the
    interface&#39;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>
    </variablelist>

    <note>
      <para>After you have made a change to the /etc/shorewall/proxyarp file,
      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 &#60;external interface&#62; host &#60;IP addr&#62;</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&#39;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>

    <warning>
      <para>Do not use Proxy ARP and FreeS/Wan on the same system unless you
      are prepared to suffer the consequences. If you start or restart
      Shorewall with an IPSEC tunnel active, the proxied IP addresses are
      mistakenly assigned to the IPSEC tunnel device (ipsecX) rather than to
      the interface that you specify in the INTERFACE column of
      <filename>/etc/shorewall/proxyarp</filename>. I haven&#39;t had the time
      to debug this problem so I can&#39;t say if it is a bug in the Kernel or
      in FreeS/Wan.</para>

      <para>You <emphasis role="bold">might</emphasis> be able to work around
      this problem using the following (I haven&#39;t tried it):</para>

      <para>In <filename>/etc/shorewall/init</filename>, include:</para>

      <programlisting><command>qt /etc/init.d/ipsec stop</command></programlisting>

      <para>In <filename>/etc/shorewall/start</filename>, include:</para>

      <programlisting><command>qt /etc/init.d/ipsec start</command></programlisting>
    </warning>
  </section>

  <section id="NAT" xreflabel="/etc/shorewall/nat">
    <title>/etc/shorewall/nat</title>

    <para>The <filename>/etc/shorewall/nat</filename> file is used to define
    one-to-one NAT. There is one entry in the file for each one-to-one NAT
    relationship that you wish to define. In order to make use of this
    feature, you must have NAT enabled.</para>

    <important>
      <para>If all you want to do is forward ports to servers behind your
      firewall, you do NOT want to use one-to-one NAT. Port forwarding can be
      accomplished with simple entries in the <link linkend="Rules">rules file</link>.
      Also, in most cases <link linkend="ProxyArp">Proxy ARP</link> provides a
      superior solution to one-to-one NAT because the internal systems are
      accessed using the same IP address internally and externally.</para>
    </important>

    <para>Columns in an entry are:</para>

    <variablelist>
      <varlistentry>
        <term>EXTERNAL</term>

        <listitem>
          <para>External IP address</para>

          <caution>
            <para>This should NOT be the primary IP address of the interface
            named in the next column.</para>
          </caution>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>INTERFACE</term>

        <listitem>
          <para>Interface that you want the EXTERNAL IP address to appear on.
          Beginning with Shorewall version 1.3.14, if you have set
          ADD_IP_ALIASES=Yes in <xref linkend="Conf" />, you can specify an
          alias label of the form <emphasis>interfacename:digit</emphasis>
          (e.g., eth0:0) and Shorewall will create the alias with that label.
          Alias labels created in this way allow the alias to be visible to
          the ipconfig utility. <emphasis role="bold">THAT IS THE ONLY THING
          THAT THIS LABEL IS GOOD FOR AND IT MAY NOT APPEAR ANYWHERE ELSE IN
          YOUR SHOREWALL CONFIGURATION.</emphasis></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>INTERNAL</term>

        <listitem>
          <para>Internal IP address.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ALL INTERFACES</term>

        <listitem>
          <para>If Yes or yes (or left empty), NAT will be effective from all
          hosts. If No or no 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 and the ALL INTERFACES column contains Yes or
          yes, NAT will be effective from the firewall system.</para>

          <note>
            <para>For this to work, you must be running kernel 2.4.19 or later
            and iptables 1.2.6a or later and you must have enabled <emphasis
            role="bold">CONFIG_IP_NF_NAT_LOCAL</emphasis> in your kernel.</para>
          </note>
        </listitem>
      </varlistentry>
    </variablelist>

    <para><ulink url="NAT.htm">Look here for additional information and an
    example.</ulink></para>
  </section>

  <section id="Tunnels" xreflabel="/etc/shorewall/tunnels">
    <title>/etc/shorewall/tunnels</title>

    <para>The /etc/shorewall/tunnels file allows you to define IPSec, GRE,
    IPIP, <ulink url="http://openvpn.sourceforge.net/">OpenVPN</ulink>, PPTP
    and 6to4.tunnels with end-points on your firewall. To use ipsec, you must
    install version 1.9, 1.91 or the current <ulink
    url="http://www.xs4all.nl/%7Efreeswan/">FreeS/WAN</ulink> development
    snapshot.</para>

    <note>
      <para>For kernels 2.4.4 and above, you will need to use version 1.91 or
      a development snapshot as patching with version 1.9 results in kernel
      compilation errors.</para>
    </note>

    <para>Instructions for setting up <ulink url="IPSEC.htm">IPSEC tunnels</ulink>
    may be found here, 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>MODULE_SUFFIX</term>

        <listitem>
          <para>(Added at version 1.4.9) - The value of this variable
          determines the possible file extensions of kernel modules. The
          default value is &#34;o gz ko and o.gz&#34;. See <xref
          linkend="modules" /> for more details.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ADMINISABSENTMINDED</term>

        <listitem>
          <para>(Added at version 1.4.7) - The value of this variable affects
          Shorewall&#39;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 /etc/shorewall/routestopped,
          connections that were active when Shorewall stopped continue to work
          and all new connections from the firewall system itself are allowed.
          If this variable is not set or is given the empty value then
          ADMINISABSENTMINDED=No is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>SHOREWALL_SHELL</term>

        <listitem>
          <para>(Added at version 1.4.6) - This parameter is used to specify
          the shell program to be used to interpret the firewall script
          (/usr/share/shorewall/firewall). If not specified or specified as a
          null value, /bin/sh is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>LOGFORMAT</term>

        <listitem>
          <para>(Added at version 1.4.4) - The value of this variable generate
          the --log-prefix setting for Shorewall logging rules. It contains a
          <quote>printf</quote> formatting template which accepts three
          arguments (the chain name, logging rule number (optional) and the
          disposition). To use LOGFORMAT with <ulink
          url="http://www.fireparse.com">fireparse</ulink>, set it as:</para>

          <programlisting>LOGFORMAT=&#34;fp=%s:%d a=%s &#34;</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=&#34;&#34;) then <quote>Shorewall:%s:%s:</quote> is
          assumed.</para>

          <caution>
            <para><command>/sbin/shorewall</command> uses the leading part of
            the LOGFORMAT string (up to but not including the first
            <quote>%</quote>) to find log messages in the <quote>show log</quote>,
            <quote>status</quote> and <quote>hits</quote> commands. This part
            should not be omitted (the LOGFORMAT should not begin with
            <quote>%</quote>) and the leading part should be sufficiently
            unique for <command>/sbin/shorewall</command> to identify
            Shorewall messages.</para>
          </caution>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>CLEAR_TC</term>

        <listitem>
          <para>(Added at version 1.3.13) - If this option is set to
          <quote>No</quote> then Shorewall won&#39;t clear the current traffic
          control rules during [re]start. This setting is intended for use by
          people that prefer to configure traffic shaping when the network
          interfaces come up rather than when the firewall is started. If that
          is what you want to do, set TC_ENABLED=Yes and CLEAR_TC=No and do
          not supply an <filename>/etc/shorewall/tcstart</filename> file. That
          way, your traffic shaping rules can still use the <quote>fwmark</quote>
          classifier based on packet marking defined in
          /etc/shorewall/tcrules. If not specified, CLEAR_TC=Yes is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MARK_IN_FORWARD_CHAIN</term>

        <listitem>
          <para>(Added at version 1.3.12) - If your kernel has a FORWARD chain
          in the mangle table, you may set MARK_IN_FORWARD_CHAIN=Yes to cause
          the marking specified in the <ulink
          url="traffic_shaping.htm#tcrules">tcrules file</ulink> to occur in
          that chain rather than in the PREROUTING chain. This permits you to
          mark inbound traffic based on its destination address when SNAT or
          Masquerading are in use. To determine if your kernel has a FORWARD
          chain in the mangle table, use the <quote><command>/sbin/shorewall
          show mangle</command></quote> command; if a FORWARD chain is
          displayed then your kernel will support this option. If this option
          is not specified or if it is given the empty value (e.g.,
          MARK_IN_FORWARD_CHAIN=&#34;&#34;) then MARK_IN_FORWARD_CHAIN=No is
          assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>RFC1918_LOG_LEVEL</term>

        <listitem>
          <para>(Added at version 1.3.12) - This parameter determines the
          level at which packets logged under the <link linkend="rfc1918"><quote>norfc1918</quote>
          mechanism</link> are logged. The value must be a valid <ulink
          url="shorewall_logging.html">syslog level</ulink> and if no level is
          given, then info is assumed. Prior to Shorewall version 1.3.12,
          these packets are always logged at the info level.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>TCP_FLAGS_DISPOSITION</term>

        <listitem>
          <para>(Added in Version 1.3.11) - Determines the disposition of TCP
          packets that fail the checks enabled by the <link
          linkend="Interfaces">tcpflags</link> interface option and must have
          a value of ACCEPT (accept the packet), REJECT (send an RST response)
          or DROP (ignore the packet). If not set or if set to the empty value
          (e.g., TCP_FLAGS_DISPOSITION=&#34;&#34;) then
          TCP_FLAGS_DISPOSITION=DROP is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>TCP_FLAGS_LOG_LEVEL</term>

        <listitem>
          <para>(Added in Version 1.3.11) - Determines the <ulink
          url="shorewall_logging.html">syslog level</ulink> for logging
          packets that fail the checks enabled by the <link
          linkend="Interfaces">tcpflags</link> interface option.The value must
          be a valid syslogd log level. If you don&#39;t want to log these
          packets, set to the empty value (e.g.,
          TCP_FLAGS_LOG_LEVEL=&#34;&#34;).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MACLIST_DISPOSITION</term>

        <listitem>
          <para>(Added in Version 1.3.10) - Determines the disposition of
          connections requests that fail <ulink url="MAC_Validation.html">MAC
          Verification</ulink> and must have the value ACCEPT (accept the
          connection request anyway), REJECT (reject the connection request)
          or DROP (ignore the connection request). If not set or if set to the
          empty value (e.g., MACLIST_DISPOSITION=&#34;&#34;) then
          MACLIST_DISPOSITION=REJECT is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MACLIST_LOG_LEVEL</term>

        <listitem>
          <para>(Added in Version 1.3.10) - Determines the <ulink
          url="shorewall_logging.html">syslog level</ulink> for logging
          connection requests that fail <ulink url="MAC_Validation.html">MAC
          Verification</ulink>. The value must be a valid syslogd log level.
          If you don&#39;t want to log these connection requests, set to the
          empty value (e.g., MACLIST_LOG_LEVEL=&#34;&#34;).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NEWNOTSYN</term>

        <listitem>
          <para>(Added in Version 1.3.8) - When set to <quote>Yes</quote> or
          <quote>yes</quote>, Shorewall will filter TCP packets that are not
          part of an established connention and that are not SYN packets (SYN
          flag on - ACK flag off). If set to <quote>No</quote>, Shorewall will
          silently drop such packets. If not set or set to the empty value
          (e.g., <quote>NEWNOTSYN=</quote>), NEWNOTSYN=No is assumed.</para>

          <para>If you have a HA setup with failover to another firewall, you
          should have NEWNOTSYN=Yes on both firewalls. You should also select
          NEWNOTSYN=Yes if you have asymmetric routing.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>LOGNEWNOTSYN</term>

        <listitem>
          <para>(Added in Version 1.3.6) - Beginning with version 1.3.6,
          Shorewall drops non-SYN TCP packets that are not part of an existing
          connection. If you would like to log these packets, set LOGNEWNOTSYN
          to the <ulink url="shorewall_logging.html">syslog level</ulink> at
          which you want the packets logged. Example: LOGNEWNOTSYN=ULOG|</para>

          <note>
            <para>Packets logged under this option are usually the result of
            broken remote IP stacks rather than the result of any sort of
            attempt to breach your firewall.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DETECT_DNAT_ADDRS</term>

        <listitem>
          <para>(Added in Version 1.3.4) - If set to <quote>Yes</quote> or
          <quote>yes</quote>, Shorewall will detect the first IP address of
          the interface to the source zone and will include this address in
          DNAT rules as the original destination IP address. If set to
          <quote>No</quote> or <quote>no</quote>, Shorewall will not detect
          this address and any destination IP address will match the DNAT
          rule. If not specified or empty, <quote>DETECT_DNAT_ADDRS=Yes</quote>
          is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MULTIPORT</term>

        <listitem>
          <note>
            <para>Removed in version 1.4.6 -- the value of this parameter is
            now automatically detected by Shorewall</para>
          </note>

          <para>If set to <quote>Yes</quote> or <quote>yes</quote>, Shorewall
          will use the Netfilter multiport facility. In order to use this
          facility, your kernel must have multiport support
          (CONFIG_IP_NF_MATCH_MULTIPORT). When this support is used, Shorewall
          will generate a single rule from each record in the
          /etc/shorewall/rules file that meets these criteria:</para>

          <itemizedlist>
            <listitem>
              <para>No port range(s) specified</para>
            </listitem>

            <listitem>
              <para>Specifies 15 or fewer ports</para>
            </listitem>
          </itemizedlist>

          <para>Rules not meeting those criteria will continue to generate an
          individual rule for each listed port or port range.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NAT_BEFORE_RULES</term>

        <listitem>
          <para>If set to <quote>No</quote> or <quote>no</quote>, port
          forwarding rules can override the contents of the <xref
          linkend="NAT" /> file. If set to <quote>Yes</quote> or
          <quote>yes</quote>, port forwarding rules cannot override one-to-one
          NAT. If not set or set to an empty value, <quote>Yes</quote> is
          assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FW</term>

        <listitem>
          <para>This parameter specifies the name of the firewall zone. If not
          set or if set to an empty string, the value <quote>fw</quote> is
          assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>SUBSYSLOCK</term>

        <listitem>
          <para>This parameter should be set to the name of a file that the
          firewall should create if it starts successfully and remove when it
          stops. Creating and removing this file allows Shorewall to work with
          your distribution&#39;s initscripts. For RedHat, this should be set
          to /var/lock/subsys/shorewall. For Debian, the value is
          /var/state/shorewall and in LEAF it is /var/run/shorwall. Example:
          SUBSYSLOCK=/var/lock/subsys/shorewall.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>STATEDIR</term>

        <listitem>
          <para>This parameter specifies the name of a directory where
          Shorewall stores state information. If the directory doesn&#39;t
          exist when Shorewall starts, it will create the directory. Example:
          STATEDIR=/tmp/shorewall.</para>

          <note>
            <para>If you change the STATEDIR variable while the firewall is
            running, create the new directory if necessary then copy the
            contents of the old directory to the new directory.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MODULESDIR</term>

        <listitem>
          <para>This parameter specifies the directory where your kernel
          netfilter modules may be found. If you leave the variable empty,
          Shorewall will supply the value &#34;/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>
          </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>NAT_ENABLED</term>

        <listitem>
          <note>
            <para>Removed in Shorewall 1.4.6 -- the value of this parameter is
            now automatically detected by Shorewall</para>
          </note>

          <para>This parameter determines whether Shorewall supports NAT
          operations. NAT operations include:</para>

          <simplelist>
            <member>One-to-one NAT</member>

            <member>Port Forwarding</member>

            <member>Port Redirection</member>

            <member>Masquerading</member>
          </simplelist>

          <para>If the parameter has no value or has a value of
          <quote>Yes</quote> or <quote>yes</quote> then NAT is enabled. If the
          parameter has a value of <quote>no</quote> or <quote>No</quote> then
          NAT is disabled.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>MANGLE_ENABLED</term>

        <listitem>
          <note>
            <para>Removed in Shorewall 1.4.6 -- the value of this parameter is
            now automatically detected by Shorewall</para>
          </note>

          <para>This parameter determines if packet mangling is enabled. If
          the parameter has no value or has a value of <quote>Yes</quote> or
          <quote>yes</quote> than packet mangling is enabled. If the parameter
          has a value of <quote>no</quote> or <quote>No</quote> then packet
          mangling is disabled. If packet mangling is disabled, the
          /etc/shorewall/tos file is ignored.</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=&#34;&#34;) 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&#39;s network configuration tools.</para>

          <important>
            <para>Shorewall versions before 1.4.6 can only add addresses to
            the first subnetwork configured on an interface.</para>
          </important>

          <para>If this variable is not set or is given an empty value
          (ADD_IP_ALIASES=&#34;&#34;) then ADD_IP_ALIASES=Yes is assumed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ADD_SNAT_ALIASES</term>

        <listitem>
          <para>This parameter determines whether Shorewall automatically adds
          the SNAT <emphasis>ADDRESS</emphasis> in <xref linkend="Masq" />. If
          the variable is set to <quote>Yes</quote> or <quote>yes</quote> then
          Shorewall automatically adds these addresses. If it is set to
          <quote>No</quote> or <quote>no</quote>, you must add these addresses
          yourself using your distribution&#39;s network configuration tools.</para>

          <important>
            <para>Shorewall versions before 1.4.6 can only add addresses to
            the first subnetwork configured on an interface.</para>
          </important>

          <para>If this variable is not set or is given an empty value
          (ADD_SNAT_ALIASES=&#34;&#34;) then ADD_SNAT_ALIASES=No is assumed.</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 paremter 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>CLAMPMSS</term>

        <listitem>
          <para>This parameter enables the TCP Clamp MSS to PMTU feature of
          Netfilter and is usually required when your internet connection is
          through PPPoE or PPTP. If set to <quote>Yes</quote> or
          <quote>yes</quote>, the feature is enabled. If left blank or set to
          <quote>No</quote> or <quote>no</quote>, the feature is not enabled.</para>

          <note>
            <para>This option requires CONFIG_IP_NF_TARGET_TCPMSS <ulink
            url="kernel.htm">in your kernel</ulink>.</para>
          </note>
        </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. 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 &#60;<emphasis>modulename</emphasis>&#62; [ &#60;<emphasis>module parameters</emphasis>&#62; ]</programlisting>

    <para>where</para>

    <variablelist>
      <varlistentry>
        <term>&#60;<emphasis>modulename</emphasis>&#62;</term>

        <listitem>
          <para>is the name of the modules without the trailing
          <quote>.o</quote> (example ip_conntrack).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>&#60;<emphasis>module parameters</emphasis>&#62;</term>

        <listitem>
          <para>Optional parameters to the insmod utility.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>The function determines if the module named by &#60;<emphasis>modulename</emphasis>&#62;
    is already loaded and if not then the function determines if the
    <quote>.o</quote> file corresponding to the module exists in the
    <emphasis>&#60;moduledirectory&#62;</emphasis>; if so, then the following
    command is executed:</para>

    <programlisting>insmod <emphasis>&#60;moduledirectory</emphasis>&#62;/&#60;<emphasis>modulename</emphasis>&#62;.o &#60;<emphasis>module parameters</emphasis>&#62;</programlisting>

    <para>If the file doesn&#39;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>&#60;moduledirectory</emphasis>&#62;/&#60;<emphasis>modulename</emphasis>&#62;.o.gz &#60;<emphasis>module parameters</emphasis>&#62;</programlisting>

    <para>Beginning with the 1.4.9 Shorewall release, the value of the
    MODULE_SUFFIX option in determines which files the loadmodule function
    looks for if the named module doesn&#39;t exist. For each file
    <emphasis>&#60;extension&#62;</emphasis> listed in MODULE_SUFFIX (default
    &#34;o gz ko o.gz&#34;), the function will append a period (&#34;.&#34;)
    and the extension and if the resulting file exists then the following
    command will be executed:</para>

    <programlisting>insmod <emphasis>moduledirectory</emphasis>/&#60;<emphasis>modulename</emphasis>&#62;.<emphasis>&#60;extension&#62;</emphasis> &#60;<emphasis>module parameters</emphasis>&#62;</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&#39;s number.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>SOURCE PORT(S)</term>

        <listitem>
          <para>The source port or a port range. For all ports, place a hyphen
          (<quote>-</quote>) in this column.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>DEST PORT(S)</term>

        <listitem>
          <para>The destination port or a port range. To indicate all ports,
          place a hyphen (<quote>-</quote>) in this column.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>TOS</term>

        <listitem>
          <para>The type of service. Must be one of the following:</para>

          <simplelist>
            <member>Minimize-Delay (16)</member>

            <member>Maximize-Throughput (8)</member>

            <member>Maximize-Reliability (4)</member>

            <member>Minimize-Cost (2)</member>

            <member>Normal-Service (0)</member>
          </simplelist>
        </listitem>
      </varlistentry>
    </variablelist>

    <para><filename>/etc/shorewall/tos</filename> file that is included with
    Shorewall</para>

    <programlisting>#SOURCE  DEST    PROTOCOL    SOURCE PORTS(S)   DEST PORTS(S)   TOS
all      all     tcp         -                 ssh             16
all      all     tcp         ssh               -               16
all      all     tcp         -                 ftp             16
all      all     tcp         ftp               -               16
all      all     tcp         -                 ftp-data        8
all      all     tcp         ftp-data          -               8</programlisting>

    <warning>
      <para>Users have reported that odd routing problems result from adding
      the ESP and AH protocols to the <filename>/etc/shorewall/tos</filename>
      file.</para>
    </warning>
  </section>

  <section id="Blacklist" xreflabel="/etc/shorewall/blacklist">
    <title>/etc/shorewall/blacklist</title>

    <para>Each line in <filename>/etc/shorewall/blacklist</filename> contains
    an IP address, a MAC address in Shorewall Format or subnet address.</para>

    <example>
      <title></title>

      <programlisting>130.252.100.69
206.124.146.0/24</programlisting>
    </example>

    <para>Packets <emphasis role="bold">from</emphasis> hosts listed in the
    blacklist file will be disposed of according to the value assigned to the
    <link linkend="Conf">BLACKLIST_DISPOSITION</link> and <link linkend="Conf">BLACKLIST_LOGLEVEL</link>
    variables in /etc/shorewall/shorewall.conf. Only packets arriving on
    interfaces that have the <quote><link linkend="Interfaces">blacklist</link></quote>
    option in <filename>/etc/shorewall/interfaces</filename> are checked
    against the blacklist. The black list is designed to prevent listed
    hosts/subnets from accessing services on <emphasis role="bold">your</emphasis>
    network.</para>

    <para>Beginning with Shorewall 1.3.8, the blacklist file has three
    columns:</para>

    <variablelist>
      <varlistentry>
        <term>ADDRESS/SUBNET</term>

        <listitem>
          <para>As described above.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>PROTOCOL</term>

        <listitem>
          <para>Optional. If specified, only packets specifying this protocol
          will be blocked.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>PORTS</term>

        <listitem>
          <para>Optional; may only be given if PROTOCOL is tcp, udp or icmp.
          Expressed as a comma-separated list of port numbers or service names
          (from /etc/services). If present, only packets destined for the
          specified protocol and one of the listed ports are blocked. When the
          PROTOCOL is icmp, the PORTS column contains a comma-separated list
          of ICMP type numbers or names (see <quote>iptables -h icmp</quote>).</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Shorewall also has a <ulink url="blacklisting_support.htm">dynamic
    blacklist capability</ulink>.</para>

    <important>
      <para>The Shorewall blacklist file is <emphasis role="bold">NOT</emphasis>
      designed to police your users&#39; web browsing -- to do that, I suggest
      that you install and configure <ulink url="http://www.squid-cache.org">Squid</ulink>
      with <ulink url="http://www.squidguard.org/">SquidGuard</ulink>.</para>
    </important>
  </section>

  <section id="rfc1918" xreflabel="/etc/shorewall/rfc1918">
    <title>/etc/shorewall/rfc1918 (Added in Version 1.3.1)</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.</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>
  </section>

  <section id="Routestopped" xreflabel="/etc/shorewall/routestopped">
    <title>/etc/shorewall/routestopped (Added in Version 1.3.4)</title>

    <para>This file defines the hosts that are accessible from the firewall
    when the firewall is stopped. Columns in the file are:</para>

    <variablelist>
      <varlistentry>
        <term>INTERFACE</term>

        <listitem>
          <para>The firewall interface through which the host(s) comminicate
          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>
  </section>

  <section id="Maclist" xreflabel="/etc/shorewall/maclist">
    <title>/etc/shorewall/maclist (Added in Version 1.3.10)</title>

    <para>This file is described in the <ulink url="MAC_Validation.html">MAC
    Validation Documentation</ulink>.</para>
  </section>

  <section id="ECN" xreflabel="/etc/shorewall/ecn">
    <title>/etc/shorewall/ecn (Added in Version 1.4.0)</title>

    <para>This file is described in the <ulink url="ECN.html">ECN Control
    Documentation</ulink>.</para>
  </section>

  <section id="UserSets" xreflabel="/usr/shorewall/Users">
    <title>/etc/shorewall/users and /etc/shorewall/usersets</title>

    <para>These files are described in the<ulink url="UserSets.html">UID/GID-based
    Rules 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.13</revnumber><date>2004-02-13</date><authorinitials>TE</authorinitials><revremark>Add
    information about the order of rules evalution.</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>