shorewall_code/docs/configuration_file_basics.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Configuration Files Tips and Hints</title>

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

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

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

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

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

  <caution>
    <para>If you copy or edit your configuration files on a system running
    Microsoft Windows, you must run them through <ulink
    url="http://www.megaloman.com/~hany/software/hd2u/">dos2unix</ulink>
    before you use them with Shorewall.</para>
  </caution>

  <section>
    <title id="Intro">Introduction</title>

    <para>This article offers hints about how to accomplish common tasks with
    Shorewall. The <ulink url="Introduction.html">Introduction to
    Shorewall</ulink> is required reading for being able to use this article
    effectively. For information about setting up your first Shorewall-based
    firewall, see the <ulink url="GettingStarted.html">Quickstart
    Guides</ulink>.</para>
  </section>

  <section id="Files">
    <title>Files</title>

    <para><itemizedlist>
        <listitem>
          <para><filename>/etc/shorewall/shorewall.conf</filename> - used to
          set global firewall parameters.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/params</filename> - use this file to
          set shell variables that you will expand in other files. It is
          always processed by /bin/sh or by the shell specified through
          SHOREWALL_SHELL in
          <filename>/etc/shorewall/shorewall.conf.</filename></para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/zones</filename> - partition the
          firewall's view of the world into zones.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/policy</filename> - establishes
          firewall high-level policy.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/initdone</filename> - An optional
          Perl script that will be invoked by the Shorewall rules compiler
          when the compiler has finished it's initialization.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/interfaces</filename> - describes the
          interfaces on the firewall system.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/hosts</filename> - allows defining
          zones in terms of individual hosts and subnetworks.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/masq</filename> - directs the
          firewall where to use many-to-one (dynamic) Network Address
          Translation (a.k.a. Masquerading) and Source Network Address
          Translation (SNAT).</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/mangle</filename> - supersedes
          <filename>/etc/shorewall/tcrules</filename> in Shorewall 4.6.0.
          Contains rules for packet marking, TTL, TPROXY, etc.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/rules</filename> - defines rules that
          are exceptions to the overall policies established in
          /etc/shorewall/policy.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/nat</filename> - defines one-to-one
          NAT rules.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/proxyarp</filename> - defines use of
          Proxy ARP.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/routestopped</filename> - defines
          hosts accessible when Shorewall is stopped.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tcrules </filename>- The file has a
          rather unfortunate name because it is used to define marking of
          packets for later use by both traffic control/shaping and policy
          routing. This file is superseded by
          <filename>/etc/shorewall/mangle</filename> in Shorewall
          4.6.0.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tos</filename> - defines rules for
          setting the TOS field in packet headers.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tunnels</filename> - defines tunnels
          (VPN) with end-points on the firewall system.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/blacklist</filename> - Deprecated in
          favor of <filename>/etc/shorewall/blrules</filename>. Lists
          blacklisted IP/subnet/MAC addresses.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/blrules</filename> — Added in
          Shorewall 4.5.0. Define blacklisting and whitelisting.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/init</filename> - commands that you
          wish to execute at the beginning of a <quote>shorewall start</quote>
          or <quote>shorewall restart</quote>.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/start</filename> - commands that you
          wish to execute at the completion of a <quote>shorewall
          start</quote> or <quote>shorewall restart</quote></para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/stop </filename>- commands that you
          wish to execute at the beginning of a <quote>shorewall
          stop</quote>.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/stopped</filename> - commands that
          you wish to execute at the completion of a <quote>shorewall
          stop</quote>.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/ecn</filename> - disable Explicit
          Congestion Notification (ECN - RFC 3168) to remote hosts or
          networks.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/accounting</filename> - define IP
          traffic accounting rules</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/actions</filename> and
          <filename>/usr/share/shorewall/action.template</filename> allow
          user-defined actions.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/providers</filename> - defines an
          alternate routing table.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/rtrules</filename> - Defines routing
          rules to be used in conjunction with the routing tables defined in
          <filename>/etc/shorewall/providers</filename>.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tcdevices</filename>,
          <filename>/etc/shorewall/tcclasses</filename>,
          <filename>/etc/shorewall/tcfilters</filename> - Define complex
          traffic shaping.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tcrules</filename> - Mark or classify
          traffic for traffic shaping or multiple providers. Deprecated in
          Shorewall 4.6.0 in favor of
          <filename>/etc/shorewall/mangle</filename>.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tcinterfaces</filename> and
          <filename>/etc/shorewall-tcpri</filename> - Define simple traffic
          shaping.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/secmarks</filename> - Added in
          Shorewall 4.4.13. Attach an SELinux context to selected
          packets.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/vardir</filename> - Determines the
          directory where Shorewall maintains its state.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/shorewall/actions.std</filename> -
          Actions defined by Shorewall.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/shorewall/action.*</filename> - Details
          of actions defined by Shorewall.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/shorewall/macro.*</filename> - Details of
          macros defined by Shorewall.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/shorewall/modules</filename> - directs
          the firewall to load kernel modules.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/modules</filename> — Specifies the kernel
          modules to be loaded during shorewall start/restart.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/helpers</filename> — Added in Shorewall
          4.4.7. Specifies the kernel modules to be loaded during shorewall
          start/restart when LOAD_HELPERS_ONLY=Yes in
          <filename>shorewall.conf</filename>.</para>
        </listitem>

        <listitem>
          <para><filename>/usr/share/arprules</filename> — Added in Shorewall
          4.5.12. Allows specification of arptables rules.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/mangle</filename> -- Added in
          Shorewall 4.6.0. Supersedes<filename>
          /etc/shorewall/tcrules</filename>.</para>
        </listitem>
      </itemizedlist></para>

    <para><emphasis role="bold">If you need to change a file in
    /usr/share/shorewall/, copy it to <filename>/etc/shorewall</filename> and
    modify the copy</emphasis></para>
  </section>

  <section id="Manpages">
    <title>Man Pages</title>

    <para>Man pages are provided in section 5 for each of the Shorewall
    configuration files. The name of the page is formed by prefixing the file
    name with "shorewall-".</para>

    <para>Example — To view the manual page for
    <filename>/etc/shorewall/interfaces</filename>:</para>

    <programlisting>man shorewall-interfaces</programlisting>

    <para>The /etc/shorewall/shorewall.conf file is an exception -- the man
    page for that file is 'shorewall.conf':</para>

    <programlisting>man shorewall.conf</programlisting>
  </section>

  <section id="Comments">
    <title>Comments</title>

    <para>You may place comments in configuration files by making the first
    non-whitespace character a pound sign (<quote>#</quote>). You may also
    place comments at the end of any line, again by delimiting the comment
    from the rest of the line with a pound sign.</para>

    <example id="comment">
      <title>Comments in a Configuration File</title>

      <programlisting># This is a comment
ACCEPT  net     $FW      tcp     www     #This is an end-of-line comment</programlisting>
    </example>

    <important>
      <para>If a comment ends with a backslash ("\"), the next line will also
      be treated as a comment. See <link linkend="Continuation">Line
      Continuation</link> below.</para>
    </important>
  </section>

  <section id="Names">
    <title>Names</title>

    <para>When you define an object in Shorewall (<ulink
    url="manpages/shorewall-zones.html">Zone</ulink>, <link
    linkend="Logical">Logical Interface</link>, <ulink
    url="ipsets.html">ipsets</ulink>, <ulink
    url="Actions.html">Actions</ulink>, etc., you give it a name. Shorewall
    names start with a letter and consist of letters, digits or underscores
    ("_"). Except for Zone names, Shorewall does not impose a limit on name
    length.</para>

    <para>When an ipset is referenced, the name must be preceded by a plus
    sign ("+").</para>

    <para>The last character of an interface may also be a plus sign to
    indicate a wildcard name.</para>

    <para>Physical interface names match names shown by 'ip link ls'; if the
    name includes an at sign ("@"), do not include that character or any
    character that follows. For example, "sit1@NONE" is referred to as simply
    'sit1".</para>
  </section>

  <section>
    <title>Zone and Chain Names</title>

    <para>For a pair of zones, Shorewall creates two Netfilter chains; one for
    connections in each direction. The names of these chains are formed by
    separating the names of the two zones by either "2" or "-".</para>

    <para>Example: Traffic from zone A to zone B would go through chain A2B
    (think "A to B") or "A-B".</para>

    <para>In Shorewall 4.6, the default separator is "-" but you can override
    that by setting ZONE_SEPARATOR="2" in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>

    <note>
      <para>Prior to Shorewall 4.6, the default separator was "2".</para>
    </note>

    <para>Zones themselves have names that begin with a letter and are
    composed of letters, numerals, and "_". The maximum length of a name is
    dependent on the setting of LOGFORMAT in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). See <ulink
    url="manpages/shorewall-zones.html">shorewall-zones</ulink> (5) for
    details.</para>
  </section>

  <section id="capabilities">
    <title>Capabilities</title>

    <para>Shorewall probes your system to determine the features that it
    supports. The result of this probing is a set of
    <firstterm>capabilities</firstterm>. This probing is normally done each
    time that the compiler is run but can also be done by executing the
    <command>shorewall show capabilities</command> command. Regardless of
    whether the compiler or the command does the probing, this probing may
    produce error messages in your system log. These log messages are to be
    expected and do not represent a problem; they merely indicate that
    capabilities that are being probed are not supported on your
    system.</para>

    <para>Probing may be suppressed by using a <firstterm>capabilities
    file</firstterm>. A capabilities file may be generated using this
    command:</para>

    <programlisting><command>shorewall show -f capabilities &gt; /etc/shorewall/capabilities</command></programlisting>

    <important>
      <para>If you use a capabilities file, be sure to regenerate it after you
      have performed a Shorewall upgrade to ensure that all current
      capabilities have been recorded in your file.</para>
    </important>
  </section>

  <section id="BlankColumn">
    <title>"Blank" Columns</title>

    <para>If you don't want to supply a value in a column but want to supply a
    value in a following column, simply enter '-' to make the column appear
    empty.</para>

    <para>Example:<programlisting>#INTERFACE         BROADCAST            OPTIONS
br0                -                    routeback</programlisting></para>
  </section>

  <section id="Continuation">
    <title>Line Continuation</title>

    <para>You may continue lines in the configuration files using the usual
    backslash (<quote>\</quote>) followed immediately by a new line character
    (Enter key).</para>

    <example id="continuation">
      <title>Line Continuation</title>

      <programlisting>ACCEPT  net     $FW      tcp \↵
smtp,www,pop3,imap  #Services running on the firewall</programlisting>

      <para>In certain cases, leading white space is ignored in continuation
      lines:</para>

      <itemizedlist>
        <listitem>
          <para>The continued line ends with a colon (":")</para>
        </listitem>

        <listitem>
          <para>The continued line ends with a comma (",")</para>
        </listitem>
      </itemizedlist>

      <para>Example (<filename>/etc/shorewall/rules</filename>):</para>

      <programlisting>#ACTION     SOURCE          DEST            PROTO           DEST
#                                                           PORT(S)
ACCEPT      net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873</programlisting>

      <para>The leading white space on the first through third continuation
      lines is ignored so the SOURCE column effectively contains
      "net:206.124.146.177,206.124.147.178,206.124.146.180". Because the third
      continuation line does not end with a comma or colon, the leading white
      space in the last line is not ignored.</para>
    </example>

    <important>
      <para>A trailing backslash is not ignored in a comment. So the continued
      rule above can be commented out with a single '#' as follows:</para>

      <programlisting>#ACTION     SOURCE          DEST            PROTO           DEST
#                                                           PORT(S)
<emphasis role="bold">#</emphasis>ACCEPT     net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873</programlisting>
    </important>
  </section>

  <section id="Pairs">
    <title>Alternate Specification of Column Values - Shorewall 4.4.24 and
    Later</title>

    <para>Some of the configuration files now have a large number of columns.
    That makes it awkward to specify a value for one of the right-most columns
    as you must have the correct number of intervening '-' columns.</para>

    <para>This problem is addressed by allowing column values to be specified
    as <replaceable>column-name</replaceable>/<replaceable>value</replaceable>
    pairs.</para>

    <para>There is considerable flexibility in how you specify the
    pairs:</para>

    <itemizedlist>
      <listitem>
        <para>At any point, you can enter a left curly bracket ('{') followed
        by one or more specifications of the following forms:</para>

        <simplelist>
          <member><replaceable>column-name</replaceable>=<replaceable>value</replaceable></member>

          <member><replaceable>column-name</replaceable>=<replaceable>&gt;value</replaceable></member>

          <member><replaceable>column-name</replaceable>:<replaceable>value</replaceable></member>
        </simplelist>

        <para>The pairs must be followed by a right curly bracket
        ("}").</para>

        <para>The value may optionally be enclosed in double quotes.</para>

        <para>The pairs must be separated by white space, but you can add a
        comma adjacent to the <replaceable>values</replaceable> for
        readability as in:</para>

        <simplelist>
          <member><emphasis role="bold">{ proto=&gt;udp, port=1024
          }</emphasis></member>
        </simplelist>
      </listitem>

      <listitem>
        <para>You can also separate the pairs from columns by using a
        semicolon:</para>

        <simplelist>
          <member><emphasis role="bold">; proto:udp,
          port:1024</emphasis></member>
        </simplelist>

        <important>
          <para>That usage is deprecated beginning with Shorewall 4.6.0. See
          the INLINE_MATCHES option in <ulink
          url="manpages/shorewall.conf.html">shorewall.conf(5)</ulink>.</para>
        </important>
      </listitem>
    </itemizedlist>

    <para>The following table shows the column names for each of the
    table-oriented configuration files.</para>

    <note>
      <para>Column names are <emphasis
      role="bold">case-insensitive</emphasis>.</para>
    </note>

    <informaltable>
      <tgroup cols="2">
        <tbody>
          <row>
            <entry><emphasis role="bold">File</emphasis></entry>

            <entry><emphasis role="bold">Column names</emphasis></entry>
          </row>

          <row>
            <entry>accounting</entry>

            <entry>action,chain, source, dest, proto, dport, sport, user,
            mark, ipsec, headers</entry>
          </row>

          <row>
            <entry>conntrack (formerly notrack)</entry>

            <entry>source,dest,proto,dport,sport,user,switch</entry>
          </row>

          <row>
            <entry>blacklist</entry>

            <entry>networks,proto,port,options</entry>
          </row>

          <row>
            <entry>blrules</entry>

            <entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
          </row>

          <row>
            <entry>ecn</entry>

            <entry>interface,hosts. Beginning with Shorewall 4.5.4, 'host' is
            a synonym for 'hosts'.</entry>
          </row>

          <row>
            <entry>hosts</entry>

            <entry>zone,hosts,options. Beginning with Shorewall 4.5.4, 'host'
            is a synonym for 'hosts'.</entry>
          </row>

          <row>
            <entry>interfaces</entry>

            <entry>zone,interface,broadcast,options</entry>
          </row>

          <row>
            <entry>maclist</entry>

            <entry>disposition,interface,mac,addresses</entry>
          </row>

          <row>
            <entry>mangle</entry>

            <entry>action,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers</entry>
          </row>

          <row>
            <entry>masq</entry>

            <entry>interface,source,address,proto,port,ipsec,mark,user,switch</entry>
          </row>

          <row>
            <entry>nat</entry>

            <entry>external,interface,internal,allints,local</entry>
          </row>

          <row>
            <entry>netmap</entry>

            <entry>type,net1,interface,net2,net3,proto,dport,sport</entry>
          </row>

          <row>
            <entry>notrack</entry>

            <entry>source,dest,proto,dport,sport,user</entry>
          </row>

          <row>
            <entry>policy</entry>

            <entry>source,dest,policy,loglevel,limit,connlimit</entry>
          </row>

          <row>
            <entry>providers</entry>

            <entry>table,number,mark,duplicate,interface,gateway,options,copy</entry>
          </row>

          <row>
            <entry>proxyarp and proxyndp</entry>

            <entry>address,interface,external,haveroute,persistent</entry>
          </row>

          <row>
            <entry>rtrules</entry>

            <entry>source,dest,provider,priority</entry>
          </row>

          <row>
            <entry>routes</entry>

            <entry>provider,dest,gateway,device</entry>
          </row>

          <row>
            <entry>routestopped</entry>

            <entry>interface,hosts,options,proto,dport,sport</entry>
          </row>

          <row>
            <entry>rules</entry>

            <entry>action,source,dest,proto,dport,sport,origdest,rate,user,mark,connlimit,time,headers,switch,helper</entry>
          </row>

          <row>
            <entry>secmarks</entry>

            <entry>secmark,chain,source,dest,proto,dport,sport,user,mark</entry>
          </row>

          <row>
            <entry>tcclasses</entry>

            <entry>interface,mark,rate,ceil,prio,options</entry>
          </row>

          <row>
            <entry>tcdevices</entry>

            <entry>interface,in_bandwidth,out_bandwidth,options,redirect</entry>
          </row>

          <row>
            <entry>tcfilters</entry>

            <entry>class,source,dest,proto,dport,sport,tos,length</entry>
          </row>

          <row>
            <entry>tcinterfaces</entry>

            <entry>interface,type,in_bandwidth,out_bandwidth</entry>
          </row>

          <row>
            <entry>tcpri</entry>

            <entry>band,proto,port,address,interface,helper</entry>
          </row>

          <row>
            <entry>tcrules</entry>

            <entry>mark,source,dest,proto,dport,sport,user,test,length,tos,connbytes,helper,headers.
            Beginning with Shorewall 4.5.3, 'action' is a synonym for
            'mark'.</entry>
          </row>

          <row>
            <entry>tos</entry>

            <entry>source,dest,proto,dport,sport,tos,mark</entry>
          </row>

          <row>
            <entry>tunnels</entry>

            <entry>type,zone,gateway,gateway_zone. Beginning with Shorewall
            4.5.3, 'gateways' is a synonym for 'gateway'. Beginning with
            Shorewall 4.5.4, 'gateway_zones' is a synonym for
            'gateway_zone'.</entry>
          </row>

          <row>
            <entry>zones</entry>

            <entry>zone,type,options,in_options,out_options</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>Example (rules file):</para>

    <programlisting>#ACTION         SOURCE            DEST            PROTO   DEST 
#                                                         PORT(S)
DNAT            net               loc:10.0.0.1    tcp     80    ; mark="88"</programlisting>

    <para>Here's the same line in several equivalent formats:</para>

    <programlisting>{ action=&gt;DNAT, source=&gt;net, dest=&gt;loc:10.0.0.1, proto=&gt;tcp, dport=&gt;80, mark=&gt;88 }
; action:"DNAT" source:"net"  dest:"loc:10.0.0.1" proto:"tcp" dport:"80" mark:"88"
DNAT { source=net dest=loc:10.0.0.1 proto=tcp dport=80 mark=88 }</programlisting>
  </section>

  <section>
    <title>Addresses</title>

    <para>In both Shorewall and Shorewall6, there are two basic types of
    addresses:</para>

    <variablelist>
      <varlistentry>
        <term>Host Address</term>

        <listitem>
          <para>This address type refer to a single host.</para>

          <para>In IPv4, the format is <emphasis>i.j.k.l</emphasis> where
          <emphasis>i</emphasis> through <emphasis>l</emphasis> are decimal
          numbers between 1 and 255.</para>

          <para>In IPv6, the format is <emphasis>a:b:c:d:e:f:g:h</emphasis>
          where <emphasis>a</emphasis> through <emphasis>h</emphasis> consist
          of 1 to 4 hexidecimal digits (leading zeros may be omitted). a
          single series of 0 addresses may be omitted. For example
          2001:227:e857:1:0:0:0:0:1 may be written 2001:227:e857:1::1.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Network Address</term>

        <listitem>
          <para>A network address refers to 1 or more hosts and consists of a
          host address followed by a slash ("/") and a <firstterm>Variable
          Length Subnet Mask</firstterm> (VLSM). This is known as
          <firstterm>Classless Internet Domain Routing</firstterm> (CIDR)
          notation.</para>

          <para>The VLSM is a decimal number. For IPv4, it is in the range 0
          through 32. For IPv6, the range is 0 through 128. The number
          represents the number of leading bits in the address that represent
          the network address; the remainder of the bits are a host address
          and are generally given as zero.</para>

          <para>Examples:</para>

          <para>IPv4: 192.168.1.0/24</para>

          <para>IPv6: 2001:227:e857:1:0:0:0:0:1/64</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>In the Shorewall documentation and manpages, we have tried to make
    it clear which type of address is accepted in each specific case.</para>

    <para>For more information about addressing, see the<ulink
    url="shorewall_setup_guide.htm#Addressing"> Setup Guide</ulink>.</para>
  </section>

  <section id="SOURCE-DEST">
    <title>Specifying SOURCE and DEST</title>

    <para>Entries in Shorewall configuration files often deal with the source
    (SOURCE) and destination (DEST) of connections and Shorewall implements a
    uniform way for specifying them.</para>

    <para>A SOURCE or DEST consists of one to three parts separated by colons
    (":"):</para>

    <orderedlist>
      <listitem>
        <para>ZONE — The name of a zone declared in
        <filename>/etc/shorewall/zones</filename> or
        <filename>/etc/shorewall6/zones</filename>. This part is only
        available in the rules file (<filename>/etc/shorewall/rules</filename>
        and <filename>/etc/shorewall6/rules</filename>).</para>
      </listitem>

      <listitem>
        <para>INTERFACE — The name of an interface that matches an entry in
        <filename>/etc/shorewall/interfaces</filename>
        (<filename>/etc/shorewall6/interfaces</filename>).</para>
      </listitem>

      <listitem>
        <para>ADDRESS LIST — A list of one or more addresses (host or network)
        or address ranges, separated by commas. In an IPv6 configuration, this
        list must be included in square or angled brackets ("[...]" or
        "&lt;...&gt;"). The list may have <link
        linkend="Exclusion">exclusion</link>.</para>
      </listitem>
    </orderedlist>

    <para>Examples.</para>

    <orderedlist>
      <listitem>
        <para>All hosts in the <emphasis role="bold">net</emphasis> zone —
        <emphasis role="bold">net</emphasis></para>
      </listitem>

      <listitem>
        <para>Subnet 192.168.1.0/29 in the <emphasis
        role="bold">loc</emphasis> zone — <emphasis
        role="bold">loc:192.168.1.0/29</emphasis></para>
      </listitem>

      <listitem>
        <para>All hosts in the net zone connecting through <filename
        class="devicefile">ppp0</filename> — <emphasis
        role="bold">net:ppp0</emphasis></para>
      </listitem>

      <listitem>
        <para>All hosts interfaced by <filename
        class="devicefile">eth3</filename> — <emphasis
        role="bold">eth3</emphasis></para>
      </listitem>

      <listitem>
        <para>Subnet 10.0.1.0/24 interfacing through <filename><filename
        class="devicefile">eth2</filename></filename> — <emphasis
        role="bold">eth2:10.0.1.0/24</emphasis></para>
      </listitem>

      <listitem>
        <para>Host 2002:ce7c:92b4:1:a00:27ff:feb1:46a9 in the <emphasis
        role="bold">loc</emphasis> zone — <emphasis
        role="bold">loc:[2002:ce7c:92b4:1:a00:27ff:feb1:46a9]</emphasis></para>
      </listitem>

      <listitem>
        <para>The primary IP address of eth0 in the $FW zone - <emphasis
        role="bold">$FW:&amp;eth0</emphasis> (see <link
        linkend="Rvariables">Run-time Address Variables</link> below)</para>
      </listitem>

      <listitem>
        <para>All hosts in Vatican City - <emphasis
        role="bold">net:^VA</emphasis> (Shorwall 4.5.4 and later - See <ulink
        url="ISO-3661.html">this article</ulink>).</para>
      </listitem>
    </orderedlist>
  </section>

  <section id="INCLUDE">
    <title>INCLUDE Directive</title>

    <para>Any configuration file may contain INCLUDE directives. An INCLUDE
    directive consists of the word INCLUDE followed by a path name and causes
    the contents of the named file to be logically included into the file
    containing the INCLUDE. Relative path names given in an INCLUDE directive
    are resolved using the current CONFIG_PATH setting (see <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>

    <para>INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
    directives are ignored with a warning message.</para>

    <para>Beginning with Shorewall 4.4.17, the INCLUDE directive may also
    appear in the following <ulink
    url="shorewall_extension_scripts.htm">extension scripts</ulink>:</para>

    <itemizedlist>
      <listitem>
        <para>clear</para>
      </listitem>

      <listitem>
        <para>findgw</para>
      </listitem>

      <listitem>
        <para>init</para>
      </listitem>

      <listitem>
        <para>isusable</para>
      </listitem>

      <listitem>
        <para>refresh</para>
      </listitem>

      <listitem>
        <para>refreshed</para>
      </listitem>

      <listitem>
        <para>restore</para>
      </listitem>

      <listitem>
        <para>restored</para>
      </listitem>

      <listitem>
        <para>start</para>
      </listitem>

      <listitem>
        <para>started</para>
      </listitem>

      <listitem>
        <para>stop</para>
      </listitem>

      <listitem>
        <para>stopped</para>
      </listitem>

      <listitem>
        <para>tcclear</para>
      </listitem>
    </itemizedlist>

    <para>When used in these scripts, the INCLUDEd files are copied into the
    compiled firewall script.</para>

    <caution>
      <para>Prior to Shorewall 4.4.17, if you are using <ulink
      url="Shorewall-Lite.html">Shorewall Lite</ulink> , it is not advisable
      to use INCLUDE in the <filename>params</filename> file in an export
      directory if you set EXPORTPARAMS=Yes in <ulink
      url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5). If you do
      that, you must ensure that the included file is also present on the
      firewall system's <filename
      class="directory">/etc/shorewall-lite/</filename> directory.</para>

      <para>If you only need the <filename>params</filename> file at compile
      time, you can set EXPORTPARAMS=No in
      <filename>shorewall.conf</filename>. That prevents the
      <filename>params</filename> file from being copied into the compiled
      script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
      <filename>params</filename> file. Note that with Shorewall 4.4.17 and
      later:</para>

      <itemizedlist>
        <listitem>
          <para>The variables set at compile time are available at run-time
          even with EXPORTPARAMS=No.</para>
        </listitem>

        <listitem>
          <para>The INCLUDE directive in the <filename>params</filename> file
          is processed at compile time and the INCLUDEd file is copied into
          the compiled script.</para>
        </listitem>
      </itemizedlist>
    </caution>

    <example id="include">
      <title>Use of INCLUDE</title>

      <programlisting>     shorewall/params.mgmt:
 
        MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3
         TIME_SERVERS=4.4.4.4
         BACKUP_SERVERS=5.5.5.5
 
        ----- end params.mgmt -----
 
     shorewall/params:
 
        # Shorewall 1.3 /etc/shorewall/params
         [..]
         #######################################
  
         INCLUDE params.mgmt    
   
       # params unique to this host here
       #LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
 
       ----- end params -----
 
     shorewall/rules.mgmt:
 
       ACCEPT net:$MGMT_SERVERS   $FW                  tcp    22
       ACCEPT $FW                 net:$TIME_SERVERS    udp    123
       ACCEPT $FW                 net:$BACKUP_SERVERS  tcp    22
 
      ----- end rules.mgmt -----
 
     shorewall/rules:
 
      # Shorewall version 1.3 - Rules File
       [..]
       #######################################
  
       INCLUDE rules.mgmt     
   
       # rules unique to this host here
       #LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
 
     ----- end rules -----</programlisting>

      <para>You may include multiple files in one command using an <link
      linkend="Embedded">embedded shell command</link>.</para>

      <para>Example (include all of the files ending in ".rules" in a
      directory:):<programlisting>gateway:/etc/shorewall # ls rules.d
ALL.rules  DNAT.rules  FW.rules  NET.rules  REDIRECT.rules  VPN.rules
gateway:/etc/shorewall # </programlisting></para>

      <para>/etc/shorewall/rules:<programlisting>SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>

      <para>If you are the sort to put such an entry in your rules file even
      though /etc/shorewall/rules.d might not exist or might be empty, then
      you probably want:</para>

      <programlisting>SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules 2&gt; /dev/null || true</programlisting>

      <para>Beginning with Shorewall 4.5.2, in files other than
      <filename>/etc/shorewall/params</filename> and
      <filename>/etc/shorewall/conf</filename>, INCLUDE may be immediately
      preceded with '?' to signal that the line is a compiler directive and
      not configuration data.</para>

      <para>Example:</para>

      <programlisting>?INCLUDE common.rules</programlisting>
    </example>
  </section>

  <section>
    <title>?FORMAT Directive</title>

    <para>A number of configuration files support multiple formats. Prior to
    Shorewall 4.5.11, the format was specified by a line having 'FORMAT' as
    the first token. This requires each of the file processors to handle
    FORMAT separately.</para>

    <para>In Shorewall 4.5.11, the ?FORMAT directive was created to centralize
    processing of FORMAT directives. The old entries, while still supported,
    are now deprecated.</para>

    <para>The ?FORMAT directive is as follows:</para>

    <variablelist>
      <varlistentry>
        <term>?FORMAT <replaceable>format</replaceable></term>

        <listitem>
          <para>Where format is an integer. In all cases, the default format
          is 1. The following table shows the files that have different
          formats and the supported formats for each.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <informaltable>
      <tgroup align="left" cols="2">
        <tbody>
          <row>
            <entry>FILE</entry>

            <entry>FORMATS</entry>
          </row>

          <row>
            <entry>action files (action.*)</entry>

            <entry>1 and 2</entry>
          </row>

          <row>
            <entry>conntrack</entry>

            <entry>1, 2 and 3</entry>
          </row>

          <row>
            <entry>interfaces</entry>

            <entry>1 and 2</entry>
          </row>

          <row>
            <entry>macro files (macro.*)</entry>

            <entry>1 and 2</entry>
          </row>

          <row>
            <entry>tcrules</entry>

            <entry>1 and 2</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section>
    <title>?COMMENT Directive</title>

    <para>A number of files allow attaching comments to generated Netfilter
    rules:</para>

    <simplelist>
      <member><filename>accounting</filename></member>

      <member><filename>action</filename>.* files</member>

      <member><filename>blrules</filename></member>

      <member><filename>conntrack</filename></member>

      <member><filename>macro</filename>.* files</member>

      <member><filename>masq</filename></member>

      <member><filename>nat</filename></member>

      <member><filename>rules</filename></member>

      <member><filename>secmarks</filename></member>

      <member><filename>tcrules</filename></member>

      <member><filename>tunnels</filename></member>
    </simplelist>

    <para>Prior to Shorewall 4.5.11, comments were specified by a line having
    COMMENT as the first token. The remainder of the line is treated as a
    comment to be attached to rules.</para>

    <para>In Shorewall 4.5.11, the ?COMMENT directive was created to
    centralize processing of COMMENT directives. The old entries, while still
    supported, are now deprecated.</para>

    <para>Use of this directive requires Comment support in your kernel and
    iptables - see the output of <command><link
    linkend="capabilities">shorewall show
    capabilities</link></command>.</para>

    <para>The ?COMMENT directive is as follows:</para>

    <variablelist>
      <varlistentry>
        <term>[?]COMMENT [ <replaceable>comment</replaceable> ]</term>

        <listitem>
          <para>If <replaceable>comment</replaceable> is present, it will
          appear enclosed in /*....*/ in the output of the <command>shorewall
          show </command>and <command>shorewall dump</command> commands. If no
          <replaceable>comment</replaceable> is present, the rules generated
          by following entries will not have comments attached.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Example (<filename>/etc/shorewall/rules</filename>):</para>

    <programlisting>?COMMENT Stop NETBIOS noise

REJECT          loc                             net                     tcp     137,445
REJECT          loc                             net                     udp     137:139

?COMMENT Stop my idiotic work laptop from sending to the net with an HP source/dest IP address

DROP            loc:!192.168.0.0/22             net

?COMMENT</programlisting>

    <para>Here's the corresponding output from
    <filename>/sbin/shorewall-lite</filename>:</para>

    <programlisting>gateway:~ # <command>shorewall-lite show loc-net</command>
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008

Counters reset Mon Oct 16 14:52:17 PDT 2006

Chain loc-net (1 references)
 pkts bytes target     prot opt in     out     source               destination
    0     0 LOG        tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           tcp dpt:25
    0     0 LOG        udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:1025:1031
    0     0 reject     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           multiport dports 137,445 <emphasis
        role="bold">/* Stop NETBIOS noise */</emphasis>
    0     0 reject     udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:137:139 <emphasis
        role="bold">/* Stop NETBIOS noise */</emphasis>
    0     0 DROP       all  --  *      *      !192.168.0.0/22       0.0.0.0/0           <emphasis
        role="bold">/* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */</emphasis>
    5   316 ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0
gateway:~ #

</programlisting>

    <para>?COMMENT lines in macro files work somewhat differently from other
    files. ?COMMENT lines in macros are ignored if COMMENT support is not
    available or if there was a COMMENT in use when the top-level macro was
    invoked. This allows the following:</para>

    <para><filename>/usr/share/shorewall/macro.SSH</filename>:</para>

    <para><programlisting>#ACTION SOURCE DEST  PROTO DEST    SOURCE  RATE  USER/
#                          PORT(S) PORT(S) LIMIT GROUP
?COMMENT SSH
PARAM   -      -     tcp   22 </programlisting>
    <filename>/etc/shorewall/rules</filename>:<programlisting>?COMMENT Allow SSH from home
SSH(ACCEPT)    net:$MYIP      $FW
?COMMENT</programlisting>The comment line in macro.SSH will not override the
    ?COMMENT line in the rules file and the generated rule will show <emphasis
    role="bold">/* Allow SSH from home */</emphasis> when displayed through
    the Shorewall show and dump commands.</para>
  </section>

  <section id="CONFIG_PATH">
    <title>CONFIG_PATH</title>

    <para>The CONFIG_PATH option in shorewall.conf determines where the
    compiler searches for configuration files. The default setting is
    CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that the
    compiler first looks in /etc/shorewall and if it doesn't find the file, it
    then looks in /usr/share/shorewall.</para>

    <para>You can change this setting to have the compiler look in different
    places. For example, if you want to put your own versions of standard
    macros in /etc/shorewall/Macros, then you could set
    CONFIG_PATH=/etc/shorewall:/etc/shorewall/Macros:/usr/share/shorewall and
    the compiler will use your versions rather than the standard ones.</para>
  </section>

  <section id="Variables">
    <title>Using Shell Variables</title>

    <para>You may use the <filename>/etc/shorewall/params</filename> file to
    set shell variables that you can then use in 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>

    <para>The following variable names must be avoided. Those in <emphasis
    role="bold">bold font</emphasis> must be avoided in all Shorewall
    versions; those in regular font must be avoided in versions prior to
    4.4.8.</para>

    <simplelist>
      <member><emphasis role="bold">Any option from <ulink
      url="manpages/shorewall.conf.html">shorewall.conf</ulink>
      (5)</emphasis></member>

      <member><emphasis role="bold">COMMAND</emphasis></member>

      <member><emphasis role="bold">CONFDIR</emphasis></member>

      <member>DEBUG</member>

      <member>ECHO_E</member>

      <member>ECHO_N</member>

      <member>EXPORT</member>

      <member>FAST</member>

      <member>FILEMODE</member>

      <member>HOSTNAME</member>

      <member>IPT_OPTIONS</member>

      <member>NOROUTES</member>

      <member>PREVIEW</member>

      <member>PRODUCT</member>

      <member>PROFILE</member>

      <member>PURGE</member>

      <member>RECOVERING</member>

      <member>RESTOREPATH</member>

      <member>RING_BELL</member>

      <member><emphasis role="bold">SHAREDIR</emphasis></member>

      <member><emphasis role="bold">Any name beginning with SHOREWALL_ or
      SW_</emphasis></member>

      <member>STOPPING</member>

      <member>TEST</member>

      <member>TIMESTAMP</member>

      <member>USE_VERBOSITY</member>

      <member><emphasis role="bold">VARDIR</emphasis></member>

      <member><emphasis role="bold">VARLIB</emphasis></member>

      <member>VERBOSE</member>

      <member>VERBOSE_OFFSET</member>

      <member>VERSION</member>
    </simplelist>

    <para>Example:</para>

    <blockquote>
      <programlisting>    /etc/shorewall/params
 
        NET_IF=eth0
        NET_BCAST=130.252.100.255
        NET_OPTIONS=routefilter,routefilter
 
    /etc/shorewall/interfaces record:

        net $NET_IF $NET_BCAST $NET_OPTIONS
 
    The result will be the same as if the record had been written
 
        net eth0 130.252.100.255 routefilter,routefilter
 </programlisting>
    </blockquote>

    <para>Variables may be used anywhere in the other configuration
    files.<note>
        <para>If you use "$FW" on the right side of assignments in the
        <filename>/etc/shorewall/params</filename> file, you must also set the
        FW variable in that file.</para>

        <para>Example:<programlisting>/etc/shorewall/zones:

        #ZONE        TYPE          OPTIONS
        <emphasis role="bold">fw</emphasis>           firewall

/etc/shorewall/params:

        FW=<emphasis role="bold">fw</emphasis>
        BLARG=$FW:206.124.146.176</programlisting></para>
      </note></para>

    <para>Because the <filename>/etc/shorewall/params</filename> file is
    simply sourced into the shell, you can place arbitrary shell code in the
    file and it will be executed each time that the file is read. Any code
    included should follow these guidelines:</para>

    <orderedlist>
      <listitem>
        <para>The code should not have side effects, especially on other
        shorewall configuration files.</para>
      </listitem>

      <listitem>
        <para>The code should be safe to execute multiple times without
        producing different results.</para>
      </listitem>

      <listitem>
        <para>Should not depend on where the code is called from.</para>
      </listitem>

      <listitem>
        <para>Should not assume anything about the state of Shorewall.</para>
      </listitem>

      <listitem>
        <para>The names of any functions or variables declared should begin
        with an upper case letter.</para>
      </listitem>

      <listitem>
        <para>The <filename>/etc/shorewall/params</filename> file is processed
        by the compiler at compile-time and by the compiled script at
        run-time. If you have set EXPORTPARAMS=No in
        <filename>shorewall.conf</filename>, then the
        <filename><filename>params</filename></filename> file is only
        processed by the compiler; it is not run by the compiled script.
        Beginning with Shorewall 4.4.17, the values of the variables set at
        compile time are available at run time with EXPORTPRARMS=No.</para>
      </listitem>

      <listitem>
        <para>If you are using <ulink url="Shorewall-Lite.html">Shorewall
        Lite</ulink> and if the <filename>params</filename> script needs to
        set shell variables based on the configuration of the firewall system,
        you can use this trick:</para>

        <programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>

        <para>The <command>shorewall-lite call</command> command allows you to
        call interactively any Shorewall function that you can call in an
        extension script.</para>

        <note>
          <para>Within your configuration files, only the $VAR and ${VAR}
          forms of variable expansion are supported. You may not use the more
          exotic forms supported by the shell (${VAR:=val}, ${VAR:-val},
          ...)</para>
        </note>
      </listitem>
    </orderedlist>

    <para>Beginning with Shorewall 4.4.27, you may also use options in <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5) (e.g.,
    $BLACKLIST_LOGLEVEL).</para>

    <note>
      <para>When an option is set to 'No' in shorewall.conf, the corresponding
      shell variable will be empty.</para>
    </note>

    <note>
      <para>Options that were not set in shorewall.conf will expand to their
      default value.</para>
    </note>

    <para id="Rvariables">Beginning with Shorewall 4.5.2, configuration files
    can access variables defined in the <ulink
    url="Install.htm#shorewallrc">shorewallrc file</ulink>.</para>

    <para>Beginning with Shorewall 4.5.11, variables can be altered by
    compiler directives.</para>

    <variablelist>
      <varlistentry>
        <term>?SET <replaceable>variable value</replaceable></term>

        <listitem>
          <para>The <replaceable>variable</replaceable> can be specified
          either with or without a leading '$' to allow using both Perl and
          Shell variable representation. The ${...} form (e.g. ${foo}) is not
          allowed.</para>

          <para>The <replaceable>value</replaceable> is a Perl-compatible
          expression.</para>

          <note>
            <para>The Shorewall compiler performs variable expansion within
            the expression. So variables are expanded even when they appear in
            single quotes.</para>
          </note>

          <note>
            <para>If a variable within the expression can contain a
            non-numeric value, it is a good idea to enclose it in quotes.
            Otherwise, the Shorewall compiler has to guess whether to enclose
            the variable's value in quotes or not.</para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>?RESET <replaceable>variable</replaceable></term>

        <listitem>
          <para>Removes the named <replaceable>variable</replaceable> from the
          compiler's variable table.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Action variables are read-only and cannot be ?SET (although you can
    change their values <ulink url="Actions.html#Embedded">using embedded
    Perl</ulink>).</para>

    <para>Beginning with Shorewall 4.5.13, <link
    linkend="ShorewallVariables">Shorewall Variables</link> may be set. When
    setting a Shorewall Variable, the <replaceable>variable</replaceable> must
    include the leading '@' and the @{...} form is not allowed.</para>
  </section>

  <section id="AddressVariables">
    <title>Address Variables</title>

    <para>Given that shell variables are expanded at compile time, there is no
    way to cause such variables to be expanded at run time. Prior to Shorewall
    4.4.17, this made it difficult (to impossible) to include dynamic IP
    addresses in a <ulink url="Shorewall-Lite.html">Shorewall-lite</ulink>
    configuration.</para>

    <para>Version 4.4.17 implemented <firstterm>Run-time address
    variables</firstterm>. In configuration files, these variables are
    expressed as an apersand ('&amp;') followed by the logical name of an
    interface defined in shorewall-interfaces (5). Wildcard interfaces (those
    ending in '+') are not supported and will cause a compilation
    error.</para>

    <variablelist>
      <varlistentry>
        <term>Example:</term>

        <listitem>
          <para><emphasis role="bold">&amp;eth0</emphasis> would represent the
          primary IP address of eth0.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Beginning with Shorewall 4.5.11, you can define your own address
    variables by using this syntax:</para>

    <simplelist>
      <member>&amp;{<replaceable>variable</replaceable>}</member>
    </simplelist>

    <para>where <replaceable>variable</replaceable> is a valid shell variable
    name. The generated script will verify that the
    <replaceable>variable</replaceable> contains a valid host or network
    address, either from the environment or from it being assigned in your
    <emphasis>init</emphasis> <ulink
    url="shorewall_extension_scripts.htm">extension script</ulink>, and will
    raise an error if it does not. In the error case, the state of the
    firewall will remain unchanged.</para>

    <para>Example:</para>

    <para>/etc/shorewall/init:</para>

    <programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>

    <para>/etc/shorewall/rules:</para>

    <programlisting>test:debug	net:<emphasis role="bold">&amp;{SMC_ADDR}</emphasis>		fw</programlisting>

    <para>A second form is also available beginning with Shorewall
    4.5.11</para>

    <simplelist>
      <member>%{<replaceable>variable</replaceable>}</member>
    </simplelist>

    <para>Unlike with the first form, this form does not require the variable
    to be set. If the variable is empty, the generated script will supply the
    all-zeros address (0.0.0.0 in IPv4 and :: in IPv6). In most cases, the
    compiler simply omits rules containing matches on the all-zeros
    address.</para>

    <para>Example:</para>

    <para>/etc/shorewall/init:</para>

    <programlisting><emphasis role="bold">SMC_ADDR</emphasis>=10.1.10.11</programlisting>

    <para>/etc/shorewall/rules:</para>

    <programlisting>test:debug	net:<emphasis role="bold">%{SMC_ADDR}</emphasis>		fw</programlisting>

    <important>
      <para>For a particular address variable, all references must use the
      same prefix character ('&amp;' or '%'). Otherwise, the following error
      message is raised:</para>

      <simplelist>
        <member>ERROR: Mixed required/optional usage of address variable
        <replaceable>variable</replaceable></member>
      </simplelist>
    </important>

    <para>Run-time address variables may be used in the SOURCE and DEST column
    of the following configuration files:</para>

    <itemizedlist>
      <listitem>
        <para><ulink
        url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="Actions.html">Action</ulink> files</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-accounting.html">shorewall-blacklist</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="Macros.html">Macro</ulink> files</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5)</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="manpages/shorewall-tos.html">shorewall-tos</ulink>
        (5)</para>
      </listitem>
    </itemizedlist>

    <para>They may also appear in the ORIGINAL DEST column of:</para>

    <itemizedlist>
      <listitem>
        <para><ulink
        url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="Macros.html">Macro</ulink> files</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
      </listitem>
    </itemizedlist>

    <para>For optional interfaces, if the interface is not usable at the time
    that the firewall starts, one of two approaches are taken, depending on
    the context:</para>

    <itemizedlist>
      <listitem>
        <para>the all-zero address will be used (0.0.0.0 in IPv4 and :: in
        IPv6), resulting in no packets matching the rule (or all packets if
        used with exclusion).</para>
      </listitem>

      <listitem>
        <para>the entire rule is omitted from the ruleset.</para>
      </listitem>
    </itemizedlist>

    <para>Beginning with Shorewall 4.5.1, <firstterm>Run-time Gateway
    Variables</firstterm> in the form of a percent sign ('%') followed by a
    logical interface name are also supported. These are expanded at run-time
    to the gateway through the named interface. For optional interfaces, if
    the interface is not usable at the time that the firewall starts, the nil
    address will be used (0.0.0.0 in IPv4 and :: in IPv6), resulting in no
    packets matching the rule. Run-time gateway variables may be used in the
    SOURCE and DEST columns of the following configuration files:</para>

    <itemizedlist>
      <listitem>
        <para><ulink
        url="manapges/shorewall-accounting.html">shorewall-accounting</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="Actions.html">Action</ulink> files</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-accounting.html">shorewall-blacklist</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="Macros.html">Macro</ulink> files</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-nat.html">shorewall-nat</ulink>(5) (As a
        qualifier to the INTERFACE).</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5)</para>
      </listitem>

      <listitem>
        <para><ulink
        url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
        (5)</para>
      </listitem>

      <listitem>
        <para><ulink url="manpages/shorewall-tos.html">shorewall-tos</ulink>
        (5)</para>
      </listitem>
    </itemizedlist>

    <variablelist>
      <varlistentry>
        <term>Example:</term>

        <listitem>
          <para><emphasis role="bold">%eth0</emphasis> would represent the IP
          address of the gateway out of eth0.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>If there is no gateway out of the named interface, the nil IP
    address is used (0.0.0.0 in IPv4 and :: in IPv6). That way, the generated
    rule will match no packets (or all packets if used with exclusion).</para>
  </section>

  <section id="ActionVariables">
    <title>Action Variables</title>

    <para>Action variables were introduced in Shorewall 4.4.16 and may be
    accessed within the body of an <ulink
    url="Actions.html">action</ulink>.</para>

    <variablelist>
      <varlistentry>
        <term>Parameter variables</term>

        <listitem>
          <para>Parameter variables expand to the value of the corresponding
          action parameter. <emphasis>$1</emphasis> is the first parameter,
          <emphasis>$2</emphasis> is the second parameter and so on.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Chain name</term>

        <listitem>
          <para>Beginning with Shorewall 4.5.10, $0 expands to the name of the
          action chain. Shorewall generates a separate chain for each unique
          (action,log-level,log-tag,parameters) tupple. The first such chain
          has the same name as the action itself. Subsequent chains are formed
          by prepending '%' to the action name and appending a number to
          insure uniqueness. For an action called 'Action', the chains would
          be <emphasis>Action</emphasis>, <emphasis>%Action</emphasis>,
          <emphasis>%Action0</emphasis>, <emphasis>%Action1</emphasis> and so
          on.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="ShorewallVariables">
    <title>Shorewall Variables</title>

    <para>Shorewall Variables were introduced in Shorewall 4.5.11. To insure
    uniqueness, these variables start with the character @; the name of the
    variable must be enclosed in {...} when the following character is
    alphanumeric or is an underscore ("_"). With the exception of @0 (or it's
    alias @chain), Shorewall variables may only be used within an action
    body.</para>

    <para>Prior to Shorewall 4.5.13, Shorewall variables are read-only.
    Beginning with Shorewall 4.5.13, their values may be altered using the
    ?SET directive.</para>

    <para>The Shorewall variables are:</para>

    <variablelist>
      <varlistentry>
        <term>@0 and @chain (@{0} and @{chain})</term>

        <listitem>
          <para>Expands to the name of the current chain. Unlike $0, @0 has
          all non-alphanumeric characters except underscore removed. Also
          unlike $0, @0 may be used in SWITCH columns in configuration
          files.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>@1, @2, ... (@{1}, @{2}, ...</term>

        <listitem>
          <para>These are synonyms for the Action parameter variables $1, $2,
          etc.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>@loglevel (@{loglevel})</term>

        <listitem>
          <para>Expands to the log level specified when the action was
          invoked.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>@logtag (@{logtag})</term>

        <listitem>
          <para>Expands to the log tag specified when the action was
          invoked.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>@disposition (@{disposition})</term>

        <listitem>
          <para>Added in Shorewall 4.5.13. When a non-inlined action is
          entered, this variable is set to the empty value. When an inline
          action is entered, the variable's value is unchanged.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>@caller (@{caller})</term>

        <listitem>
          <para>Added in Shorewall 4.5.13. Within an action, expands to the
          name of the chain that invoked the action.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Beginning with Shorewall 4.5.13, the values of @chain and
    @disposition are used to generated the --log-prefix in logging rules. When
    either is empty, the historical value is used to generate the
    --log-prefix.</para>
  </section>

  <section id="Conditional">
    <title>Conditional Entries</title>

    <para>Beginning with Shorewall 4.5.2, lines in configuration files may be
    conditionally included or omitted based on the setting of <link
    linkend="Variables">Shell variables</link>.</para>

    <para>The general form is:</para>

    <programlisting>?IF <replaceable>$variable

</replaceable>&lt;lines to be included if $variable is non-empty and non-zero&gt;

?ELSE

&lt;lines to be omitted if $variable is non-empty and non-zero&gt;

?ENDIF</programlisting>

    <para>The compiler predefines two special
    <replaceable>variable</replaceable>s that may only be used in ?IF
    lines:</para>

    <variablelist>
      <varlistentry>
        <term>__IPV4</term>

        <listitem>
          <para>True if this is an IPv4 compilation</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>__IPV6</term>

        <listitem>
          <para>True if this is an IPv6 compilation.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Unless <replaceable>variable</replaceable> is one of these
    pre-defined ones, it is searched for in the following places in the order
    listed.</para>

    <itemizedlist>
      <listitem>
        <para>the compiler's environmental variables.</para>
      </listitem>

      <listitem>
        <para>variables set in
        <filename>/etc/shorewall/params</filename>.</para>
      </listitem>

      <listitem>
        <para>options set in
        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
      </listitem>

      <listitem>
        <para>options set in the <filename>shorewallrc</filename> file when
        Shorewall Core was installed.</para>
      </listitem>
    </itemizedlist>

    <important>
      <para>Beginning with Shorewall 4.5.11, the compiler's environmental
      variables are search last rather than first.</para>
    </important>

    <para>If the <replaceable>variable</replaceable> is still not
    found:</para>

    <itemizedlist>
      <listitem>
        <para>if it begins with '__', then those leading characters are
        stripped off.</para>
      </listitem>

      <listitem>
        <para>the variable is then searched for in the defined
        <firstterm>capabilities</firstterm>. The current set of capabilities
        may be obtained by the command <command>shorewall show
        capabilities</command> (the capability names are in
        parentheses).</para>
      </listitem>
    </itemizedlist>

    <para>If it is not found in any of those places, the
    <replaceable>variable</replaceable> is assumed to have a value of 0
    (false) in Shorewall versions prior to 4.5.11. In 4.5.11 and later, it is
    assumed to have the value '' (an empty string, which also evaluates to
    false).</para>

    <para>The setting in <filename>/etc/shorewall/params</filename> by be
    overridden at runtime, provided the setting in
    <filename>/etc/shorewall/params</filename> is done like this:</para>

    <programlisting>[ -n "${<replaceable>variable</replaceable>:=0}" ]</programlisting>

    <para>or like this:</para>

    <programlisting>[ -n "${<replaceable>variable</replaceable>}" ] || <replaceable>variable</replaceable>=0</programlisting>

    <para>Either of those will set variable to 0 if it is not set to a
    non-empty value in the environment. The setting can be overridden at
    runtime:</para>

    <programlisting><replaceable>variable</replaceable>=1 shorewall restart -c # use -c to force recompilation if AUTOMAKE=Yes in /etc/shorewall/shorewall.conf</programlisting>

    <para>The ?ELSE may be omitted if there are no lines to be omitted.</para>

    <para>The test may also be inverted using '!':</para>

    <programlisting>?IF ! <replaceable>$variable

</replaceable>&lt;lines to be omitted if $variable is non-empty and non-zero&gt;

?ELSE

&lt;lines to be included if $variable is non-empty and non-zero&gt;

?ENDIF</programlisting>

    <para>Conditional entries may be nested but the number of ?IFs must match
    the number of ?ENDs in any give file. <link linkend="INCLUDE">INCLUDE
    directives</link> are ignored in omitted lines.</para>

    <programlisting>?IF <replaceable>$variable1

</replaceable>&lt;lines to be included if $variable1 is non-empty and non-zero&gt;

   ?IF $variable2

&lt;lines to be included if $variable1 and $variable2 are non-empty and non-zero&gt;

   ?ELSE

&lt;lines to be omitted if $variable1 is non-empty and non-zero and if $variable2 is empty or zero&gt;

   ?ENDIF
<replaceable>
</replaceable>&lt;lines to be included if $variable1 is non-empty and non-zero&gt;

?ELSE

&lt;lines to be omitted if $variable is non-empty and non-zero&gt;

?ENDIF</programlisting>

    <para>Beginning with Shorewall 4.5.6, rather than a simple variable in ?IF
    directives, Perl-compatible expressions are allowed (after the Shorewall
    compiler expands all variables, the resulting expression is then evaluated
    by Perl). Variables in the expressions are as described above.</para>

    <para>Example:</para>

    <programlisting>?IF $BLACKLIST_LOGLEVEL == 6 &amp;&amp; ! __LOG_OPTIONS</programlisting>

    <para>Additionally, a ?ELSIF directive is supported.</para>

    <para>Example:</para>

    <programlisting>?IF <replaceable>expression-1

</replaceable>&lt;lines to be included if expression-1 evaluates to true (non-empty and non-zero)

?ELSIF <replaceable>expression1-2</replaceable>

&lt;lines to be included if expression-1 evaluates to false (zero or empty) and expression-2 evaluates to true

?ELSIF <replaceable>expression-3
</replaceable>
&lt;lines to be included if expression-1 and expression-2 both evalute to false and expression-3 evalutes to true

?ELSE

&lt;lines to be included if all three expressions evaluate to false.

?ENDIF</programlisting>
  </section>

  <section id="Embedded">
    <title>Embedded Shell and Perl</title>

    <para>Earlier versions of Shorewall offered <ulink
    url="shorewall_extension_scripts.htm">extension scripts</ulink> to allow
    users to extend Shorewall's functionality. Extension scripts were designed
    to work under the limitations of the Bourne Shell. With the current
    Perl-based compiler, <firstterm>Embedded scripts</firstterm> offer a
    richer and more flexible extension capability.</para>

    <para>While inline scripts may be written in either Shell or Perl, those
    written in Perl have a lot more power. They may be used in all
    configuration files except <filename>/etc/shorewall/params</filename> and
    <filename>/etc/shorewall/shorewall.conf</filename>.</para>

    <para><emphasis role="bold">Note:</emphasis>In this section, '[' and ']'
    are meta-characters which indicate that what they enclose is optional and
    may be omitted.</para>

    <para>Single line scripts take one of the following forms:</para>

    <itemizedlist>
      <listitem>
        <para>[<emphasis role="bold">?</emphasis>]<emphasis
        role="bold">PERL</emphasis> &lt;<emphasis>perl
        script</emphasis>&gt;</para>
      </listitem>

      <listitem>
        <para>[<emphasis role="bold">?</emphasis>]<emphasis
        role="bold">SHELL</emphasis> &lt;<emphasis>shell
        script</emphasis>&gt;</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>The optional leading question mark (?) is allowed in Shorewall
      4.5.5 and later.</para>
    </note>

    <para>Shell scripts run in a child shell process and their output is piped
    back to the compiler which processes that output as if it were embedded at
    the point of the script.</para>

    <para>Example: The following entries in
    <filename>/etc/shorewall/rules</filename> are equivalent:<programlisting>SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done</programlisting><programlisting>ACCEPT net fw tcp 22
ACCEPT loc fw tcp 22
ACCEPT dmz fw tcp 22</programlisting></para>

    <para>Perl scripts run in the context of the compiler process using Perl's
    eval() function. Perl scripts are implicitly prefixed by the
    following:</para>

    <programlisting>package Shorewall::User;
use Shorewall::Config ( qw/shorewall/ );</programlisting>

    <para>To produce output that will be processed by the compiler as if it
    were embedded in the file at the point of the script, pass that output to
    the Shorewall::Config::shorewall() function. The Perl equivalent of the
    above SHELL script would be:<programlisting>PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</programlisting>A
    couple of more points should be mentioned:</para>

    <orderedlist>
      <listitem>
        <para>Compile-time extension scripts are also implicitly prefixed by
        "package Shorewall::User;".</para>
      </listitem>

      <listitem>
        <para>A <emphasis role="bold">compile</emphasis> extension script is
        supported. That script is run early in the compilation process and
        allows users to load additional modules and to define data and
        functions for use in subsequent embedded scripts and extension
        scripts.</para>
      </listitem>

      <listitem>
        <para><ulink url="ManualChains.html">Manual Chains</ulink> may be
        added in the <emphasis role="bold">compile</emphasis> extension
        script..</para>
      </listitem>
    </orderedlist>

    <para>Multi-line scripts use one of the following forms:<programlisting>[<emphasis
          role="bold">?</emphasis>]<emphasis role="bold">BEGIN SHELL</emphasis>
&lt;<emphasis>shell script</emphasis>&gt;
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
          role="bold">SHELL</emphasis> ]</programlisting><programlisting>[<emphasis
          role="bold">?</emphasis>]<emphasis role="bold">BEGIN PERL</emphasis> [<emphasis
          role="bold">;</emphasis>]
