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

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

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

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

    <copyright>
      <year>2001-2008</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 3.0 and
    later. If you are running a version of Shorewall earlier than Shorewall
    3.0.0 then please see the documentation for that
    release.</emphasis></para>
  </caution>

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

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

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

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

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

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

        <listitem>
          <para><filename>/etc/shorewall/modules</filename> - directs the
          firewall to load kernel modules.</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>- defines marking
          of packets for later use by traffic control/shaping or policy
          routing.</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> - lists
          blacklisted IP/subnet/MAC addresses.</para>
        </listitem>

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

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

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

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

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

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

        <listitem>
          <para><filename>/etc/shorewall/actions</filename> and
          <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/route_rules</filename> (Added in
          Shorewall 3.2.0) - 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> (tcfilters added in
          Shorewall 4.2.0) - Define traffic shaping.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/tcrules</filename> - Mark or classify
          traffic for traffic shaping or multiple providers.</para>
        </listitem>

        <listitem>
          <para><filename>/etc/shorewall/vardir</filename> - (Added in
          Shorewall 4.0.0-RC2) - 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/rfc1918</filename> — Defines the behavior
          of the 'norfc1918' interface option in
          <filename>/etc/shorewall/interfaces</filename>. <emphasis
          role="bold">If you need to change this file, copy it to
          <filename>/etc/shorewall</filename> and modify the
          copy</emphasis>.</para>
        </listitem>
      </itemizedlist></para>
  </section>

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

    <para>Beginning with Shorewall version 3.4, 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>
  </section>

  <section id="COMMENT">
    <title>Attach Comment to Netfilter Rules</title>

    <para>Beginning with Shorewall version 3.3.3, if you kernel and iptables
    contain comment match support (see the output of <command>shorewall show
    capabilities</command>), then you can attach comments to Netfilter rules.
    This feature is available in the following files:</para>

    <itemizedlist>
      <listitem>
        <para><filename>/etc/shorewall/masq</filename></para>
      </listitem>

      <listitem>
        <para><filename>/etc/shorewall/nat</filename></para>
      </listitem>

      <listitem>
        <para><filename>/etc/shorewall/rules</filename></para>
      </listitem>

      <listitem>
        <para><filename>/etc/shorewall/tcrules</filename></para>
      </listitem>

      <listitem>
        <para>Action definition files
        (<filename>/etc/shorewall/action.*</filename>)</para>
      </listitem>

      <listitem>
        <para>Macro definition files (/etc/shorewall/macro.*) — Added in
        Shorewall-perl 4.2.0. They are ignored by Shorewall-shell 4.1 and
        later.</para>
      </listitem>
    </itemizedlist>

    <para>To attach a comment to one or more rules, insert a record above the
    rules that begins with the word COMMENT (must be in all caps). The
    remainder of the line is treated as a comment -- that comment will appear
    delimited by "/* ... */" in the output of the <command>shorewall[-lite]
    show</command> and <command>shorewall[-lite] dump</command> commands. The
    comment will be attached to each generated rule until another COMMENT line
    appears. To stop attaching comments to rules, simply insert a line that
    contains the single word COMMENT.</para>

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

    <programlisting>COMMENT Stop NETBIOS noise

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

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

DROP            loc:!192.168.0.0/22             net

COMMENT</programlisting>

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

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

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

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

</programlisting>

    <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/ALLOW    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="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>
    </example>
  </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>

    <caution>
      <para>If you are using <ulink
      url="CompiledPrograms.html%23Lite">Shorewall Lite</ulink> and are
      running a version of Shorewall earlier than 3.2.9, it is not advisable
      to use INCLUDE in the <filename>params</filename> file in an export
      directory. 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>Beginning with Shorewall version 3.2.9 (3.4.0 RC2), 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.</para>
    </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>Users of Shorewall-perl 4.0.6 and later 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>
    </example>
  </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 some of the other
    configuration files.</para>

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

    <para>Example:</para>

    <blockquote>
      <programlisting>    /etc/shorewall/params
 
        NET_IF=eth0
        NET_BCAST=130.252.100.255
        NET_OPTIONS=routefilter,norfc1918
 
    /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,norfc1918
 </programlisting>
    </blockquote>

    <para>Variables may be used anywhere in the other configuration
    files.<note>
        <para>Shorewall-perl users: 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 (the params
        file is sourced by both /sbin/shorewall and
        /usr/lib/shorewall/firewall).</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. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, 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.</para>
      </listitem>

      <listitem>
        <para>If you are using <ulink
        url="CompiledPrograms.html#Lite">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
        to call interactively any Shorewall function that you can call in an
        extension script.</para>
      </listitem>
    </orderedlist>

    <para>When expanding a variable, the acceptable forms of expansion depend
    on whether you are using Shorewall-shell or Shorewall-perl.</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall-shell and all Shorewall versions prior to 4.0 can use
        any form of expansion supported by the shell ($VAR, ${VAR},
        ${VAR:=val}, ...).</para>
      </listitem>

      <listitem>
        <para>Shorewall-perl only supports the $VAR and ${VAR} forms.</para>
      </listitem>
    </itemizedlist>
  </section>

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

    <para>This feature was added in Shorewall-perl 4.0.6. To use it, you must
    be running 4.0.6 or later and must be using Shorewall-perl
    (SHOREWALL_COMPILER=perl in shorewall.conf).</para>

    <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 Shorewall-perl,
    <firstterm>Embedded scripts</firstterm> offer a richer and more flexible
    extension capability.</para>

    <para>While inline scripts scripts may be written in either Shell or Perl,
    those written in Perl have a lot more power.</para>

    <para>Embedded scripts can be either single-line or multi-line. Single
    line scripts take one of the following forms:</para>

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

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

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

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

    <para>Perl scripts run in the context of of the compiler process. 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() function. The Perl equivalent of the above SHELL script would
    be:<programlisting>PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</programlisting>Perl
    scripts are implicitly prefixed by the following:</para>

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

    <para>As part of the change that added embedded scripts:</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 was
        added for use by Shorewall-perl. 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>A <ulink url="ManualChains.html">Manual Chain</ulink> facility
        was added.</para>
      </listitem>
    </orderedlist>

    <para>Multi-line scripts use one of the following forms:<programlisting><emphasis
          role="bold">BEGIN SHELL</emphasis>
