shorewall_code/docs/LennyToSqueeze.xml

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

  <articleinfo>
    <title>Shorewall Issues when Upgrading from Debian Lenny to
    Squeeze</title>

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

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

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

    <copyright>
      <year>2009</year>

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

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

  <section>
    <title>Introduction</title>

    <para>Debian Lenny includes Shorewall version 4.0.15 while Squeeze will
    soon include Shorewall 4.4. Because there are significant differences
    between the two product versions, some users may experience upgrade
    issues. This article outlines those issues and offers advice for dealing
    with them.</para>

    <note>
      <para>Although this article is targeted specifically at Lenny -&gt;
      Squeeze upgrades, it should be useful to any Shorewall-shell user
      upgrading to Shorewall 4.4.x.</para>
    </note>
  </section>

  <section>
    <title>Packaging Differences</title>

    <para>The first key difference between Shorewall 4.0 and Shorewall 4.4 is
    in the packaging. In Lenny, there are six Shorewall packages:</para>

    <orderedlist>
      <listitem>
        <para>shorewall-common — Contains the basic components needed to
        create an IPv4 firewall.</para>
      </listitem>

      <listitem>
        <para>shorewall-shell — The legacy Shorewall configuration compiler
        written in Bourne shell.</para>
      </listitem>

      <listitem>
        <para>shorewall — A transitional package that depends on
        shorewall-common and shorewall-shell. Installing this package installs
        both shorewall-common and shorewall-shell.</para>
      </listitem>

      <listitem>
        <para>shorewall-perl — A re-implementation of the Shorewall
        configuration compiler in Perl. This compiler has many advantages over
        the shell-based compiler:</para>

        <itemizedlist>
          <listitem>
            <para>The compiler is much faster</para>
          </listitem>

          <listitem>
            <para>The compiler does a much better job of validating the
            configuration, thus avoiding run-time errors.</para>
          </listitem>

          <listitem>
            <para>The compiler produces better and more consistent diagnostic
            messages.</para>
          </listitem>

          <listitem>
            <para>The compiler produces a script that runs much faster and
            that does not reject/drop connections during start/restart.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>shorewall-lite — A small package that can run scripts generated
        by shorewall-shell or shorewall-perl. Allows centralized firewall
        administration.</para>
      </listitem>

      <listitem>
        <para>shorewall-doc — Documentation.</para>
      </listitem>
    </orderedlist>

    <para>In Squeeze, there are five packages:</para>

    <orderedlist>
      <listitem>
        <para>shorewall — Contains everything needed to create an IPv4
        firewall. It combines the former shorewall-common and shorewall-perl
        packages.</para>
      </listitem>

      <listitem>
        <para>shorewall6 — Depends on shorewall. Adds those components needed
        to create an IPv6 firewall.</para>
      </listitem>

      <listitem>
        <para>shorewall-lite — Same as in Lenny; only runs IPv4 firewall
        scripts.</para>
      </listitem>

      <listitem>
        <para>shorewall6-lite — Similar to shorewall-lite, except that it only
        runs IPv6 firewall scripts.</para>
      </listitem>

      <listitem>
        <para>shorewall-doc — Documentation.</para>
      </listitem>
    </orderedlist>

    <warning>
      <para>Do not purge the old packages (shorewall-common, shorewall-shell
      and shorewall-perl) until after the new shorewall package has been
      installed.</para>
    </warning>

    <para>The key change in Squeeze that may produce upgrade issues is that
    Squeeze does not include the shell-based configuration compiler. As a
    consequence, unless you are already using Shorewall-perl on Lenny, an
    upgrade from Lenny to Squeeze will mean that you will be switching from
    the old shell-based compiler to the new Perl-based compiler. While the two
    compilers are highly compatible, there are some differences. Those
    differences are detailed in the following sections.</para>
  </section>

  <section>
    <title>Issues Most Likely to Cause Problems or Concerns</title>

    <section>
      <title>shorewall.conf</title>

      <para>As always, when upgrading from one major release of Shorewall to
      another, the installer will prompt you about replacing your existing
      <filename>shorewall.conf</filename> with the updated one from the
      package. Shorewall is designed with the assumption that users will never
      replace shorewall.conf and retaining your existing file will always
      produce upward-compatible behavior.</para>

      <para>That having been said, there are a few settings that you may have
      in your shorewall.conf that will cause compilation warning or error
      messages after the upgrade.</para>

      <variablelist>
        <varlistentry>
          <term>BLACKLISTNEWONLY</term>

          <listitem>
            <para>If you have BLACKLISTNEWONLY=No together with
            FASTACCEPT=Yes, you will receive this error:</para>

            <para><emphasis role="bold">ERROR: BLACKLISTNEWONLY=No may not be
            specified with FASTACCEPT=Yes</emphasis></para>

            <para>To eliminate the error, reverse the setting of one of the
            options.</para>

            <note>
              <para>This combination never worked correctly in earlier
              versions -- to duplicate the earlier behavior, you will want to
              set BLACKLISTNEWONLY=Yes.</para>
            </note>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>BRIDGING</term>

          <listitem>
            <para>If you have set this option to Yes, you will receive the
            following error:</para>

            <para><emphasis role="bold">ERROR: BRIDGING=Yes is not supported
            by Shorewall 4.4.x</emphasis></para>

            <para>You should not be receiving this error if you are upgrading
            from Lenny since BRIDGING=Yes did not work in that release. If you
            have a bridge configuration where you want to control connections
            through the bridge, you will want to visit <ulink
            url="http://www.shorewall.net/bridge-Shorewall-perl.html">http://www.shorewall.net/bridge-Shorewall-perl.html</ulink>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>DELAYBLACKLISTLOAD</term>

          <listitem>
            <para>If you have set this option to Yes, you will receive the
            following warning:</para>

            <para><emphasis role="bold">WARNING: DELAYBLACKLIST=Yes is not
            supported by Shorewall 4.4.x</emphasis></para>

            <para>To eliminate the warning, set DELAYBLACKLISTLOAD=No or
            remove the setting altogether.</para>
          </listitem>
        </varlistentry>

        <varlistentry id="FW">
          <term>FW</term>

          <listitem>
            <para>If a setting for FW appears in your shorewall.conf file, you
            will receive this warning:</para>

            <para><emphasis role="bold">WARNING: Unknown configuration option
            (FW) ignored.</emphasis></para>

            <para>Remove the setting from the file and modify your
            <filename>/etc/shorewall/zones</filename> file as described <link
            linkend="zones">below</link>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>IPSECFILE</term>

          <listitem>
            <para>If you have specified IPSECFILE=ipsec or IPSECFILE= or if
            you do not have a setting for IPSECFILE, then you will receive the
            following error:</para>

            <para><emphasis role="bold">ERROR: IPSECFILE=ipsec is not
            supported by Shorewall 4.4.x</emphasis></para>

            <para>To eliminate the warning, you will need to:</para>

            <orderedlist>
              <listitem>
                <para>Set IPSECFILE=zones</para>
              </listitem>

              <listitem>
                <para>Modify your <filename>/etc/shorewall/zones</filename>
                file as described <link linkend="zones">below</link>.</para>
              </listitem>
            </orderedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>RFC1918_LOG_LEVEL</term>

          <listitem>
            <para>If you have specified any setting for this option, you will
            receive the following warning:</para>

            <para><emphasis role="bold">WARNING: RFC1918_LOG_LEVEL=value
            ignored. The 'norfc1918' interface/host option is no longer
            supported.</emphasis></para>

            <para>To eliminate the warning, set RFC1918_LOG_LEVEL= or simply
            remove the setting altogether.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>RFC1918_STRICT</term>

          <listitem>
            <para>If you have set this option to Yes, you will receive the
            following warning:</para>

            <para><emphasis role="bold">WARNING: RFC1918_STRICT=Yes is not
            supported by Shorewall 4.4.x</emphasis></para>

            <para>To eliminate the warning, set RFC1918_STRICT=No or remove
            the setting altogether.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>SAVE_IPSETS</term>

          <listitem>
            <para>If you have SAVE_IPSETS=Yes, you will receive the following
            warning:</para>

            <para><emphasis role="bold">WARNING SAVE_IPSETS=Yes is not
            supported by Shorewall 4.4.x</emphasis></para>

            <para>To eliminate this message, you will need to set
            SAVE_IPSETS=No or remove the setting altogether.</para>

            <para>For more information, see <ulink
            url="Shorewall-perl.html#SAVE_IPSETS">this article</ulink>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>SHOREWALL_COMPILER</term>

          <listitem>
            <para>If you have specified SHOREWALL_COMPILER=shell, you will
            receive the following warning message:</para>

            <para><emphasis role="bold">WARNING: SHOREWALL_COMPILER=shell
            ignored. Shorewall-shell support has been removed in this
            release</emphasis></para>

            <para>To eliminate the warning, set SHOREWALL_COMPILER=perl or
            simply remove the setting altogether.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>USE_ACTIONS</term>

          <listitem>
            <para>If you have set this option to No, you will receive the
            following warning:</para>

            <para><emphasis role="bold">WARNING: USE_ACTIONS=No is not
            supported by Shorewall 4.4.x</emphasis></para>

            <para>To eliminate the warning, set USE_ACTIONS=Yes or remove the
            setting altogether.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section id="zones">
      <title>/etc/shorewall/zones</title>

      <para>If the column headings in your /etc/shorewall/zones file look like
      this:</para>

      <programlisting>#ZONE   DISPLAY         COMMENTS