&lt;<emphasis>perl script</emphasis>&gt;
[<emphasis role="bold">?</emphasis>]<emphasis role="bold">END</emphasis> [ <emphasis
          role="bold">PERL</emphasis> ] [<emphasis role="bold">;</emphasis>]</programlisting><note>
        <para>The optional leading question mark (?) is allowed in Shorewall
        4.5.5 and later.</para>
      </note></para>
  </section>

  <section id="dnsnames">
    <title>Using DNS Names</title>

    <caution>
      <para>I personally recommend strongly against using DNS names in
      Shorewall configuration files. If you use DNS names and you are called
      out of bed at 2:00AM because Shorewall won't start as a result of DNS
      problems then don't say that you were not forewarned.</para>
    </caution>

    <para>Host addresses in Shorewall configuration files may be specified as
    either IP addresses or DNS Names.</para>

    <para>DNS names in iptables rules aren't nearly as useful as they first
    appear. When a DNS name appears in a rule, the iptables utility resolves
    the name to one or more IP addresses and inserts those addresses into the
    rule. So changes in the DNS-&gt;IP address relationship that occur after
    the firewall has started have absolutely no effect on the firewall's rule
    set.</para>

    <para>For some sites, using DNS names is very risky. Here's an
    example:</para>

    <programlisting>teastep@ursa:~$ dig pop.gmail.com

