shorewall_code/docs/upgrade_issues.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">
<!-- $Id$ -->
<article id="upgrade_issues">
  <articleinfo>
    <title>Upgrade Issues</title>

    <author>
      <firstname>Tom</firstname>

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

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

    <copyright>
      <year>2002</year>

      <year>2003</year>

      <year>2004</year>

      <year>2005</year>

      <year>2006</year>

      <year>2007</year>

      <holder>Thomas M. Eastep</holder>

      <holder></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 type="" url="copyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <section>
    <title>Important</title>

    <para>It is important that you read all of the sections on this page where
    the version number mentioned in the section title is later than what you
    are currently running.</para>

    <para>In the descriptions that follows, the term
    <emphasis>group</emphasis> refers to a particular network or subnetwork
    (which may be <literal>0.0.0.0/0</literal> or it may be a host address)
    accessed through a particular interface.</para>

    <para>Examples:</para>

    <simplelist columns="1" type="vert">
      <member><literal>eth0:0.0.0.0/0</literal></member>

      <member><literal>eth2:192.168.1.0/24</literal></member>

      <member><literal>eth3:192.0.2.123</literal></member>
    </simplelist>

    <para>You can use the <command moreinfo="none">shorewall check</command>
    command to see the groups associated with each of your zones.</para>
  </section>

  <section>
    <title>Versions &gt;= 4.0.0-Beta1</title>

    <orderedlist>
      <listitem>
        <para> This is the first Shorewall release that fully integrates the
        new Shorewall-perl compiler. You are now offered a choice as to which
        compiler(s) you install. In Shorewall 4.0.0, there are the following
        packages:<itemizedlist>
            <listitem>
              <para>Shorewall ( common files )</para>
            </listitem>

            <listitem>
              <para>Shorewall-shell ( the shell-based compiler )</para>
            </listitem>

            <listitem>
              <para>Shorewall-perl (the Perl-based compiler )</para>
            </listitem>

            <listitem>
              <para>Shorewall-lite</para>
            </listitem>
          </itemizedlist>You must install Shorewall and at least one of the
        compiler packages (you may install them both).</para>

        <para>You cannot simply upgrade your existing Shorewall package. You
        must upgrade Shorewall <emphasis role="bold">and</emphasis> install
        one or both of the compilers.</para>

        <para>If you attempt to upgrade using the RPM, you get this
        result:<programlisting>gateway:~ # rpm -Uvh shorewall-4.0.0.noarch.rpm 
error: Failed dependencies:
shorewall_compiler is needed by shorewall-4.0.0-1.noarch
gateway:~ #</programlisting> You must either:<programlisting>rpm -U shorewall-4.0.0.noarch.rpm shorewall-shell-4.0.0.noarch.rpm</programlisting>or<programlisting>rpm -U shorewall-4.0.0.noarch.rpm shorewall-perl-4.0.0.noarch.rpm</programlisting>or<programlisting>rpm -i shorewall-shell-4.0.0.noarch.rpm
rpm -U shorewall-4.0.0.noarch.rpm</programlisting>or<programlisting>rpm -i shorewall-perl-4.0.0.noarch.rpm
rpm -U shorewall-4.0.0.noarch.rpm</programlisting>If you are upgrading using
        the tarball, you must install either shorewall-shell or shorewall-perl
        before you upgrade Shorewall. Otherwise, the install.sh script fails
        with:<simplelist>
            <member>ERROR: No Shorewall compiler is installed</member>
          </simplelist>The shorewall-shell and shorewall-perl packages are
        installed from the tarball in the expected way; untar the package, and
        run the install.sh script.</para>
      </listitem>

      <listitem>
        <para>The ROUTE_FILTER and LOG_MARTIANS options in shorewall.conf work
        slightly differently in Shorewall 4.0.0. In prior releases, leaving
        these options empty was equivalent to setting them to 'No' which
        caused the corresponding flag in /proc to be reset for all interfaces.
        Beginning in Shorewall 4.0.0, leaving these options empty causes
        Shorewall to leave the flags in /proc as they are. You must set the
        option to 'No' in order to obtain the old behavior. </para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Versions &gt;= 3.4.0-Beta1</title>

    <orderedlist>
      <listitem>
        <para>Shorewall supports the notion of "default actions". A default
        action defines a set of rules that are applied before a policy is
        enforced. Default actions accomplish two goals:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para>Relieve log congestion. Default actions typically include
            rules to silently drop or reject traffic that would otherwise be
            logged when the policy is enforced.</para>
          </listitem>

          <listitem>
            <para>Insure correct operation. Default actions can also avoid
            common pitfalls like dropping connection requests on TCP port 113.
            If these connections are dropped (rather than rejected) then you
            may encounter problems connecting to internet services that
            utilize the AUTH protocol of client authentication.</para>
          </listitem>
        </orderedlist>

        <para>In prior Shorewall versions, default actions (action.Drop and
        action.Reject) were defined for DROP and REJECT policies in
        <filename>/usr/share/shorewall/actions.std</filename>. These could be
        overridden in <filename>/etc/shorewall/actions</filename>.</para>

        <para>This approach has two drawbacks:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para>All DROP policies must use the same default action and all
            REJECT policies must use the same default action.</para>
          </listitem>

          <listitem>
            <para>Now that we have <ulink
            url="Modularization.html">modularized action processing</ulink>,
            we need a way to define default rules for a policy that does not
            involve actions.</para>
          </listitem>
        </orderedlist>

        <para>If you have not overridden the defaults using entries in
        <filename>/etc/shorewall/actions</filename> then you need make no
        changes to migrate to Shorewall version 3.4. If you have overridden
        either of these entries, then please read on.</para>

        <para>The change in version 3.4 is two-fold:</para>

        <itemizedlist>
          <listitem>
            <para>Four new options have been added to the
            <filename>/etc/shorewall/shorewall.conf</filename> file that allow
            specifying the default action for DROP, REJECT, ACCEPT and
            QUEUE.</para>

            <para>The options are DROP_DEFAULT, REJECT_DEFAULT, ACCEPT_DEFAULT
            and QUEUE_DEFAULT.</para>

            <para>DROP_DEFAULT describes the rules to be applied before a
            connection request is dropped by a DROP policy; REJECT_DEFAULT
            describes the rules to be applied if a connection request is
            rejected by a REJECT policy. The other two are similar for ACCEPT
            and QUEUE policies. The value assigned to these may be:</para>

            <orderedlist numeration="loweralpha">
              <listitem>
                <para>The name of an action.</para>
              </listitem>

              <listitem>
                <para>The name of a macro.</para>
              </listitem>

              <listitem>
                <para>'None' or 'none'</para>
              </listitem>
            </orderedlist>

            <para>The default values are:</para>

            <simplelist>
              <member>DROP_DEFAULT="Drop"</member>

              <member>REJECT_DEFAULT="Reject"</member>

              <member>ACCEPT_DEFAULT=none</member>

              <member>QUEUE_DEFAULT=none</member>
            </simplelist>

            <para>If USE_ACTIONS=Yes, then these values refer to action.Drop
            and action.Reject respectively. If USE_ACTIONS=No, then these
            values refer to macro.Drop and macro.Reject.</para>

            <para>If you set the value of either option to "None" then no
            default action will be used and the default action or macro (if
            any) must be specified in
            <filename>/etc/shorewall/policy</filename>.</para>
          </listitem>

          <listitem>
            <para>The POLICY column in /etc/shorewall/policy has been
            extended.</para>

            <para>In <filename>/etc/shorewall/policy</filename>, when the
            POLICY is DROP, REJECT, ACCEPT or QUEUE then the policy may be
            followed by ":" and one of the following:</para>

            <orderedlist numeration="loweralpha">
              <listitem>
                <para>The word "None" or "none". This causes any default
                action defined in
                <filename>/etc/shorewall/shorewall.conf</filename> to be
                omitted for this policy.</para>
              </listitem>

              <listitem>
                <para>The name of an action (requires that USE_ACTIONS=Yes in
                <filename>shorewall.conf</filename>). That action will be
                invoked before the policy is enforced.</para>
              </listitem>

              <listitem>
                <para>The name of a macro. The rules in that macro will be
                applied before the policy is enforced. This does not require
                USE_ACTIONS=Yes.</para>
              </listitem>
            </orderedlist>
          </listitem>
        </itemizedlist>

        <para>Example:</para>

        <programlisting>#SOURCE         DEST            POLICY          LOG