net     Net             The big bad net
loc     Local           The local LAN</programlisting>

      <para>then you are using the original zones file format that has been
      deprecated since Shorewall 3.0.</para>

      <para>You will need to convert to the new file format which has the
      following headings:</para>

      <programlisting>#ZONE   TYPE            OPTIONS         IN                      OUT
#                                       OPTIONS                 OPTIONS</programlisting>

      <para>You will need to add an entry for your firewall zone. The default
      name for the firewall zone is 'fw' but may have been overriden using
      <link linkend="FW">the FW option in
      <filename>shorewall.conf</filename></link>.</para>

      <programlisting>#ZONE   TYPE            OPTIONS         IN                      OUT
#                                       OPTIONS                 OPTIONS
fw      firewall</programlisting>

      <para>The remainder of your zones will have type 'ipv4' unless they are
      mentioned in your /etc/shorewall/ipsec file (see <link
      linkend="ipsec">below</link>).</para>

      <programlisting>#ZONE   TYPE            OPTIONS         IN                      OUT
#                                       OPTIONS                 OPTIONS
fw      firewall
net     ipv4            # The big bad net
loc     ipv4            # The local LAN</programlisting>
    </section>

    <section id="ipsec">
      <title>/etc/shorewall/ipsec</title>

      <para>This file is no longer used -- its specifications are now included
      in <filename>/etc/shorewall/zones</filename>.</para>

      <para>Take this example:</para>

      <programlisting>#ZONE   IPSEC    OPTIONS         IN              OUT