; &lt;&lt;&gt;&gt; DiG 9.4.2-P1 &lt;&lt;&gt;&gt; pop.gmail.com
;; global options:  printcmd
;; Got answer:
;; -&gt;&gt;HEADER&lt;&lt;- opcode: QUERY, status: NOERROR, id: 1774
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0

;; QUESTION SECTION:
;pop.gmail.com.               IN A

;; ANSWER SECTION:
pop.gmail.com.          <emphasis role="bold">300</emphasis>   IN CNAME gmail-pop.l.google.com.
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis>   IN A     209.85.201.109
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis>   IN A     209.85.201.111</programlisting>

    <para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
    minutes later, the answer may change!</para>

    <para>So this rule may work for five minutes then suddently stop
    working:</para>

    <programlisting>#ACTION        SOURCE               DEST              PROTO             DEST
#                                                                       PORT(S)
POP(ACCEPT)     loc                  net:pop.gmail.com</programlisting>

    <para>If your firewall rules include DNS names then:</para>

    <itemizedlist>
      <listitem>
        <para>If your <filename>/etc/resolv.conf </filename>is wrong then your
        firewall won't start.</para>
      </listitem>

      <listitem>
        <para>If your <filename>/etc/nsswitch.conf</filename> is wrong then
        your firewall won't start.</para>
      </listitem>

      <listitem>
        <para>If your Name Server(s) is(are) down then your firewall won't
        start.</para>
      </listitem>

      <listitem>
        <para>If your startup scripts try to start your firewall before
        starting your DNS server then your firewall won't start.</para>
      </listitem>

      <listitem>
        <para>Factors totally outside your control (your ISP's router is down
        for example), can prevent your firewall from starting.</para>
      </listitem>

      <listitem>
        <para>You must bring up your network interfaces prior to starting your
        firewall.</para>
      </listitem>
    </itemizedlist>

    <para>Each DNS name must be fully qualified and include a minimum of two
    periods (although one may be trailing). This restriction is imposed by
    Shorewall to insure backward compatibility with existing configuration
    files.</para>

    <example id="validdns">
      <title>Valid DNS Names</title>

      <itemizedlist>
        <listitem>
          <para>mail.shorewall.net</para>
        </listitem>

        <listitem>
          <para>shorewall.net. (note the trailing period).</para>
        </listitem>
      </itemizedlist>
    </example>

    <example id="invaliddns">
      <title>Invalid DNS Names</title>

      <itemizedlist>
        <listitem>
          <para>mail (not fully qualified)</para>
        </listitem>

        <listitem>
          <para>shorewall.net (only one period)</para>
        </listitem>
      </itemizedlist>
    </example>

    <para>DNS names may not be used as:</para>

    <itemizedlist>
      <listitem>
        <para>The server address in a DNAT rule (/etc/shorewall/rules
        file)</para>
      </listitem>

      <listitem>
        <para>In the ADDRESS column of an entry in /etc/shorewall/masq.</para>
      </listitem>

      <listitem>
        <para>In the <filename>/etc/shorewall/nat</filename> file.</para>
      </listitem>
    </itemizedlist>

    <para>These restrictions are imposed by Netfilter and not by
    Shorewall.</para>
  </section>

  <section id="Lists">
    <title>Comma-separated Lists</title>

    <para>Comma-separated lists are allowed in a number of contexts within the
    configuration files. A comma separated list:</para>

    <itemizedlist>
      <listitem>
        <para>Must not have any embedded white space.<programlisting>     Valid:   routefilter,dhcp,arpfilter
     Invalid: routefilter,     dhcp,     arpfilter</programlisting></para>
      </listitem>

      <listitem>
        <para>If you use line continuation to break a comma-separated list,
        the comma must be the last thing on the continued line before '\'
        unless the continuation line has no leading white space.</para>
      </listitem>

      <listitem>
        <para>Entries in a comma-separated list may appear in any
        order.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Compliment">
    <title>Complementing an Address, Subnet, Protocol or Port List</title>

    <para>Where specifying an IP address, a subnet or an interface, you can
    precede the item with <quote>!</quote> to specify the complement of the
    item. For example, !192.168.1.4 means <quote>any host but
    192.168.1.4</quote>. There must be no white space following the
    <quote>!</quote>.</para>

    <para>Similarly, in columns that specify an IP protocol, you can precede
    the protocol name or number by "!". For example, !tcp means "any protocol
    except tcp".</para>

    <para>This also works with port lists, providing that the list contains 15
    or fewer ports (where a <link linkend="Ranges">port range</link> counts as
    two ports). For example !ssh,smtp means "any port except 22 and
    25".</para>

    <para>In Shorewall 4.4.19 and later, icmp type lists are supported but
    complementing an icmp type list is <emphasis>not</emphasis> supported. You
    may, however, complement a single icmp (icmp6) type.</para>
  </section>

  <section id="Exclusion">
    <title>Exclusion Lists</title>

    <para>Where a comma-separated list of addresses is accepted, an
    <firstterm>exclusion list</firstterm> may also be included. An exclusion
    list is a comma-separated list of addresses that begins with "!".</para>

    <para>Example:</para>

    <programlisting>!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>

    <para>The above list refers to "All addresses except 192.168.1.3,
    192.168.1.12 and 192.168.1.32-192.168.1.63.</para>

    <para>Exclusion lists can also be added after a network address.</para>

    <para>Example:</para>

    <programlisting>192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>

    <para>The above list refers to "All addresses in 192.168.1.0-192.168.1.255
    except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
  </section>

  <section id="IPRanges">
    <title>IP Address Ranges</title>

    <para>If you kernel and iptables have iprange match support, you may use
    IP address ranges in Shorewall configuration file entries; IP address
    ranges have the syntax &lt;<emphasis>low IP
    address</emphasis>&gt;-&lt;<emphasis>high IP address</emphasis>&gt;.
    Example: 192.168.1.5-192.168.1.12.</para>

    <para>To see if your kernel and iptables have the required support, use
    the <command>shorewall show capabilities</command> command:</para>

    <programlisting>&gt;~ <command>shorewall show capabilities</command>
