shorewall_code/docs/upgrade_issues.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">
<!-- $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>

      <year>2008</year>

      <year>2009</year>

      <year>2012</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 id="Important">
    <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 show
    zones</command> command to see the groups associated with each of your
    zones.</para>
  </section>

  <section>
    <title>Versions &gt;= 4.5.0</title>

    <orderedlist>
      <listitem>
        <para>Shorewall, Shorewall6, Shorewall-lite and Shorewall6-lite now
        depend on the new package Shorewall-core. If you use the Shorewall
        installers, you must install Shorewall-core prior to installing or
        upgrading any of the other packages.</para>
      </listitem>

      <listitem>
        <para>The BLACKLIST section of the rules file has been eliminated. If
        you have entries in that file section, you must move them to the
        blrules file.</para>
      </listitem>

      <listitem>
        <para>This version of Shorewall requires the Digest::SHA1 or the
        Digest:SHA Perl module.</para>

        <simplelist>
          <member>Debian: libdigest-sha-perl</member>

          <member>Fedora: perl-Digest-SHA1</member>

          <member>OpenSuSE: perl-Digest-SHA1</member>
        </simplelist>
      </listitem>

      <listitem>
        <para>The generated firewall script now maintains the
        /var/lib/shorewall[6][-lite]/interface.status files used by SWPING and
        by LSM.</para>
      </listitem>

      <listitem>
        <para>Beginning with Shorewall 4.5.2, using /etc/shorewall-lite/vardir
        and /etc/shorewall6-lite/vardir to specify VARDIR is deprecated in
        favor of the VARDIR setting in shorewallrc.</para>

        <para>NOTE: While the name of the variable remains VARDIR, the meaning
        is slightly different. When set in shorewallrc, each product
        (shorewall-lite, and shorewall6-lite) will create a directory under
        the specified path name to hold state information.</para>

        <para>Example:</para>

        <blockquote>
          <para>VARDIR=/opt/var/</para>

          <para>The state directory for shorewall-lite will be
          /opt/var/shorewall-lite/ and the directory for shorewall6-lite will
          be /opt/var/shorewall6-lite.</para>
        </blockquote>

        <para>When VARDIR is set in /etc/shorewall[6]/vardir, the product will
        save its state directly in the specified directory.</para>
      </listitem>

      <listitem>
        <para>Begining with Shorewall 4.5.6, the tcrules file is processed if
        MANGLE_ENABLED=Yes, independent of the setting of TC_ENABLED. This
        allows actions like TTL and TPROXY to be used without enabling traffic
        shaping. If you have rules in your tcrules file that you only want
        processed when TC_ENABLED is other than 'No', then enclose them
        in</para>

        <blockquote>
          <para>?IF $TC_ENABLED</para>

          <para>...</para>

          <para>?ENDIF</para>
        </blockquote>

        <para>If they are to be processed only if TC_ENABLED=Internal, then
        enclose them in</para>

        <blockquote>
          <para>?IF TC_ENABLED eq 'Internal'</para>

          <para>...</para>

          <para>?ENDIF.</para>
        </blockquote>

        <para></para>
      </listitem>

      <listitem>
        <para>Beginning with Shorewall 4.5.7, the deprecated
        /etc/shorewall[6]/blacklist files are no longer installed. Existing
        files are still processed by the compiler.</para>

        <para>Note that blacklist files may be converted to equivalent blrules
        files using <command>shorewall[6] update -b</command>.</para>
      </listitem>

      <listitem>
        <para>In Shorewall 4.5.7, the
        <filename>/etc/shorewall[6]/notrack</filename> file was renamed
        <filename>/etc/shorewall[6]/conntrack</filename>. When upgrading to a
        release &gt;= 4.5.7, the <filename>conntrack</filename> file will be
        installed along side of an existing <filename>notrack</filename>
        file.</para>

        <para>If the 'notrack' file is non-empty, a warning message is issued
        during compilation:</para>

        <blockquote>
          <para>WARNING: Non-empty notrack file (...); please move its
          contents to the conntrack file</para>
        </blockquote>

        <para>This warning can be eliminated by removing the notrack file (if
        it has no entries), or by moving its entries to the conntrack file and
        removing the notrack file. Note that the conntrack file is always
        populated with rules</para>
      </listitem>

      <listitem>
        <para>In Shorewall 4.5.8, the /etc/shorewall[6]/routestopped files
        were deprecated if favor of new /etc/shorewall[6]/stoppedrules
        counterparts. The new files have much more familiar and
        straightforward semantics. Once a stoppedrules file is populated, the
        compiler will process that file and will ignore the corresponding
        routestopped file.</para>
      </listitem>

      <listitem>
        <para>In Shorewall 4.5.8, a new variable (VARLIB) was added to the
        shorewallrc file. This variable assumes the role formerly played by
        VARDIR, and VARDIR now designates the configuration directory for a
        particular product.</para>

        <para>This change should be transparent to all users:</para>

        <orderedlist numeration="loweralpha">
          <listitem>
            <para>If VARDIR is set in an existing shorewallrc file and VARLIB
            is not, then VARLIB is set to ${VARDIR} and VARDIR is set to
            ${VARLIB}/${PRODUCT}.</para>
          </listitem>

          <listitem>
            <para>If VARLIB is set in a shorewallrc file and VARDIR is not,
            then VARDIR is set to ${VARLIB}/${PRODUCT}.</para>
          </listitem>
        </orderedlist>

        <para> The Shorewall-core installer will automatically update
        ~/.shorewallrc and save the original in ~/.shorewallrc.bak.</para>
      </listitem>

      <listitem>
        <para>Previously, the macro.SNMP macro opened both UDP ports 161 and
        162 from SOURCE to DEST. This is against the usual practice of opening
        these ports in the opposite direction. Beginning with Shorewall 4.5.8,
        the SNMP macro opens port 161 from SOURCE to DEST as before, and a new
        SNMPTrap macro is added that opens port 162 (from SOURCE to
        DEST).</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Versions &gt;= 4.4.0</title>

    <orderedlist>
      <listitem>
        <para>If you are using Shorewall-perl, there are no additional upgrade
        issues. If you are using Shorewall-shell or are upgrading from a
        Shorewall version earlier than 4.0.0 then you will need to <ulink
        url="Shorewall-perl.html">migrate to Shorewall-perl</ulink>.
        Shorewall-4.3.5 and later only use the perl-based compiler.</para>

        <para>If you have specified "SHOREWALL_COMPILER=shell" in
        shorewall.conf, then you must either:</para>

        <itemizedlist>
          <listitem>
            <para>change that specification to "SHOREWALL_COMPILER=perl";
            or</para>
          </listitem>

          <listitem>
            <para>change that specification to "SHOREWALL_COMPILER=";
            or</para>
          </listitem>

          <listitem>
            <para>delete the specification altogether.</para>
          </listitem>
        </itemizedlist>

        <para>Failure to do so will result in the following
        warning:<blockquote>
            <para>WARNING: SHOREWALL_COMPILER=shell ignored. Support for
            Shorwall-shell has been removed in this release.</para>
          </blockquote></para>
      </listitem>

      <listitem>
        <para>The <command>shorewall stop</command>, <command>shorewall
        clear</command>, <command>shorewall6 stop</command> and
        <command>shorewall6 clear</command> commands no longer read the
        <filename>routestopped</filename> file. The
        <filename>routestopped</filename> file used is the one that was
        present at the last <command>start</command>,
        <command>restart</command> or <command>restore</command>
        command.<important>
            <para>If you modify the routestopped file, you must restart
            Shorewall before the changes to that file will take effect.</para>
          </important></para>
      </listitem>

      <listitem>
        <para>The old macro parameter syntax (e.g., SSH/ACCEPT) is now
        deprecated in favor of the new syntax (e.g., SSH(ACCEPT)). The 4.3
        documentation uses the new syntax exclusively, although the old syntax
        continues to be supported.</para>
      </listitem>

      <listitem>
        <para>Support for the SAME target in /etc/shorewall/masq and
        /etc/shorewall/rules has been removed, following the removal of the
        underlying support in the Linux kernel.</para>
      </listitem>

      <listitem>
        <para>Supplying an interface name in the SOURCE column of
        /etc/shorewall/masq is now deprecated. Entering the name of an
        interface there will result in a compile-time warning:</para>

        <para>WARNING: Using an interface as the masq SOURCE requires the
        interface to be up and configured when Shorewall
        starts/restarts</para>

        <para>To avoid this warning, replace interface names by the
        corresponding netwok(s) in CIDR format (e.g.,
        192.168.144.0/24).</para>
      </listitem>

      <listitem>
        <para>Previously, Shorewall has treated traffic shaping class IDs as
        decimal numbers (or pairs of decimal numbers). That worked fine until
        IPMARK was implemented. IPMARK requires Shorewall to generate class
        Ids in numeric sequence. In 4.3.9, that didn't work correctly because
        Shorewall was generating the sequence "..8,9,10,11..." when the
        correct sequence was "...8,9,a,b,...". Shorewall now treats class IDs
        as hex, like 'tc' and 'iptables' do.</para>

        <para>This should only be an issue if you have more than 9 interfaces
        defined in <filename>/etc/shorewall/tcdevices</filename> and if you
        use class IDs in <filename>/etc/shorewall/tcrules</filename>. You will
        need to renumber the class IDs for devices 10 and greater.</para>
      </listitem>

      <listitem>
        <para>Support for the 'norfc1918' interface and host option has been
        removed. If 'norfc1918' is specified for an entry in either the
        interfaces or the hosts file, a warning is issued and the option is
        ignored. Simply remove the option to avoid the warning.</para>

        <para>Similarly, if RFC1918_STRICT=Yes or a non-empty
        RFC1918_LOG_LEVEL is given in shorewall.conf, a warning will be issued
        and the option will be ignored.</para>

        <para>You may simply delete the RFC1918-related options from your
        shorewall.conf file if you are seeing warnings regarding them.</para>

        <para>Users who currently use 'norfc1918' are encouraged to consider
        using NULL_ROUTE_RFC1918=Yes instead.</para>
      </listitem>

      <listitem>
        <para>The install.sh scripts in the Shorewall and Shorewall6 packages
        no longer create a backup copy of the existing configuration. If you
        want your configuration backed up prior to upgrading, you will need to
        do that yourself. As part of this change, the fallback.sh scripts are
        no longer released.</para>
      </listitem>

      <listitem>
        <para>Previously, if an ipsec zone was defined as a sub-zone of an
        ipv4 or ipv6 zone using the special &lt;child&gt;:&lt;parent&gt;,...
        syntax, CONTINUE policies for the sub-zone did not work as expected.
        Traffic that was not matched by a sub-zone rule was not compared
        against the parent zone(s) rules. In 4.4.0, such traffic IS compared
        against the parent zone rules.</para>
      </listitem>

      <listitem>
        <para>The name <emphasis role="bold">any</emphasis> is now reserved
        and may not be used as a zone name.</para>
      </listitem>

      <listitem>
        <para>Perl module initialization has changed in Shorewall 4.4.1.
        Previously, each Shorewall Perl package would initialize its global
        variables for IPv4 in an INIT block. Then, if the compilation turned
        out to be for IPv6, Shorewall::Compiler::compiler() would reinitialize
        them for IPv6.</para>

        <para>Beginning in Shorewall 4.4.1, the modules do not initialize
        themselves in an INIT block. So if you use Shorewall modules outside
        of the Shorewall compilation environment, then you must explicitly
        call the module's 'initialize' function after the module has been
        loaded.</para>
      </listitem>

      <listitem>
        <para>Checking for zone membership has been tighened up. Previously, a
        zone could contain &lt;interface&gt;:0.0.0.0/0 along with other hosts;
        now, if the zone has &lt;interface&gt;:0.0.0.0/0 (even with
        exclusions), then it may have no additional members in <ulink
        url="manpages/shorewall-hosts.html">/etc/shorewall/hosts</ulink>.</para>
      </listitem>

      <listitem>
        <para>ADD_IP_ALIASES=No is now the setting in the released<ulink
        url="manpages/shorewall.conf.html"> shorewall.conf</ulink> and in all
        of the samples. This will not affect you during upgrade unless you
        choose to replace your current shorewall.conf with the one from the
        release (not recommended).</para>
      </listitem>

      <listitem>
        <para>The names of interface configuration variables in generated
        scripts have been changed to ensure uniqueness. These names now begin
        with SW_. This change will only affect you if your extension scripts
        are using one or more of these variables.</para>

        <informaltable>
          <tgroup cols="2">
            <tbody>
              <row>
                <entry>Old Variable Name</entry>

                <entry>New Variable Name</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_address</entry>

                <entry>SW_<replaceable>iface</replaceable>_ADDRESS</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_BCASTS</entry>

                <entry>SW_<replaceable>iface</replaceable>_BCASTS</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_ACASTS</entry>

                <entry>SW_<replaceable>iface</replaceable>_CASTS</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_GATEWAY</entry>

                <entry>SW_<replaceable>iface</replaceable>_NETWORKS</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_ADDRESSES</entry>

                <entry>SW_<literal>iface</literal>_ADDRESSES</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_NETWORKS</entry>

                <entry>SW_<replaceable>iface</replaceable>_NETWORKS</entry>
              </row>

              <row>
                <entry><replaceable>iface</replaceable>_MAC</entry>

                <entry>SW_<replaceable>iface</replaceable>_MAC</entry>
              </row>

              <row>
                <entry><replaceable>provider</replaceable>_IS_USABLE</entry>

                <entry>SW_<replaceable>provider</replaceable>_IS_USABLE</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>

        <para>were <replaceable>iface</replaceable> is a capitalized interface
        name (e.g., ETH0) and <replaceable>provider</replaceable> is the
        capitalized name of a provider.</para>
      </listitem>

      <listitem>
        <para>If your <ulink
        url="manpages/shorewall-params.html">/etc/shorewall/params</ulink> (or
        <ulink
        url="manpages6/shorewall6-params.html">/etc/shorewall6/params</ulink>)
        file sends output to Standard Output, you need to be aware that the
        output will be redirected to Standard Error beginning with Shorewall
        4.4.16.</para>
      </listitem>

      <listitem>
        <para>Beginning with Shorewall 4.4.17, the EXPORTPARAMS option is
        deprecated. With EXPORTPARAMS=No, the variables set by <ulink
        url="manpages/shorewall-params.html">/etc/shorewall/params</ulink>
        (<ulink
        url="manpages6/shorewall6-params.html">/etc/shorewall6/params</ulink>)
        at compile time are now available in the compiled firewall
        script.</para>
      </listitem>

      <listitem>
        <para>The <command>iprange</command> and <command>ipaddr</command>
        commands require the 'bc' utility.</para>
      </listitem>

      <listitem>
        <para>Beginning with Shorewall 4.4.26, the WIDE_TC_MARKS and
        HIGH_ROUTE_MARKS options are deprecated in favor of TC_BITS,
        MASK_BITS, PROVIDER_BITS and PROVIDER_OFFSET. See the <ulink
        url="PacketMarking.html#Values">Packet Marking using
        /etc/shorewall/tcrules</ulink> article. The <command>shorewall
        update</command> (<command>shorewall6 update</command>) command will
        automatically generate the correct values for these new options
        depending on your settings of WIDE_TC_MARKS and
        HIGH_ROUTE_MARKS.</para>
      </listitem>
    </orderedlist>

    <para>Be sure to check the latest 4.4 Release Notes linked from the <ulink
    url="index.htm">home page</ulink>.</para>
  </section>

  <section>
    <title>Versions &gt;= 4.2.0</title>

    <orderedlist>
      <listitem>
        <para>Previously, when HIGH_ROUTE_MARKS=Yes, Shorewall allowed
        non-zero mark values &lt; 256 to be assigned in the OUTPUT chain. This
        has been changed so that only high mark values may be assigned there.
        Packet marking rules for traffic shaping of packets originating on the
        firewall must be coded in the POSTROUTING table.</para>
      </listitem>

      <listitem>
        <para>Previously, Shorewall did not range-check the value of the
        VERBOSITY option in shorewall.conf. Beginning with Shorewall 4.2: a) A
        VERBOSITY setting outside the range -1 through 2 is rejected. b) After
        the -v and -q options are applied, the resulting value is adjusted to
        fall within the range -1 through 2.</para>
      </listitem>

      <listitem>
        <para>Specifying a destination zone in a NAT-only rule now generates a
        warning and the destination zone is ignored. NAT-only rules
        are:<simplelist>
            <member>NONAT</member>

            <member>REDIRECT-</member>

            <member>DNAT-</member>
          </simplelist></para>
      </listitem>

      <listitem>
        <para>The default value for LOG_MARTIANS has been changed. Previously,
        the defaults were: Shorewall-perl - 'Off' Shorewall-shell - 'No' The
        new default values are:</para>

        <variablelist>
          <varlistentry>
            <term>Shorewall-perl</term>

            <listitem>
              <para>'On.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Shorewall-shell</term>

            <listitem>
              <para>'Yes'</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>Shorewall-perl users may:</para>

        <orderedlist>
          <listitem>
            <para>Accept the new default -- martians will be logged from all
            interfaces with route filtering except those with log_martians=0
            in /etc/shorewall/interfaces.</para>
          </listitem>

          <listitem>
            <para>Explicitly set LOG_MARTIANS=Off to maintain compatibility
            with prior versions of Shorewall.</para>
          </listitem>
        </orderedlist>

        <para>Shorewall-shell users may:</para>

        <orderedlist>
          <listitem>
            <para>Accept the new default -- martians will be logged from all
            interfaces with the route filtering enabled.</para>
          </listitem>

          <listitem>
            <para>Explicitly set LOG_MARTIANS=No to maintain compatibility
            with prior versions of Shorewall.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>The value of IMPLICIT_CONTINUE in shorewall.conf (and samples)
        has been changed from Yes to No. If you are a Debian or Ubuntu user
        and you select replacement of shorewall.conf during upgrade to
        Shorewall 4.2, you will want to change IMPLICIT_CONTINUE back to 'Yes'
        if you have nested zones that rely on IMPLICIT_CONTINUE=Yes for proper
        operation.</para>
      </listitem>

      <listitem>
        <para>The 'norfc1918' option is deprecated. Use explicit rules
        instead. Note that there is a new 'Rfc1918' macro that acts on
        addresses reserved by RFC 1918.</para>
      </listitem>

      <listitem>
        <para>DYNAMIC_ZONES=Yes is no longer supported by Shorewall-perl. Use
        ipset-based zones instead.</para>
      </listitem>
    </orderedlist>
  </section>

  <section id="V4.0.0">
    <title>Versions &gt;= 4.0.0-Beta7</title>

    <orderedlist>
      <listitem>
        <para>Beginning with Shorewall 4.0.0, there is no single 'shorewall'
        package. Rather there are two compiler packages (shorewall-shell and
        shorewall-perl) and a set of base files (shorewall-common) required by
        either compiler package.</para>

        <para>Although the names of the packages are changing, you can upgrade
        without having to uninstall/reinstall.</para>

        <para>To repeat: <emphasis role="bold">You do not need to uninstall
        any existing package.</emphasis></para>

        <para>If you attempt to upgrade using the shorewall-common RPM, you
        get this result:<programlisting>gateway:~ # <command>rpm -Uvh shorewall-common-4.0.0.noarch.rpm </command>