#       ONLY                     OPTIONS         OPTIONS
ipsec1  Yes
ipsec2  No</programlisting>

      <para>This would translate to the following entries in
      <filename>/etc/shorewall/zones</filename>:</para>

      <programlisting>#ZONE   TYPE            OPTIONS         IN                      OUT
#                                       OPTIONS                 OPTIONS
ipsec1  ipsec4
ipsec2  ipv4</programlisting>

      <para>Any OPTIONS, IN OPTIONS and OUT OPTIONS should simply be copied
      from <filename>/etc/shorewall/ipsec</filename> to
      <filename>/etc/shorewall/zones</filename>.</para>
    </section>

    <section>
      <title>/etc/shorewall/interfaces</title>

      <para>The BROADCAST column is essentially unused in Squeeze. If it
      contains anything except 'detect' or '-', then you will receive this
      warning:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: Shorewall no longer uses
        broadcast addresses in rule generation when Address Type Match is
        available</emphasis></para>
      </blockquote>

      <para>To eliminate the warning, replace the contents of the BROADCAST
      column with '-' or 'detect'.</para>

      <para>The 'norfc1918' option has been removed. If you specify the
      option, you will receive the following warning:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: Support for the norfc1918
        interface option has been removed from Shorewall</emphasis></para>
      </blockquote>

      <para>To eliminate the warning, simply remove the 'norfc1918' option
      from the OPTIONS list. You may wish to consider NULL_ROUTE_RFC1918=Yes
      as a replacement (see <ulink
      url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5)).</para>
    </section>

    <section>
      <title>/etc/shorewall/hosts</title>

      <para>The 'norfc1918' option has been removed. If you specify the
      option, you will receive the following warning:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: The 'norfc1918' option is no
        longer supported</emphasis></para>
      </blockquote>

      <para>To eliminate the warning, simply remove the 'norfc1918' option
      from the OPTIONS list. You may wish to consider NULL_ROUTE_RFC1918=Yes
      as a replacement (see <ulink
      url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5)).</para>
    </section>

    <section>
      <title>/etc/shorewall/masq</title>

      <para>There is a long tradition of specifying an interface name in the
      SOURCE column of this file. Given that masquerading/SNAT occurs in the
      Netfilter POSTROUTING chain where an incoming interface may not be
      specified, Shorewall must examine the main routing table during
      <command>shorewall start</command> and <command>shorewall
      restart</command> processing to determine those networks routed out of
      the named interface and then add MASQUERADE/SNAT rules for traffic from
      those networks. This requires that the named interface be up and
      configured when Shorewall starts or restarts.</para>

      <para>This continues to be a frequent issue with VPN configurations
      where the named interface isn't configured during boot.</para>

      <para>To emphasize this restriction, if an interface is named in the
      SOURCE column of one or more entries, a single warning as follows is
      issued:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: Using an interface as the masq
        SOURCE requires the interface to be up and configured when Shorewall
        starts/restarts</emphasis></para>
      </blockquote>

      <para>To suppress this warning, replace the interface name with the list
      of networks that are routed out of the interface.</para>

      <para>Example.</para>

      <para>Existing entry:</para>

      <programlisting>#INTERFACE              SOURCE          ADDRESS         PROTO   PORT(S) IPSEC   MARK    USER/