... 
Shorewall has detected the following iptables/netfilter capabilities:
   NAT: Available
   Packet Mangling: Available
   Multi-port Match: Available
   Connection Tracking Match: Available
   Packet Type Match: Not available
   Policy Match: Available
   Physdev Match: Available
   <emphasis role="bold">IP range Match: Available &lt;--------------</emphasis></programlisting>
  </section>

  <section id="Ports">
    <title>Protocol Number/Names and Port Numbers/Service Names</title>

    <para>Unless otherwise specified, when giving a protocol number you can
    use either an integer or a protocol name from
    <filename>/etc/protocols</filename>. Similarly, when giving a port number
    you can use either an integer or a service name from
    <filename>/etc/services</filename>.<note>
        <para>The rules compiler translates protocol names to protocol numbers
        and service names to port numbers itself.</para>
      </note></para>

    <para>Also, unless otherwise documented, a protocol number/name can be
    preceded by '!' to specify "All protocols except this one" (e.g.,
    "!tcp").</para>
  </section>

  <section id="ICMP">
    <title>ICMP and ICMP6 Types and Codes</title>

    <para>When dealing with ICMP, the DEST PORT specifies the type or type and
    code. You may specify the numeric type, the numeric type and code
    separated by a slash (e.g., 3/4) or you may use a type name.</para>

    <para>Type names for IPv4 and their corresponding type or type/code
    are:</para>

    <programlisting>echo-reply'                  =&gt; 0