error: Failed dependencies:
shorewall_compiler is needed by shorewall-common-4.0.0-1.noarch
gateway:~ #</programlisting>You must either:<programlisting><command>rpm -Uvh shorewall-shell-4.0.0.noarch.rpm shorewall-common-4.0.0.noarch.rpm</command></programlisting>or<programlisting><command>rpm -Uvh shorewall-shell-4.0.0.noarch.rpm shorewall-perl-4.0.0.noarch.rpm shorewall-common-4.0.0.noarch.rpm</command></programlisting>If
        you don't want shorewall-shell, you must use the second command
        (installing both shorewall-shell and shorewall-perl) then remove
        shorewall-shell using this command:<programlisting><command>rpm -e shorewall-shell</command></programlisting>If
        you are upgrading using the tarball, you must install shorewall-shell
        and/or shorewall-perl before you upgrade using shorewall-common.
        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>

        <para>Example 1: You have 'shorewall' installed and you want to
        continue to use the shorewall-shell compiler.<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2
tar -jxf shorewall-shell-4.0.0.tar.bz2

pushd shorewall-shell-4.0.0
./install.sh
popd
pushd shorewall-common-4.0.0
./install.sh
shorewall check
shorewall restart</command></programlisting>Example 2: You have shorewall
        3.4.4 and shorewall-perl 4.0.0-Beta7 installed and you want to upgrade
        to 4.0. You do not need the shell-based compiler.<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2