&lt;<emphasis>shell script</emphasis>&gt;
<emphasis role="bold">END</emphasis> [ <emphasis role="bold">SHELL</emphasis> ]</programlisting><programlisting><emphasis
          role="bold">BEGIN PERL</emphasis> [;]
&lt;<emphasis>perl script</emphasis>&gt;
<emphasis role="bold">END</emphasis> [ <emphasis role="bold">PERL</emphasis> ] [<emphasis
          role="bold">;</emphasis>]</programlisting></para>

    <para><emphasis role="bold">Note: </emphasis>The '[' and ']' above are
    meta-characters which indicate that what they enclose is optional and may
    be omitted. So you may follow PERL with a semicolon ( ':') or you may omit
    the semicolon.</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,norfc1918
     Invalid: routefilter,     dhcp,     norfc1818</programlisting></para>
      </listitem>

      <listitem>
        <para>If you use line continuation to break a comma-separated list,
        the continuation line(s) must begin in column 1 (or there would be
        embedded 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 or Subnet</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>
  </section>

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

    <para>Shorewall 3.0 differs from earlier versions in that in most contexts
    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>Shorewall-perl translates protocol names to protocol numbers and
        service names to port numbers itself.</para>

        <para>In Shorewall versions 4.0.0 - 4.0.4, the mapping that it uses is
        contained in the Perl module
        <filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename>.
        That module is built when Shorewall is installed or upgraded using the
        current <filename>/etc/protocols</filename> and
        <filename>/etc/services</filename> files as input (if the build
        program fails, a fallback version of the module is installed).</para>

        <para>To generate a new Ports.pm module:<programlisting>cp /usr/share/shorewall-perl/Shorewall/Ports.pm /usr/share/shorewall-perl/Shorewall/Ports.pm.backup
/usr/share/shorewall/buildports.pm &gt; /usr/share/shorewall-perl/Shorewall/Ports.pm</programlisting></para>

        <para>Beginning with Shorewall version 4.0.5, the
        <filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename> has
        been eliminated and the Shorewall-perl compiler uses Perl's interfaces
        to getprotobyname(3posix) and getservbyname(3posix).</para>
      </note></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       4000:4100</programlisting>

    <para>If you omit the low port number, a value of zero is assumed; if you
    omit the high port number, a value of 65535 is assumed.</para>
  </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 will use the Netfilter <emphasis
    role="bold">multiport</emphasis> match capability if it is available (see
    the output of "<emphasis role="bold">shorewall show
    capabilities</emphasis>") and if its use is appropriate.</para>

    <para>Shorewall can use multiport match if:</para>

    <orderedlist>
      <listitem>
        <para>The list contains 15 or fewer port number; and</para>
      </listitem>

      <listitem>
        <para>There are no port ranges listed OR your iptables/kernel support
        the Extended <emphasis role="bold">multiport</emphasis> match (again
        see the output of "<command>shorewall show capabilities</command>").
        Where the Extended <emphasis role="bold">multiport</emphasis> match is
        available, each port range counts as two ports toward the maximum of
        15.</para>
      </listitem>
    </orderedlist>

    <note>
      <para>Shorewall-perl requires <emphasis role="bold">multiport</emphasis>
      match in order to accept port lists in Shorewall configuration files. It
      further requires Extended <emphasis role="bold">multiport</emphasis>
      match in order to accept port ranges in port lists. Shorewall-perl will
      never break a list longer than 15 ports (with each range counting as two
      ports) into smaller lists. So you must be sure that your port lists can
      be handled directly by the Netfilter/iptables capabilities
      available.</para>
    </note>
  </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="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>