destination-unreachable      =&gt; 3
    network-unreachable      =&gt; 3/0
    host-unreachable         =&gt; 3/1
protocol-unreachable         =&gt; 3/2
port-unreachable             =&gt; 3/3
fragmentation-needed         =&gt; 3/4
source-route-failed          =&gt; 3/5
network-unknown              =&gt; 3/6
host-unknown                 =&gt; 3/7
network-prohibited           =&gt; 3/9
host-prohibited              =&gt; 3/10
TOS-network-unreachable      =&gt; 3/11
TOS-host-unreachable         =&gt; 3/12
communication-prohibited     =&gt; 3/13
host-precedence-violation    =&gt; 3/14
precedence-cutoff            =&gt; 3/15
source-quench                =&gt; 4
redirect                     =&gt; 5
   network-redirect          =&gt; 5/0
   host-redirect             =&gt; 5/1
   TOS-network-redirect      =&gt; 5/2
   TOS-host-redirect         =&gt; 5/3
echo-request                 =&gt; 8
router-advertisement         =&gt; 9
router-solicitation          =&gt; 10
time-exceeded                =&gt; 11
   ttl-zero-during-transit   =&gt; 11/0
   ttl-zero-during-reassembly=&gt; 11/1
parameter-problem            =&gt; 12
   ip-header-bad             =&gt; 12/0
   required-option-missing   =&gt; 12/1