#                                                                                       GROUP
eth0                    eth1</programlisting>

      <para>Current routing configuration:</para>

      <programlisting>gateway:~# <command>ip route ls dev eth1</command>
172.20.1.0/24  proto kernel  scope link  src 172.20.1.254 
224.0.0.0/4  scope link 
gateway:~# 
</programlisting>

      <para>Replacement entry:</para>

      <programlisting>#INTERFACE              SOURCE          ADDRESS         PROTO   PORT(S) IPSEC   MARK    USER/
#                                                                                       GROUP
eth0                    172.20.1.0/24</programlisting>

      <para>Note that no entry is included for 224.0.0.0/4 since that is the
      multicast IP range and there should never be any packets with a SOURCE
      IP address in that network.</para>
    </section>

    <section>
      <title>/etc/shorewall/rules</title>

      <para>If you include a destination zone in a 'nonat' rule, Shorewall
      issues the following warning:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: Destination zone (zonename)
        ignored.</emphasis></para>
      </blockquote>

      <para>Nonat rules include:</para>

      <blockquote>
        <simplelist>
          <member>DNAT-</member>

          <member>REDIRECT-</member>

          <member>NONAT</member>
        </simplelist>
      </blockquote>

      <para>To eliminate the warning, remove the DEST zone.</para>

      <para>Example.</para>

      <para>Before:</para>

      <programlisting>#ACTION         SOURCE          DEST            PROTO   DEST    SOURCE          ORIGINAL        RATE            USER/   MARK    CONNLIMIT       TIME
#                                                       PORT    PORT(S)         DEST            LIMIT           GROUP
NONAT           loc             net             tcp     80</programlisting>

      <para>After:</para>

      <programlisting>#ACTION         SOURCE          DEST            PROTO   DEST    SOURCE          ORIGINAL        RATE            USER/   MARK    CONNLIMIT       TIME
#                                                       PORT    PORT(S)         DEST            LIMIT           GROUP
NONAT           loc             -               tcp     80</programlisting>
    </section>

    <section>
      <title>/etc/shorewall/routestopped</title>

      <para>The 'critical' option is no longer needed and hence is no longer
      supported. If you have critical hosts defined, you will receive this
      warning:</para>

      <blockquote>
        <para><emphasis role="bold">WARNING: The 'critical' option is no
        longer supported (or needed)</emphasis></para>
      </blockquote>

      <para>To suppress the warning, simply remove the option.</para>

      <para>Shorewall 4.4 also treats the <filename>routestopped</filename>
      file differently from earlier releases. Previously, the
      <filename>routestopped</filename> file was parsed during
      <command>shorewall stop</command> processing so that changes made to the
      file while Shorewall was running would be applied at the next
      <command>stop</command>. This is no longer the case -- the
      <filename>routestopped</filename> file is processed during compilation
      just like the rest of the configuration files so that when
      <command>shorewall stop</command> is issued, the firewall will pass
      traffic based on the contents of the <filename>routestopped</filename>
      file at the last <command>start</command> or
      <command>restart</command>.</para>
    </section>

    <section>
      <title>Extension Scripts</title>

      <para>If you have entries in Shorewall extension scripts
      (<filename>/etc/shorewall/init</filename>,
      <filename>/etc/shorewall/start</filename>, etc.) or if you have
      implemented an Action that uses an extension script, you should review
      <ulink url="Shorewall-perl.html#Extensions">this article</ulink>.</para>
    </section>
  </section>

  <section>
    <title>Additional Sources of Information</title>

    <para>The following articles provide additional information.</para>

    <itemizedlist>
      <listitem>
        <para><ulink url="Shorewall-perl.html#Incompatibilities">Shorewall
        Perl Incompatibilities</ulink></para>
      </listitem>

      <listitem>
        <para><ulink url="upgrade_issues.htm">Upgrade Issues</ulink></para>
      </listitem>
    </itemizedlist>
  </section>
</article>