#                                               LEVEL
loc             net             ACCEPT
net             all             DROP:MyDrop     info
#
# THE FOLLOWING POLICY MUST BE LAST
#
all             all             REJECT:MyReject info</programlisting>
      </listitem>

      <listitem>
        <para>The 'Limit' action is now a builtin. If you have 'Limit' listed
        in <filename>/etc/shorewall/actions</filename>, remove the entry. Also
        remove the files <filename>/etc/shorewall/action.Limit</filename>
        and/or <filename>/etc/shorewall/Limit</filename> if you have
        them.</para>
      </listitem>

      <listitem>
        <para>This issue only applies if you have entries in
        <filename>/etc/shorewall/providers</filename>.</para>

        <para>Previously, Shorewall has not attempted to undo the changes it
        has made to the firewall's routing as a result of entries in
        <filename>/etc/shorewall/providers</filename> and
        <filename>/etc/shorewall/routes</filename>. Beginning with this
        release, Shorewall will attempt to undo these changes. This change can
        present a migration issue in that the initial routing configuration
        when this version of Shorewall is installed has probably been changed
        by Shorewall already. Hence, when Shorewall restores the original
        configuration, it will be installing a configuration that the
        previously-installed version has already modified.</para>

        <para>The steps to correcting this after you have installed version
        3.4 or later of Shorewall are as follows:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para><command>shorewall[-lite] stop</command></para>
          </listitem>

          <listitem>
            <para>Remove the files
            <filename>/var/lib/shorewall[-lite]/default_route</filename> and
            <filename>/var/lib/shorewall[-lite]/undo_routing</filename> if
            they exist.</para>
          </listitem>

          <listitem>
            <para>Either restart networking or reboot.</para>
          </listitem>

          <listitem>
            <para><command>shorewall[-lite] start</command></para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>This issue only applies if you run Shorewall Lite.</para>

        <para>The <filename>/etc/shorewall-lite/shorewall.conf</filename> file
        has been renamed
        <filename>/etc/shorewall-lite/shorewall-lite.conf</filename>. When you
        upgrade, your <filename>shorewall.conf</filename> file will be renamed
        <filename>shorewall-lite.conf</filename>.</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Version &gt;= 3.2.0</title>

    <orderedlist>
      <listitem>
        <para>If you are upgrading from version 2.4 or earlier, please read
        the 3.0.0 upgrade considerations below.</para>
      </listitem>

      <listitem>
        <para>A number of macros have been split into two. The macros affected
        are:</para>

        <simplelist>
          <member>IMAP</member>

          <member>LDAP</member>

          <member>NNTP</member>

          <member>POP3</member>

          <member>SMTP</member>
        </simplelist>

        <para>Each of these macros now handles only traffic on the native
        (plaintext) port. There is a corresponding macro with S added to the
        end of the name for the SSL version of the same protocol. Thus each
        macro results in the insertion of only one port per invocation. The
        Web macro has not been split, but two new macros, HTTP and HTTPS have
        been created. The Web macro is deprecated in favour of these new
        macros, and may be removed from future Shorewall releases.</para>

        <para>These changes have been made to ensure no unexpected ports are
        opened due to the use of macros.</para>
      </listitem>

      <listitem>
        <para>In previous Shorewall releases, DNAT and REDIRECT rules
        supported a special syntax for exclusion of a subnet from the effect
        of the rule.</para>

        <para>Example:</para>

        <blockquote>
          <para>Z2 is a subzone of Z1:</para>

          <programlisting>DNAT     Z1!Z2        loc:192.168.1.4        ...</programlisting>
        </blockquote>

        <para>That feature has never worked correctly when Z2 is a dynamic
        zone. Furthermore, now that Shorewall supports exclusion lists, the
        capability is redundant since the above rule can now be written in the
        form:</para>

        <programlisting>DNAT     Z1:!&lt;list of exclusions&gt;   loc:192.168.1.4   ...</programlisting>

        <para>Beginning with Shorewall 3.2.0, the special exclusion syntax
        will no longer be supported.</para>
      </listitem>

      <listitem>
        <para>Important if you use the QUEUE target.</para>

        <para>In the /etc/shorewall/rules file and in actions, you may now
        specify 'tcp:syn' in the PROTO column. 'tcp:syn' is equivalent to
        'tcp' but also requires that the SYN flag is set and the RST, FIN and
        ACK flags be off ("--syn" is added to the iptables rule).</para>

        <para>As part of this change, Shorewall no longer adds the "--syn"
        option to TCP rules that specify QUEUE as their target.</para>
      </listitem>

      <listitem>
        <para>Extension Scripts may require change</para>

        <para>In previous releases, extension scripts were executed during
        <command>[re]start</command> by using the Bourne Shell "." operator.
        In addition to executing commands during <command>[re]start</command>,
        these scripts had to "save" the commands to be executed during
        <command>shorewall restore</command>.</para>

        <para>This clumsiness has been eliminated in Shorewall 3.2. In
        Shorewall 3.2, extension scripts are copied in-line into the compiled
        program and are executed in-line during <command>start</command>,
        <command>restart</command> and <command>restore</command>. This
        applies to all extension scripts except those associated with a chain
        or action -- those extension scripts continue to be processed at
        compile time.</para>

        <para>This new approach has two implications for existing
        scripts.</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para>It is no longer necessary to save the commands; so functions
            like 'save_command', 'run_and_save_command' and
            'ensure_and_save_command' need no longer be called. The generated
            program will contain functions with these names:</para>

            <simplelist>
              <member>save_command() - does nothing</member>

              <member>run_and_save_command() - runs the passed
              command</member>

              <member>ensure_and_save_command() - runs the passed command and
              stops the firewall if the command fails.</member>
            </simplelist>

            <para>These functions should provide for transparent migration of
            scripts that use them until you can get around to eliminating
            their use completely.</para>
          </listitem>

          <listitem>
            <para>When the extension script is copied into the compiled
            program, it is indented to line up with the surrounding code. If
            you have 'awk' installed on your system, the Shorewall compiler
            will correctly handle line continuation (last character on the
            line = "\"). If you do not have awk, it will not be possible to
            use line-continuation in your extension scripts. In no case is it
            possible to continue a quoted string over multiple lines without
            having additional whitespace inserted into the string.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Beginning with this release, the way in which packet marking in
        the PREROUTING chain interracts with the 'track' option in
        /etc/shorewall/providers has changed in two ways:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para>Packets arriving on a tracked interface are now passed to
            the PREROUTING marking chain so that they may be marked with a
            mark other than the 'track' mark (the connection still retains the
            'track' mark).</para>
          </listitem>

          <listitem>
            <para>When HIGH_ROUTE_MARKS=Yes, you can still clear the mark on
            packets in the PREROUTING chain (i.e., you can specify a mark
            value of zero).</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Kernel version 2.6.16 introduces 'xtables', a new common packet
        filtering and connection tracking facility that supports both IPv4 and
        IPv6. Because a different set of kernel modules must be loaded for
        xtables, Shorewall now includes two 'modules' files:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para><filename>/usr/share/shorewall/modules</filename> -- the
            former <filename>/etc/shorewall/modules</filename></para>
          </listitem>

          <listitem>
            <para>/usr/share/shorewall/xmodules -- a new file that support
            xtables.</para>
          </listitem>
        </orderedlist>

        <para>If you wish to use the new file, then simply execute this
        command:</para>

        <para><command>cp -f /usr/share/shorewall/xmodules
        /etc/shorewall/modules</command></para>
      </listitem>

      <listitem>
        <para>(<emphasis role="bold">Versions &gt;= 3.2.3</emphasis>)
        Previously, CLASSIFY tcrules were always processed out of the
        POSTROUTING chain. Beginning with this release, they are processed out
        of the POSTROUTING chain *except* when the SOURCE is
        $FW[:&lt;address&gt;] in which case the rule is processed out of the
        OUTPUT chain.</para>

        <para>With correctly-coded rulesets, this change should have no
        effect. Users having incorrectly-coded tcrules may need to change
        them.</para>

        <para>Example:</para>

        <blockquote>
          <programlisting>#MARK/          SOURCE  DEST    PROTO   DEST            SOURCE
#CLASSIFY                               PORTS(S)        PORT(S)
1:110           $FW     eth3    tcp     -               22</programlisting>
        </blockquote>

        <para>While the user may have expected this rule to only affect
        traffic from the firewall itself, the rule was really equivalent to
        this one:</para>

        <blockquote>
          <programlisting>#MARK/    SOURCE        DEST    PROTO   DEST            SOURCE
#CLASSIFY                               PORTS(S)        PORT(S)
1:110     0.0.0.0/0     eth3    tcp     -               22</programlisting>
        </blockquote>

        <para>So after this change, the second rule will be required rather
        than the first if that is what was really wanted.</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Version &gt;= 3.0.0</title>

    <orderedlist>
      <listitem>
        <para>The "monitor" command has been eliminated.</para>
      </listitem>

      <listitem>
        <para>The "DISPLAY" and "COMMENTS" columns in the /etc/shorewall/zones
        file have been removed and have been replaced by the former columns of
        the /etc/shorewall/ipsec file. The latter file has been
        removed.</para>

        <para>Additionally the FW option in shorewall.conf has been deprecated
        and is no longer set to 'fw' by default. New users are expected to
        define the firewall zone in /etc/shorewall/zones.</para>

        <para>Adhering to the principle of least astonishment, the old
        <filename>/etc/shorewall/ipsec</filename> file will continue to be
        supported. A new IPSECFILE variable in /etc/shorewall/shorewall.conf
        determines the name of the file that Shorewall looks in for IPSEC
        information. If that variable is not set or is set to the empty value
        then IPSECFILE=ipsec is assumed. So if you simply upgrade and don't do
        something idiotic like replace your current shorewall.conf file with
        the new one, your old configuration will continue to work. A dummy
        'ipsec' file is included in the release so that your package manager
        (e.g., rpm) won't remove your existing file.</para>

        <para>The shorewall.conf file included in this release sets
        IPSECFILE=zones so that new users are expected to use the <ulink
        url="Documentation.htm#Zones">new zone file format</ulink>.</para>
      </listitem>

      <listitem>
        <para>The DROPINVALID option has been removed from shorewall.conf. The
        behavior will be as if DROPINVALID=No had been specified. If you wish
        to drop invalid state packets, use the dropInvalid built-in
        action.</para>
      </listitem>

      <listitem>
        <para>The 'nobogons' interface and hosts option as well as the
        BOGON_LOG_LEVEL option have been eliminated.</para>
      </listitem>

      <listitem>
        <para>Most of the standard actions have been replaced by parameterized
        macros (see below). So for example, the action.AllowSMTP and
        action.DropSMTP have been removed an a parameterized macro macro.SMTP
        has been added to replace them.</para>

        <para>In order that current users don't have to immediately update
        their rules and user-defined actions, Shorewall can substitute an
        invocation of the a new macro for an existing invocation of one of the
        old actions. So if your rules file calls AllowSMTP, Shorewall will
        replace that call with SMTP/ACCEPT. Because this substitution is
        expensive, it is conditional based on the setting of MAPOLDACTIONS in
        shorewall.conf. If this option is set to YES or if it is not set (such
        as if you are using your old shorewall.conf file) then Shorewall will
        perform the substitution. Once you have converted to use the new
        macros, you can set MAPOLDACTIONS=No and invocations of those actions
        will go much quicker during 'shorewall [re]start'.</para>
      </listitem>

      <listitem>
        <para>The STATEDIR variable in /etc/shorewall/shorewall.conf has been
        removed. STATEDIR is now fixed at /var/lib/shorewall. If you have
        previously set STATEDIR to another directory, please copy the files
        from that directory to /var/lib/shorewall/ before [re]starting
        Shorewall after the upgrade to this version.</para>
      </listitem>

      <listitem>
        <para>The "shorewall status" command now just gives the status of
        Shorewall (started or not-started). The previous status command has
        been renamed "dump". The command also shows the state relative to the
        state diagram at <ulink
        url="http://shorewall.net/starting_and_stopping_shorewall.htm">http://shorewall.net/starting_and_stopping_shorewall.htm</ulink>.
        In addition to the state, the time and date at which that state was
        entered is shown.</para>

        <para>Note that at least one "shorewall [re]start" must be issued
        after upgrading to this release before "shorewall status" will show
        anything but "Unknown" for the state.</para>
      </listitem>

      <listitem>
        <para>The "shorewall forget" command now removes the dynamic blacklist
        save file (/var/lib/shorewall/save).</para>
      </listitem>

      <listitem>
        <para>In previous versions of Shorewall, the rules generated by
        entries in <filename>/etc/shorewall/tunnels</filename> preceded those
        rules generated by entries in
        <filename>/etc/shorewall/rules</filename>. Beginning with this
        release, the rules generated by entries in the tunnels file will
        appear *AFTER* the rules generated by the rules file. This may cause
        you problems if you have REJECT, DENY or CONTINUE rules in your rules
        file that would cause the tunnel transport packets to not reach the
        rules that ACCEPT them. See <ulink
        url="http://www.shorewall.net/VPNBasics.html">http://www.shorewall.net/VPNBasics.html</ulink>
        for information on the rules generated by entries in the tunnels
        file.</para>
      </listitem>

      <listitem>
        <para>The NEWNOTSYN and LOGNEWNOTSYN options in shorewall.conf have
        been removed as have the 'newnotsyn' options in
        <filename>/etc/shorewall/interfaces</filename> and
        <filename>/etc/shorewall/hosts</filename>.</para>

        <para>TCP new-not-syn packets may be blocked using the 'dropNotSyn' or
        'rejNotSyn' built-in actions.</para>

        <para>Example: Reject all new-not-syn packets from the net and log
        them at the 'info' level.</para>

        <programlisting>#ACTION          SOURCE           DEST           PROTO
SECTION NEW
rejNotSyn:info   net              all            tcp</programlisting>

        <para>Note that the rule is added at the front of the NEW section of
        the rules file.</para>
      </listitem>

      <listitem>
        <para>A new TC_SCRIPT option replaces TC_ENABLED in shorewall.conf. If
        the option is not set then the internal shaper (tc4shorewall by Arne
        Bernin) is used. Otherwise, the script named in the variable is
        used.</para>

        <para>Users who currently use an
        <filename>/etc/shorewall/tcstart</filename> file and wish to continue
        to do so should set TC_SCRIPT=/etc/shorewall/tcstart in
        shorewall.conf.</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Version &gt;= 2.4.0</title>

    <orderedlist>
      <listitem>
        <para>Shorewall now enforces the restriction that mark values used in
        <filename> /etc/shorewall/tcrules</filename> are less than 256. If you
        are using mark values &gt;= 256, you must change your configuration
        before you upgrade.</para>
      </listitem>

      <listitem>
        <para>The value "ipp2p" is no longer accepted in the PROTO column of
        the <filename>/etc/shorewall/rules</filename> file. This support has
        never worked as intended and cannot be made to work in a consistent
        way. A "Howto" article on filtering P2P with Shorewall and ipp2p will
        be forthcoming.</para>
      </listitem>

      <listitem>
        <para>LEAF/Bering packages for 2.4.0 and later releases are not
        available from shorewall.net. See the <ulink
        url="http://leaf.sourceforge.net">LEAF site</ulink> for those
        packages.</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Version &gt;= 2.2.0</title>

    <orderedlist>
      <listitem>
        <para>Shorewall configuration files except shorewall.conf are now
        empty (they contain only comments). If you wish to retain the defaults
        in any of the following files, you should copy these files before
        upgrading them then restore them after the upgrade:</para>

        <simplelist>
          <member>/etc/shorewall/zones</member>

          <member>/etc/shorewall/policy</member>

          <member>/etc/shorewall/tos</member>
        </simplelist>
      </listitem>

      <listitem>
        <para>The following builtin actions have been removed and have been
        replaced by the new action logging implementation described in the new
        features below.</para>

        <simplelist>
          <member>logNotSyn</member>

          <member>rLogNotSyn</member>

          <member>dLogNotSyn</member>
        </simplelist>
      </listitem>

      <listitem>
        <para>If shorewall.conf is upgraded to the latest version, it needs to
        be modified to set STARTUP_ENABLED=Yes.</para>
      </listitem>

      <listitem>
        <para>The Leaf/Bering version of Shorewall was previously
        named:</para>

        <simplelist>
          <member>shorwall-&lt;version&gt;.lrp</member>
        </simplelist>

        <para>Beginning with 2.1, that file will now be named:</para>

        <simplelist>
          <member>shorewall-lrp-&lt;version&gt;.tgz</member>
        </simplelist>

        <para>Simply rename that file to 'shorwall.lrp' when installing it on
        your LEAF/Bering system.</para>
      </listitem>

      <listitem>
        <para>The ORIGINAL DEST column of the /etc/shorewall/rules file may no
        longer contain a second (SNAT) address. You must use an entry in
        /etc/shorewall/masq instead.</para>

        <para>Example from Shorewall FAQ #1:</para>

        <blockquote>
          <para>Prior to Shorewall 2.1:</para>

          <para>/etc/shorewall/interfaces</para>

          <programlisting>#ZONE     INTERFACE      BROADCAST     OPTIONS
loc       eth1           detect        routeback</programlisting>

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

          <programlisting>#ACTION  SOURCE   DEST             PROTO   DEST PORT   SOURCE  ORIGINAL
#                                                      PORT    DEST
DNAT     loc      loc:192.168.1.12 tcp     80          -       130.252.100.69:192.168.1.254  </programlisting>

          <para>Shorewall 2.1 and Later:</para>

          <para>/etc/shorewall/interfaces</para>

          <programlisting>#ZONE     INTERFACE      BROADCAST     OPTIONS
loc       eth1           detect        routeback</programlisting>

          <para>/etc/shorewall/masq:</para>

          <programlisting>#INTERFACE     SUBNETS      ADDRESS        PROTO    PORT(S)
eth1           eth1         192.168.1.254  tcp      80</programlisting>

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

          <programlisting>#ACTION  SOURCE   DEST             PROTO   DEST PORT   SOURCE  ORIGINAL
#                                                      PORT    DEST
DNAT     loc      loc:192.168.1.12 tcp     80          -       130.252.100.69</programlisting>
        </blockquote>
      </listitem>

      <listitem>
        <para>The 'logunclean' and 'dropunclean' options that were deprecated
        in Shorewall 2.0 have now been removed completely.</para>
      </listitem>

      <listitem>
        <para>The default port for 'openvpn' tunnels (/etc/shorewall/tunnels)
        has been changed to 1194 to match a similar change in the OpenVPN
        product. The IANA has registered port 1194 for use by OpenVPN.</para>
      </listitem>

      <listitem>
        <para>A new IPTABLES variable has been added to shorewall.conf. This
        variable names the iptables executable that Shorewall will use. The
        variable is set to "/sbin/iptables". If you use the new
        shorewall.conf, you may need to change this setting to maintain
        compatibility with your current setup (if you use your existing
        shorewall.conf that does not set IPTABLES then you should experience
        no change in behavior).</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Version &gt;= 2.0.2 RC1</title>

    <itemizedlist>
      <listitem>
        <para>If you are upgrading from Shorewall 1.4.x and you have commands
        in your <filename>/etc/shorewall/common</filename> file that are not
        directly related to the <emphasis role="bold">common</emphasis> chain
        then you will want to move those commands to
        <filename>/etc/shorewall/initdone</filename>.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 2.0.2 Beta 1</title>

    <itemizedlist>
      <listitem>
        <para>Extension Scripts - In order for extension scripts to work
        properly with the new iptables-save/restore integration introduced in
        Shorewall 2.0.2 Beta 1, some change may be required to your extension
        scripts.</para>

        <para>If your extension scripts are executing commands other than
        <command>iptables</command> then those commands must also be written
        to the restore file (a temporary file in <filename
        class="directory">/var/lib/shorewall</filename> that is renamed
        <filename>/var/lib/shorewall/restore-base</filename> at the completion
        of the <filename>/sbin/shorewall</filename> command). The following
        functions should be of help:</para>

        <orderedlist>
          <listitem>
            <para>save_command() -- saves the passed command to the restore
            file.</para>

            <para>Example: <programlisting>save_command echo Operation Complete</programlisting></para>

            <para>That command would simply write "echo Operation Complete" to
            the restore file.</para>
          </listitem>

          <listitem>
            <para>run_and_save_command() -- saves the passed command to the
            restore file then executes it. The return value is the exit status
            of the command. Example: <programlisting>run_and_save_command "echo 1 &gt; /proc/sys/net/ipv4/icmp_echo_ignore_all"</programlisting></para>

            <para>Note that as in this example, when the command involves file
            redirection then the entire command must be enclosed in quotes.
            This applies to all of the functions described here.</para>
          </listitem>

          <listitem>
            <para>ensure_and_save_command() -- runs the passed command. If the
            command fails, the firewall is restored to its prior saved state
            and the operation is terminated. If the command succeeds, the
            command is written to the restore file</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Dynamic Zone support. - If you don't need to use the
        <command>shorewall add</command> and <command>shorewall
        delete</command> commands, you should set DYNAMIC_ZONES=No in
        <filename>/etc/shorewall/shorewall.conf</filename>.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 2.0.1</title>

    <itemizedlist>
      <listitem>
        <para>The function of 'norfc1918' is now split between that option and
        a new 'nobogons' option. The rfc1918 file released with Shorewall now
        contains entries for only those three address ranges reserved by RFC
        1918. A 'nobogons' interface option has been added which handles bogon
        source addresses (those which are reserved by the IANA, those reserved
        for DHCP auto-configuration and the class C test-net reserved for
        testing and documentation examples). This will allow users to perform
        RFC 1918 filtering without having to deal with out of date data from
        IANA. Those who are willing to update their
        <filename>/usr/share/shorewall/bogons</filename> file regularly can
        specify the 'nobogons' option in addition to 'norfc1918'. The level at
        which bogon packets are logged is specified in the new BOGON_LOG_LEVEL
        variable in shorewall.conf. If that option is not specified or is
        specified as empty (e.g, BOGON_LOG_LEVEL="") then bogon packets whose
        TARGET is 'logdrop' in
        <filename>/usr/share/shorewall/bogons</filename> are logged at the
        'info' level.</para>

        <warning>
          <para>If you have a file named <filename>rfc1918</filename> in your
          <filename class="directory">/etc/shorewall</filename> directory, you
          must either remove that file or you must copy
          <filename>/usr/share/shorewall/rfc1918</filename> to <filename
          class="directory">/etc/shorewall</filename> and modify that file
          appropriately. Do not leave the old <filename>rfc1918</filename>
          file in <filename
          class="directory">/etc/shorewall</filename>.</para>
        </warning>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>VERSION &gt;= 2.0.0-Beta1</title>

    <itemizedlist>
      <listitem>
        <para>The 'dropunclean' and 'logunclean' interface options are no
        longer supported. If either option is specified in
        <filename>/etc/shorewall/interfaces</filename>, a threatening message
        will be generated.</para>
      </listitem>

      <listitem>
        <para>The NAT_BEFORE_RULES option has been removed from
        <filename>shorewall.conf</filename>. The behavior of Shorewall 2.0 is
        as if NAT_BEFORE_RULES=No had been specified. In other words, DNAT
        rules now always take precedence over one-to-one NAT
        specifications.</para>
      </listitem>

      <listitem>
        <para>The default value for the ALL INTERFACES column in
        <filename>/etc/shorewall/nat</filename> has changed. In Shorewall 1.*,
        if the column was left empty, a value of "Yes" was assumed. This has
        been changed so that a value of "No" is now assumed.</para>
      </listitem>

      <listitem>
        <para>The following files don't exist in Shorewall 2.0:</para>

        <simplelist>
          <member><filename>/etc/shorewall/common.def</filename></member>

          <member><filename>/etc/shorewall/common</filename></member>

          <member><filename>/etc/shorewall/icmpdef</filename></member>

          <member><filename>/etc/shorewall/action.template</filename> (moved
          to
          <filename>/usr/share/shorewall/action.template</filename>)</member>
        </simplelist>

        <para>The <filename>/etc/shorewall/action</filename> file now allows
        an action to be designated as the "common" action for a particular
        policy type by following the action name with ":" and the policy
        (DROP, REJECT or ACCEPT).</para>

        <para>The file /usr/share/shorewall/actions.std has been added to
        define those actions that are released as part of Shorewall 2.0 In
        that file are two actions as follows:</para>

        <simplelist>
          <member>Drop:DROP</member>

          <member>Reject:REJECT</member>
        </simplelist>

        <para>The <quote>Drop</quote> action is the common action for DROP
        policies while the <quote>Reject</quote> action is the default action
        for REJECT policies. These actions will be performed on packets prior
        to applying the DROP or REJECT policy respectively. In the first
        release, the difference between "Reject" and "Drop" is that "Reject"
        REJECTs SMB traffic while "Drop" silently drops such traffic.</para>

        <para>As described above, Shorewall allows a common action for ACCEPT
        policies but does not specify such an action in the default
        configuration.</para>

        <para>For more information see the <ulink
        url="Actions.html">User-defined Action Page</ulink>.</para>
      </listitem>

      <listitem>
        <para>The <filename>/etc/shorewall</filename> directory no longer
        contains <filename>users</filename> file or a
        <filename>usersets</filename> file. Similar functionality is now
        available using user-defined actions.</para>

        <para>Now, action files created by copying
        <filename>/usr/share/shorewall/action.template</filename> may now
        specify a USER and or GROUP name/id in the final column just like in
        the rules file (see below). It is thus possible to create actions that
        control traffic from a list of users and/or groups.</para>
      </listitem>

      <listitem>
        <para>The last column in <filename>/etc/shorewall/rules</filename> is
        now labeled USER/GROUP and may contain:</para>

        <simplelist>
          <member>[!]&lt;<emphasis>user number</emphasis>&gt;[:]</member>

          <member>[!]&lt;<emphasis>user name</emphasis>&gt;[:]</member>

          <member>[!]:&lt;<emphasis>group number</emphasis>&gt;</member>

          <member>[!]:&lt;<emphasis>group name</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          number</emphasis>&gt;:&lt;<emphasis>group
          number</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          name</emphasis>&gt;:&lt;<emphasis>group
          number</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          inumber</emphasis>&gt;:&lt;<emphasis>group
          name</emphasis>&gt;</member>

          <member>[!]&lt;<emphasis>user
          name</emphasis>&gt;:&lt;<emphasis>group name</emphasis>&gt;</member>
        </simplelist>
      </listitem>

      <listitem>
        <para>If your kernel has IPV6 support (recent
        <trademark>SUSE</trademark> for example), and you don't use IPV6 then
        you will probably want to set DISABLE_IPV6=Yes in <ulink
        url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink>.
        You must have ipv6tables installed.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 1.4.9</title>

    <itemizedlist>
      <listitem>
        <para>The default value of NEWNOTSYN set in <ulink
        url="Documentation.htm#Conf">/etc/shorewall/shorewall.conf</ulink> has
        been changed from 'No' to 'Yes'. I find that NEWNOTSYN=No tends to
        result in lots of "stuck" connections because any network timeout
        during TCP session tear down results in retries being dropped
        (Netfilter has removed the connection from the conntrack table but the
        end-points haven't completed shutting down the connection). I
        therefore have chosen NEWNOTSYN=Yes as the default value and I advise
        caution in using NEWNOTSYN=Yes.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 1.4.8</title>

    <itemizedlist mark="bullet">
      <listitem>
        <para>The meaning of <varname>ROUTE_FILTER=Yes</varname> has changed.
        Previously this setting was documented as causing route filtering to
        occur on all network interfaces; this didn't work. Beginning with this
        release, <varname>ROUTE_FILTER=Yes</varname> causes route filtering to
        occur on all interfaces brought up while Shorewall is running. This
        means that it may be appropriate to set
        <varname>ROUTE_FILTER=Yes</varname> and use the routefilter option in
        <filename
        class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
        entries.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 1.4.6</title>

    <itemizedlist mark="bullet">
      <listitem>
        <para>The <varname>NAT_ENABLED</varname>,
        <varname>MANGLE_ENABLED</varname> and <varname>MULTIPORT</varname>
        options have been removed from <filename>shorewall.conf</filename>.
        These capabilities are now automatically detected by Shorewall.</para>
      </listitem>

      <listitem>
        <para>An undocumented feature previously allowed entries in the host
        file as follows: <synopsis>
zone	eth1:192.168.1.0/24,eth2:192.168.2.0/24
				</synopsis> This capability was never documented and has been removed in
        1.4.6 to allow entries of the following format: <synopsis>
zone	eth1:192.168.1.0/24,192.168.2.0/24
				</synopsis></para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 1.4.4</title>

    <para>If you are upgrading from 1.4.3 and have set the
    <varname>LOGMARKER</varname> variable in <filename
    class="directory">/etc/shorewall/</filename><filename>shorewall.conf</filename>,
    then you must set the new <varname>LOGFORMAT</varname> variable
    appropriately and remove your setting of
    <varname>LOGMARKER</varname>.</para>
  </section>

  <section>
    <title>Version 1.4.4</title>

    <para>If you have zone names that are 5 characters long, you may
    experience problems starting Shorewall because the
    <option>--log-prefix</option> in a logging rule is too long. Upgrade to
    Version 1.4.4a to fix this problem.</para>
  </section>

  <section>
    <title>Version &gt;= 1.4.2</title>

    <para>There are some cases where you may want to handle traffic from a
    particular group to itself. While I personally think that such a setups
    are ridiculous, there are two cases covered in this documentation where it
    can occur: <itemizedlist>
        <listitem>
          <para><ulink url="FAQ.htm#faq2">In FAQ #2</ulink></para>
        </listitem>

        <listitem>
          <para><ulink url="Shorewall_Squid_Usage.html">When running
          <application>Squid</application> as a transparent proxy in your
          local zone.</ulink></para>
        </listitem>
      </itemizedlist> If you have either of these cases, you will want to
    review the current documentation and change your configuration
    accordingly.</para>
  </section>

  <section>
    <title>Version &gt;= 1.4.1</title>

    <itemizedlist mark="bullet">
      <listitem>
        <para>Beginning with Version 1.4.1, traffic between groups in the same
        zone is accepted by default. Previously, traffic from a zone to itself
        was treated just like any other traffic; any matching rules were
        applied followed by enforcement of the appropriate policy. With 1.4.1
        and later versions, unless you have explicit rules for traffic from Z
        to Z or you have an explicit Z to Z policy (where "Z" is some zone)
        then traffic between the groups in zone Z will be accepted. If you do
        have one or more explicit rules for Z to Z or if you have an explicit
        Z to Z policy then the behavior is as it was in prior versions.</para>

        <orderedlist numeration="arabic">
          <listitem>
            <para>If you have a Z Z ACCEPT policy for a zone to allow traffic
            between two interfaces to the same zone, that policy can be
            removed and traffic between the interfaces will traverse fewer
            rules than previously.</para>
          </listitem>

          <listitem>
            <para>If you have a Z Z DROP or Z Z REJECT policy or you have
            Z-&gt;Z rules then your configuration should not require any
            change.</para>
          </listitem>

          <listitem>
            <para>If you are currently relying on a implicit policy (one that
            has "all" in either the SOURCE or DESTINATION column) to prevent
            traffic between two interfaces to a zone Z and you have no rules
            for Z-&gt;Z then you should add an explicit DROP or REJECT policy
            for Z to Z.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Sometimes, you want two separate zones on one interface but you
        don't want Shorewall to set up any infrastructure to handle traffic
        between them. <example>
            <title>The <filename>zones</filename>,
            <filename>interfaces</filename> and, <filename>hosts</filename>
            file contents</title>

            <programlisting>
<filename class="directory">/etc/shorewall/</filename><filename>zones</filename>
z1	Zone1	The first Zone
z2	Zone2	The second Zone

<filename class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
z2	eth1	192.168.1.255

<filename class="directory">/etc/shorewall/</filename><filename>hosts</filename>
z1	eth1:192.168.1.3
					</programlisting>
          </example> Here, zone z1 is nested in zone z2 and the firewall is
        not going to be involved in any traffic between these two zones.
        Beginning with Shorewall 1.4.1, you can prevent Shorewall from setting
        up any infrastructure to handle traffic between z1 and z2 by using the
        new NONE policy: <example>
            <title>The contents of <filename>policy</filename></title>

            <programlisting>
<filename class="directory">/etc/shorewall/</filename><filename>policy</filename>
z1	z2	NONE
z2	z1	NONE
					</programlisting>
          </example> Note that NONE policies are generally used in pairs
        unless there is asymmetric routing where only the traffic on one
        direction flows through the firewall and you are using a NONE policy
        in the other direction.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version 1.4.1</title>

    <itemizedlist mark="bullet">
      <listitem>
        <para>In Version 1.4.1, Shorewall will never create rules to deal with
        traffic from a given group back to itself. The
        <varname>multi</varname> interface option is no longer available so if
        you want to route traffic between two subnetworks on the same
        interface then I recommend that you upgrade to Version 1.4.2 and use
        the <varname>routeback</varname> interface or host option.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Version &gt;= 1.4.0</title>

    <important>
      <para>Shorewall &gt;=1.4.0 requires the <command>iproute</command>
      package ('<literal>ip</literal>' utility).</para>
    </important>

    <note>
      <para>Unfortunately, some distributions call this package
      <command>iproute2</command> which will cause the upgrade of Shorewall to
      fail with the diagnostic: <synopsis>error: failed dependencies:iproute is needed by shorewall-1.4.0-1</synopsis>This
      may be worked around by using the <option>--nodeps</option> option of
      <command>rpm</command> (<command>rpm -Uvh --nodeps
      <filename>your_shorewall_rpm.rpm</filename></command>).</para>
    </note>

    <para>If you are upgrading from a version &lt; 1.4.0, then: <itemizedlist
        mark="bullet">
        <listitem>
          <para>The <varname>noping</varname> and
          <varname>forwardping</varname> interface options are no longer
          supported nor is the <varname>FORWARDPING</varname> option in
          <filename>shorewall.conf</filename>. ICMP echo-request (ping)
          packets are treated just like any other connection request and are
          subject to rules and policies.</para>
        </listitem>

        <listitem>
          <para>Interface names of the form
          <varname>&lt;device&gt;:&lt;integer&gt;</varname> in <filename
          class="directory">/etc/shorewall/</filename><filename>interfaces</filename>
          now generate a Shorewall error at startup (they always have produced
          warnings in <application
          class="software">iptables</application>).</para>
        </listitem>

        <listitem>
          <para>The <varname>MERGE_HOSTS</varname> variable has been removed
          from <filename>shorewall.conf</filename>. Shorewall 1.4 behaves like
          1.3 did when <varname>MERGE_HOSTS=Yes</varname>; that is zone
          contents are determined by <emphasis>BOTH</emphasis> the interfaces
          and hosts files when there are entries for the zone in both
          files.</para>
        </listitem>

        <listitem>
          <para>The <varname>routestopped</varname> option in the interfaces
          and hosts file has been eliminated; use entries in the
          <filename>routestopped</filename> file instead.</para>
        </listitem>

        <listitem>
          <para>The Shorewall 1.2 syntax for <varname>DNAT</varname> and
          <varname>REDIRECT</varname> rules is no longer accepted; you must
          convert to using the new syntax.</para>
        </listitem>

        <listitem>
          <para>The <varname>ALLOWRELATED</varname> variable in
          <filename>shorewall.conf</filename> is no longer supported.
          Shorewall 1.4 behavior is the same as 1.3 with
          <varname>ALLOWRELATED=Yes</varname>.</para>
        </listitem>

        <listitem>
          <para>Late-arriving DNS replies are now dropped by default; there is
          no need for your own <filename
          class="directory">/etc/shorewall/</filename><filename>common</filename>
          file simply to avoid logging these packets.</para>
        </listitem>

        <listitem>
          <para>The <filename>firewall</filename>,
          <filename>functions</filename> and <filename>version</filename>
          files have been moved to <filename
          class="directory">/usr/share/shorewall</filename>.</para>
        </listitem>

        <listitem>
          <para>The <filename>icmp.def</filename> file has been removed. If
          you include it from <filename
          class="directory">/etc/shorewall/</filename><filename>icmpdef</filename>,
          you will need to modify that file.</para>
        </listitem>

        <listitem>
          <para>If you followed the advice in FAQ #2 and call
          <varname>find_interface_address</varname> in <filename
          class="directory">/etc/shorewall/</filename><filename>params</filename>,
          that code should be moved to <filename
          class="directory">/etc/shorewall/</filename><filename>init</filename>.</para>
        </listitem>
      </itemizedlist></para>
  </section>

  <section>
    <title>Version 1.4.0</title>

    <itemizedlist mark="bullet">
      <listitem>
        <para>The <varname>multi</varname> interface option is no longer
        supported. Shorewall will generate rules for sending packets back out
        the same interface that they arrived on in two cases: <itemizedlist
            mark="hollow">
            <listitem>
              <para>There is an <emphasis>explicit</emphasis> policy for the
              source zone to or from the destination zone. An explicit policy
              names both zones and does not use the <varname>all</varname>
              reserved word.</para>
            </listitem>

            <listitem>
              <para>There are one or more rules for traffic for the source
              zone to or from the destination zone including rules that use
              the <varname>all</varname> reserved word. Exception: if the
              source zone and destination zone are the same then the rule must
              be explicit - it must name the zone in both the
              <varname>SOURCE</varname> and <varname>DESTINATION</varname>
              columns.</para>
            </listitem>
          </itemizedlist></para>
      </listitem>
    </itemizedlist>
  </section>
</article>