timestamp-request            =&gt; 13
timestamp-reply              =&gt; 14
address-mask-request         =&gt; 17
address-mask-reply           =&gt; 18</programlisting>

    <para>Type names for IPv6 and their corresponding type or type/code
    are:</para>

    <programlisting>destination-unreachable       =&gt; 1
   no-route'                  =&gt; 1/0
   communication-prohibited   =&gt; 1/1
   address-unreachable'       =&gt; 1/3
   port-unreachable'          =&gt; 1/4
packet-too-big                =&gt;  2
time-exceeded'                =&gt;  3
ttl-exceeded'                 =&gt;  3
   ttl-zero-during-transit    =&gt; 3/0
   ttl-zero-during-reassembly =&gt; 3/1
parameter-problem             =&gt;  4
   bad-header                 =&gt; 4/0
   unknown-header-type        =&gt; 4/1
   unknown-option             =&gt; 4/2
echo-request                  =&gt; 128
echo-reply                    =&gt; 129
router-solicitation           =&gt; 133
router-advertisement          =&gt; 134
neighbour-solicitation        =&gt; 135
neighbour-advertisement       =&gt; 136
redirect                      =&gt; 137</programlisting>

    <para>Shorewall 4.4 does not accept lists if ICMP (ICMP6) types prior to
    Shorewall 4.4.19.</para>
  </section>

  <section id="Ranges">
    <title>Port Ranges</title>

    <para>If you need to specify a range of ports, the proper syntax is
    &lt;low port number&gt;:&lt;high port number&gt;. For example, if you want
    to forward the range of tcp ports 4000 through 4100 to local host
    192.168.1.3, the entry in /etc/shorewall/rules is:</para>

    <programlisting>#ACTION    SOURCE     DESTINATION     PROTO     DEST PORTS(S)