tar -jxf shorewall-perl-4.0.0.tar.bz2

pushd shorewall-perl-4.0.0
./install.sh
popd
pushd /shorewall-common-4.0.0
./install.sh
shorewall check
shorewall restart</command></programlisting> The RPMs are set up so that if
        you upgrade an existing Shorewall installation as part of a
        distribution upgrade and you have not already installed
        shorewall-perl, then you will end up with Shorewall-common and
        Shorewall-shell installed.</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>

      <listitem>
        <para>The <option>:noah</option> option is now the default for ipsec
        tunnels. Tunnels that use AH (protocol 51) must specify
        <option>ipsec:ah</option> in the TYPE column.</para>
      </listitem>

      <listitem>
        <para>Users upgrading from Debian Etch (Shorewall 3.2.6) to Debian
        Lenny (Shoreall 4.0.15) report finding an issue with VOIP (Asterisk)
        traffic. See <ulink url="FAQ.htm#faq77">Shorewall FAQ 77</ulink> for
        details.</para>
      </listitem>
    </orderedlist>
  </section>

  <section id="V3.4.0">
    <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 id="V3.2.0">
    <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 interacts 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 id="V3.0.0">
    <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="manpages/shorewall-zones.html">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 id="MAPOLDACTIONS">
        <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 id="V2.4.0">
    <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>
</article>