shorewall_code/Shorewall-docs2/configuration_file_basics.xml

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

  <articleinfo>
    <title>Configuration Files</title>

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

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

    <pubdate>2004-10-22</pubdate>

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

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

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

  <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 several 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> (Shorewall
          1.3.4 and later) - 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 IPSEC,
          GRE and IPIP tunnels 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> - define
          your own actions for rules in /etc/shorewall/rules (shorewall 1.4.9
          and later).</para>
        </listitem>

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

        <listitem>
          <para><filename>/usr/share/shorewall/actions.*</filename> - Details
          of actions 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>

        <listitem>
          <para><filename>/usr/share/bogons</filename> — Defines the behavior
          of the 'nobogons' 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>
    <title>Special Note about /etc/shorewall/shorewall.conf</title>

    <para>It is a good idea to modify your /etc/shorewall/shorewall.conf file,
    even if you just add a comment that says "I modified this file". That way,
    your package manager won't overwrite the file with future updated
    versions. Such overwrites can cause unwanted changes in the behavior of
    Shorewall.</para>
  </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>
      <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="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.</para>

    <example>
      <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>Beginning with Shorewall version 1.4.2, any 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 assumed to reside in /etc/shorewall or in an
    alternate configuration directory if one has been specified for the
    command.</para>

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

    <example>
      <title>Use of INCLUDE</title>

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

    <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 much be fully qualified and include a minumum of two
    periods (although one may be trailing). This restriction is imposed by
    Shorewall to insure backward compatibility with existing configuration
    files.</para>

    <example>
      <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>
      <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="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="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,&nbsp;&nbsp;&nbsp;&nbsp; dhcp,&nbsp;&nbsp;&nbsp;&nbsp; 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>
    <title>IP Address Ranges</title>

    <para>Beginning with Shorewall 2.2.0, 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 check</command> command:</para>

    <programlisting>&gt;~ <command>shorewall check</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>Port Numbers/Service Names</title>

    <para>Unless otherwise specified, when giving a port number you can use
    either an integer or a service name from /etc/services.</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="Variables">
    <title>Using Shell Variables</title>

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

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

    <example>
      <title>Using Shell Variables</title>

      <programlisting>&nbsp;&nbsp;&nbsp; /etc/shorewall/params
 
        NET_IF=eth0
        NET_BCAST=130.252.100.255
        NET_OPTIONS=routefilter,norfc1918
 
&nbsp;&nbsp;&nbsp; /etc/shorewall/interfaces record:

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

      <para>Variables may be used anywhere in the other configuration
      files.</para>
    </example>
  </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>
      <title>MAC Address of an Ethernet Controller</title>

      <programlisting> &nbsp;&nbsp;&nbsp;&nbsp; [root@gateway root]# <command>ifconfig eth0</command>
 &nbsp;&nbsp;&nbsp;&nbsp; eth0 Link encap:Ethernet HWaddr <emphasis
          role="bold">02:00:08:E3:FA:55</emphasis>
 &nbsp;&nbsp;&nbsp;&nbsp; inet addr:206.124.146.176 Bcast:206.124.146.255 Mask:255.255.255.0
 &nbsp;&nbsp;&nbsp;&nbsp; UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
 &nbsp;&nbsp;&nbsp;&nbsp; RX packets:2398102 errors:0 dropped:0 overruns:0 frame:0
 &nbsp;&nbsp;&nbsp;&nbsp; TX packets:3044698 errors:0 dropped:0 overruns:0 carrier:0
 &nbsp;&nbsp;&nbsp;&nbsp; collisions:30394 txqueuelen:100
 &nbsp;&nbsp;&nbsp;&nbsp; RX bytes:419871805 (400.4 Mb) TX bytes:1659782221 (1582.8 Mb)
 &nbsp;&nbsp;&nbsp;&nbsp; Interrupt:11 Base address:0x1800
</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>.</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 shorewall start or
        shorewall restart command (e.g., <command>shorewall -c /etc/testconfig
        restart</command> )</para>
      </listitem>
    </orderedlist>

    <para>The <ulink url="starting_and_stopping_shorewall.htm">try
    command</ulink> allows you to attempt to restart using an alternate
    configuration and if an error occurs to automatically restart the standard
    configuration.</para>
  </section>
</article>