DNAT       net        loc:192.168.1.3 tcp       <emphasis role="bold">4000:4100</emphasis></programlisting>

    <para>If you omit the low port number, a value of zero is assumed; if you
    omit the high port number, a value of 65535 is assumed.</para>

    <para>Also, unless otherwise documented, a port range can be preceded by
    '!' to specify "All ports except those in this range" (e.g.,
    "!4000:4100").</para>
  </section>

  <section id="Portlists">
    <title>Port Lists</title>

    <para>In most cases where a port or port range may appear, a
    comma-separated list of ports or port ranges may also be entered.
    Shorewall requires the Netfilter <emphasis
    role="bold">multiport</emphasis> match capability if ports lists are used
    (see the output of "<emphasis role="bold">shorewall show
    capabilities</emphasis>").</para>

    <para>Also, unless otherwise documented, a port list can be preceded by
    '!' to specify "All ports except these" (e.g., "!80,443").</para>

    <para>Prior to Shorewall 4.4.4, port lists appearing in the <ulink
    url="manpages/shorewall-routestopped.html">shorewall-routestopped</ulink>
    (5) file may specify no more than 15 ports; port ranges appearing in a
    list count as two ports each.</para>
  </section>

  <section id="MAC">
    <title>Using MAC Addresses</title>

    <para>Media Access Control (MAC) addresses can be used to specify packet
    source in several of the configuration files. In order to control traffic
    to/from a host by its MAC address, the host must be on the same network as
    the firewall.</para>

    <para>To use this feature, your kernel must have MAC Address Match support
    (CONFIG_IP_NF_MATCH_MAC) included.</para>

    <para>MAC addresses are 48 bits wide and each Ethernet Controller has a
    unique MAC address.</para>

    <para>In GNU/Linux, MAC addresses are usually written as a series of 6 hex
    numbers separated by colons.</para>

    <example id="mac">
      <title>MAC Address of an Ethernet Controller</title>

      <programlisting>     gateway:~ # <command>ip link ls dev eth0</command>
     4: eth0: &lt;BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 1500 qdisc htb qlen 1000
         link/ether <emphasis role="bold">02:00:08:E3:FA:55</emphasis> brd ff:ff:ff:ff:ff:ff
     gateway:~ #</programlisting>
    </example>

    <para>Because Shorewall uses colons as a separator for address fields,
    Shorewall requires MAC addresses to be written in another way. In
    Shorewall, MAC addresses begin with a tilde (<quote>~</quote>) and consist
    of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in
    the example above would be written <emphasis
    role="bold">~02-00-08-E3-FA-55</emphasis>.</para>

    <note>
      <para>It is not necessary to use the special Shorewall notation in the
      <filename><ulink
      url="MAC_Validation.html">/etc/shorewall/maclist</ulink></filename>
      file.</para>
    </note>
  </section>

  <section id="RateLimit">
    <title>Rate Limiting (Rate and Burst)</title>

    <para>Shorewall supports rate limiting in a number of ways. When
    specifying a rate limit, both a <firstterm>rate</firstterm> and a
    <firstterm>burst</firstterm> value are given.</para>

    <para>Example from <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>

    <simplelist>
      <member>LOGRATE=10/minute</member>

      <member>LOGBURST=5</member>
    </simplelist>

    <para>For each logging rule, the first time the rule is reached, the
    packet will be logged; in fact, since the burst is 5, the first five
    packets will be logged. After this, it will be 6 seconds (1 minute divided
    by the rate of 10) before a message will be logged from the rule,
    regardless of how many packets reach it. Also, every 6 seconds which
    passes, one of the bursts will be regained; if no packets hit the rule for
    30 seconds, the burst will be fully recharged; back where we
    started.</para>

    <note>
      <para>The LOGRATE and LOGBURST options are deprecated in favor of
      LOGLIMIT.</para>
    </note>

    <para>Shorewall also supports per-IP rate limiting.</para>

    <para>Another example from <ulink
    url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5):</para>

    <simplelist>
      <member>LOGLIMIT="s:5/min:5"</member>
    </simplelist>

    <para>Here, the leading "s:" indicates that logging is to be limited by
    source IP address ("d:" would indicate limiting by destination IP
    address).</para>

    <para>"s:" is followed by the rate (5 messages per minute) and the burst
    (5).</para>

    <para>The rate and limit arguments have the same meaning as in the example
    above.</para>
  </section>

  <section id="Switches">
    <title>Switches</title>

    <para>There are times when you would like to enable or disable one or more
    rules in the configuration without having to do a <command>shorewall
    restart</command>. This may be accomplished using the SWITCH column in
    <ulink url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5) or
    <ulink url="manpages6/shorewall6-rules.html">shorewall6-rules</ulink> (5).
    Using this column requires that your kernel and iptables include
    <firstterm>Condition Match Support</firstterm> and you must be running
    Shorewall 4.4.24 or later. See the output of <command>shorewall show
    capabilities</command> and <command>shorewall version</command> to
    determine if you can use this feature. As of this writing, Condition Match
    Support requires that you install xtables-addons.</para>

    <para>The SWITCH column contains the name of a
    <firstterm>switch.</firstterm> Each switch is initially in the <emphasis
    role="bold">off</emphasis> position. You can turn on the switch named
    <emphasis>switch1</emphasis> by:</para>

    <simplelist>
      <member><command>echo 1 &gt;
      /proc/net/nf_condition/switch1</command></member>
    </simplelist>

    <para>You can turn it off again by:</para>

    <simplelist>
      <member><command>echo 0 &gt;
      /proc/net/nf_condition/switch1</command></member>
    </simplelist>

    <para>If you simply include the switch name in the SWITCH column, then the
    rule is enabled only when the switch is <emphasis
    role="bold">on</emphasis>. If you precede the switch name with ! (e.g.,
    !switch1), then the rule is enabled only when the switch is <emphasis
    role="bold">off</emphasis>. Switch settings are retained over
    <command>shorewall restart</command>.</para>

    <para>Shorewall requires that switch names:</para>

    <itemizedlist>
      <listitem>
        <para>begin with a letter and be composed of letters, digits,
        underscore ('_') or hyphen ('-'); and</para>
      </listitem>

      <listitem>
        <para>be 30 characters or less in length.</para>
      </listitem>
    </itemizedlist>

    <para>Multiple rules can be controlled by the same switch.</para>

    <para>Example:</para>

    <blockquote>
      <para>Forward port 80 to dmz host $BACKUP if switch 'primary_down' is
      on.</para>

      <programlisting>#ACTION     SOURCE          DEST        PROTO       DEST         SOURCE    ORIGINAL   RATE      USER/     MARK    CONNLIMIT     TIME     HEADERS    SWITCH
#                                                   PORT(S)      PORT(S)   DEST       LIMIT     GROUP
DNAT        net             dmz:$BACKUP tcp         80           -         -          -         -         -       -             -        -          <emphasis
          role="bold">primary_down</emphasis>  </programlisting>
    </blockquote>
  </section>

  <section id="Logical">
    <title>Logical Interface Names</title>

    <para>When dealing with a complex configuration, it is often awkward to
    use physical interface names in the Shorewall configuration.</para>

    <itemizedlist>
      <listitem>
        <para>You need to remember which interface is which.</para>
      </listitem>

      <listitem>
        <para>If you move the configuration to another firewall, the interface
        names might not be the same.</para>
      </listitem>
    </itemizedlist>

    <para>Beginning with Shorewall 4.4.4, you can use logical interface names
    which are mapped to the actual interface using the
    <option>physical</option> option in <ulink
    url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink>
    (5).</para>

    <para>Here is an example:</para>

    <programlisting>#ZONE  INTERFACE  BROADCAST OPTIONS
net    <emphasis role="bold">COM_IF </emphasis>    detect    dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,<emphasis
        role="bold">physical=eth0</emphasis>
net    <emphasis role="bold">EXT_IF</emphasis>     detect    dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,<emphasis
        role="bold">physical=eth2</emphasis>
loc    <emphasis role="bold">INT_IF </emphasis>    detect    dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,<emphasis
        role="bold">physical=eth1</emphasis>
dmz    <emphasis role="bold">VPS_IF </emphasis>    detect    logmartians=1,routefilter=0,routeback,<emphasis
        role="bold">physical=venet0</emphasis>
loc    <emphasis role="bold">TUN_IF</emphasis>     detect    <emphasis
        role="bold">physical=tun+</emphasis></programlisting>

    <para>In this example, COM_IF is a logical interface name that refers to
    Ethernet interface <filename class="devicefile">eth0</filename>, EXT_IF is
    a logical interface name that refers to Ethernet interface <filename
    class="devicefile">eth2</filename>, and so on.</para>

    <para>Here are a couple of more files from the same configuration:</para>

    <para><ulink url="manpages/shorewall-masq.html">shorewall-masq</ulink>
    (5):</para>

    <programlisting>#INTERFACE SOURCE                    ADDRESS

COMMENT Masquerade Local Network
<emphasis role="bold">COM_IF</emphasis>     0.0.0.0/0
<emphasis role="bold">EXT_IF </emphasis>    !206.124.146.0/24         206.124.146.179:persistent</programlisting>

    <para><ulink
    url="manpages/shorewall-providers.html">shorewall-providers</ulink>
    (5)</para>

    <programlisting>#NAME   NUMBER   MARK    DUPLICATE  INTERFACE  GATEWAY         OPTIONS               COPY
Avvanta 1        0x10000 main       <emphasis role="bold">EXT_IF </emphasis>    206.124.146.254 loose,fallback        <emphasis
        role="bold">INT_IF,VPS_IF,TUN_IF</emphasis>
Comcast 2        0x20000 main       <emphasis role="bold">COM_IF</emphasis>     detect          balance               <emphasis
        role="bold">INT_IF,VPS_IF,TUN_IF</emphasis></programlisting>

    <para>Note in particular that Shorewall translates TUN_IF to <filename
    class="devicefile">tun*</filename> in the COPY column.</para>
  </section>

  <section>
    <title>Optional and Required Interfaces</title>

    <para>Normally, Shorewall assumes that all interfaces described in <ulink
    url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5)
    are going to be in an up and usable state when Shorewall starts or
    restarts. You can alter that assumption by specifying the <emphasis
    role="bold">optional</emphasis> option in the OPTIONS column.</para>

    <para>When an interface is marked as optional, Shorewall will determine
    the interface state at <command>start</command> and
    <command>restart</command> and adjust its configuration
    accordingly.</para>

    <itemizedlist>
      <listitem>
        <para>The <emphasis role="bold">arp_filter</emphasis>, <emphasis
        role="bold">arp_ignore</emphasis>, <emphasis
        role="bold">routefilter</emphasis>, <emphasis
        role="bold">logmartians</emphasis>, <emphasis
        role="bold">proxyarp</emphasis> and <emphasis
        role="bold">sourceroute</emphasis> options are not enforced when the
        interface is down, thus avoiding an error message such
        as:<programlisting>WARNING: Cannot set Martian logging on ppp0</programlisting></para>
      </listitem>

      <listitem>
        <para>If the interface is associated with a provider in <ulink
        url="manpages/shorewall-providers.html">shorewall-providers</ulink>
        (5), <command>start</command> and <command>restart</command> will not
        fail if the interface is not usable.</para>
      </listitem>

      <listitem>
        <para>When DETECT_DNAT_IPADDRS=Yes in <ulink
        url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5), DNAT
        rules in shorewall-rules (5) involving the interface will be omitted
        when the interface does not have an IP address.</para>
      </listitem>

      <listitem>
        <para>If <emphasis role="bold">detect</emphasis> is specified in the
        ADDRESS column of an entry in <ulink
        url="manpages/shorewall-masq.html">shorewall-masq</ulink> (5) then the
        firewall still start if the optional interface in the INTERFACE column
        does not have an IP address.</para>
      </listitem>
    </itemizedlist>

    <para>If you don't want the firewall to start unless a given interface is
    usable, then specify <emphasis role="bold">required</emphasis> in the
    OPTIONS column of <ulink
    url="manpages/shorewall-interfaces.html">shorewall-interfaces</ulink> (5).
    If you have installed and configured the Shorewall-init package, then when
    the interface becomes available, an automatic attempt will be made to
    start the firewall.</para>
  </section>

  <section id="Levels">
    <title>Shorewall Configurations</title>

    <para>Shorewall allows you to have configuration directories other than
    <filename class="directory">/etc/shorewall</filename>. The shorewall
    check, start and restart commands allow you to specify an alternate
    configuration directory and Shorewall will use the files in the alternate
    directory rather than the corresponding files in /etc/shorewall. The
    alternate directory need not contain a complete configuration; those files
    not in the alternate directory will be read from <filename
    class="directory">/etc/shorewall</filename>.<important>
        <para>Shorewall requires that the file
        <filename>/etc/shorewall/shorewall.conf</filename> to always exist.
        Certain global settings are always obtained from that file. If you
        create alternative configuration directories, do not remove
        /etc/shorewall/shorewall.conf.</para>
      </important></para>

    <para>This facility permits you to easily create a test or temporary
    configuration by</para>

    <orderedlist>
      <listitem>
        <para>copying the files that need modification from /etc/shorewall to
        a separate directory;</para>
      </listitem>

      <listitem>
        <para>modify those files in the separate directory; and</para>
      </listitem>

      <listitem>
        <para>specifying the separate directory in a <command>shorewall
        start</command> or <command>shorewall restart</command> command (e.g.,
        <command>shorewall restart /etc/testconfig</command> )</para>
      </listitem>
    </orderedlist>
  </section>

  <section id="Save">
    <title>Saved Configurations</title>

    <para>Shorewall allows you to <firstterm>save</firstterm> the
    currently-running configuration in a form that permits it to be
    re-installed quickly. When you save the configuration using the
    <command>shorewall save</command> command, the running configuration is
    saved in a file in the <filename
    class="directory">/var/lib/shorewall</filename> directory. The default
    name of that file is <filename>/var/lib/shorewall/restore</filename> but
    you can specify a different name as part of the command. For example, the
    command <command>shorewall save standard</command> will save the running
    configuration in <filename>/var/lib/shorewall/standard</filename>. A saved
    configuration is re-installed using the <command>shorewall
    restore</command> command. Again, that command normally will restore the
    configuration saved in <filename>/var/lib/shorewall/restore</filename> but
    as with the <command>save</command> command, you can specify a different
    file name in the command. For example, <command>shorewall restore
    standard</command> will re-install the configuration saved in
    <filename>/var/lib/shorewall/standard</filename>. By permitting you to
    save different configurations under different names, Shorewall provides a
    means for quickly switching between these different saved
    configurations.</para>

    <para>As mentioned above, the default configuration is called 'restore'
    but like most things in Shorewall, that default can be changed. The
    default name is specified using the <emphasis
    role="bold">RESTOREFILE</emphasis> option in
    <filename>/etc/shorewall/shorewall.conf</filename>.</para>

    <warning>
      <para>The default saved configuration is used by Shorewall in a number
      of ways besides in the <command>restore</command> command; to avoid
      surprises, I recommend that you read the <ulink
      url="starting_and_stopping_shorewall.htm#Saved">Shorewall Operations
      documentation section about saved configurations</ulink> before creating
      one.</para>
    </warning>
  </section>
</article>