shorewall_code/Shorewall-docs2/ErrorMessages.xml

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

  <articleinfo>
    <title>Shorewall Error Messages</title>

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

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

    <pubdate>2005-03-08</pubdate>

    <copyright>
      <year>2004</year>

      <year>2005</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>Shorewall can produce a wide variety of error messages when a
    problem is detected with your configuration. This article attempts to
    explain the cause of and cures for some of these messages.</para>
  </section>

  <section>
    <title>Messages Produced by /sbin/shorewall</title>

    <para>Some error messages are produced by the /sbin/shorewall utility.
    These messages are detailed in this section.</para>

    <glosslist>
      <glossentry>
        <glossterm>ERROR: &lt;label&gt; must specify a simple file name:
        &lt;name&gt;</glossterm>

        <glossdef>
          <para>This means that you have specified a restore file name with a
          "/". Restore files must be simple file names with no slashes.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Shorewall is not properly installed</glossterm>

        <glossdef>
          <para>The files <filename>/usr/share/shorewall/firewall</filename>
          and/or <filename>/usr/share/shorewall/version</filename> do not
          exist.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: &lt;file name&gt; exists and is not a saved
        Shorewall configuration</glossterm>

        <glossdef>
          <para>The named file in <filename>/var/lib/shorewall</filename>
          exists but is not executable.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Reserved file name: &lt;file name&gt;</glossterm>

        <glossdef>
          <para>You have specified either <filename>save</filename> or
          <filename>restore-base</filename> as the name of a restore file --
          those names are reserved for use by Shorewall.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Currently-running Configuration Not
        Saved</glossterm>

        <glossdef>
          <para>During processing of a <command>shorewall save</command>
          command, the <command>iptables-save</command> command failed.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: /var/lib/shorewall/restore-base does not
        exist</glossterm>

        <glossdef>
          <para>The <command>shorewall start</command> and <command>shorewall
          restart</command> commands create a file called
          <filename>/var/lib/shorewall/restore-base</filename> which forms the
          basis for creating a restore file using <command>shorewall
          save</command>. This error message is issued when <command>shorewall
          save</command> is not able to find that file.</para>
        </glossdef>
      </glossentry>
    </glosslist>
  </section>

  <section>
    <title>Messages Produced by /usr/share/shorewall/firewall</title>

    <para>The program <filename>/usr/share/shorewall/firewall</filename> is
    responsible for parsing the Shorewall configuration files and for creating
    and changing the Netfilter configuration. Some of the error messages
    generated by this program are listed below.</para>

    <glosslist>
      <glossentry>
        <glossterm>ERROR: Invalid zone definition for zone
        &lt;zone&gt;</glossterm>

        <glossdef>
          <para>The zone named in the message is defined to be associated with
          an interface in <filename>/etc/shorewall/interfaces</filename> yet
          it also has an entry for that same interface in
          <filename>/etc/shorewall/hosts</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Invalid zone (&lt;zone&gt;) in record
        "&lt;record&gt;"</glossterm>

        <glossdef>
          <para>The zone named in the ZONE column of the listed record from
          <filename>/etc/shorewall/interfaces</filename> or
          <filename>/etc/shorewall/hosts</filename> is not defined in
          <filename>/etc/shorewall/zones</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Duplicate Interface &lt;interface&gt;</glossterm>

        <glossdef>
          <para>The named interface has two entries in
          <filename>/etc/shorewall/interfaces</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Invalid Interface Name:
        &lt;interface&gt;</glossterm>

        <glossdef>
          <para>The interface name contains a colon (":") or is "+". If the
          name includes a ":", you probably need to read <ulink
          url="Shorewall_and_Aliased_Interfaces.xml">this
          article</ulink>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Unknown interface (&lt;interface&gt;) in record
        "&lt;record&gt;"</glossterm>

        <glossdef>
          <para>The <emphasis>&lt;interface&gt;</emphasis> name listed in the
          <emphasis>&lt;record&gt;</emphasis> from
          <filename>/etc/shorewall/hosts</filename> was not defined in
          <filename>/etc/shorewall/interfaces</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Bridged interfaces may not be defined in
        /etc/shorewall/interfaces:
        &lt;interface&gt;[:&lt;address&gt;]</glossterm>

        <glossdef>
          <para>The named interface appears in /etc/shorewall/hosts and
          appears as a bridge port (after a colon) but is also defined in
          <filename>/etc/shorewall/interfaces</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Your kernel and/or iptables does not support policy
        match: ipsec</glossterm>

        <glossdef>
          <para>You have specified the <emphasis role="bold">ipsec</emphasis>
          option in an <filename>/etc/shorewall/hosts</filename> record but
          your kernel and/or iptables is missing policy match support. That
          support in turn requires a set of ipsec-netfilter patches in order
          to work correctly.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Undefined zone &lt;zone&gt;</glossterm>

        <glossdef>
          <para>The named zone appears in the /etc/shorewall/policy file but
          not in the /etc/shorewall/zones file.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Can't determine the IP address of
        &lt;interface&gt;</glossterm>

        <glossdef>
          <para>You have specified DETECT_DNAT_ADDRS=Yes in
          /etc/shorewall/shorewall.conf and Shorewall is unablee to determine
          the IP address of the named <emphasis>&lt;interface&gt;</emphasis>.
          Be sure that the interface is started before starting Shorewall or
          set DETECT_DNAT_ADDRS=No.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Invalid gateway zone (&lt;zone&gt;) -- Tunnel
        "&lt;record&gt;</glossterm>

        <glossdef>
          <para>The listed <emphasis>&lt;zone&gt;</emphasis> name appears in
          the GATEWAY ZONE column of the listed
          <emphasis>&lt;record&gt;</emphasis> from
          <filename>/etc/shorewall/tunnels</filename> but is not defined in
          <filename>/etc/shorewall/zones</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Your kernel and/or iptables does not support policy
        match</glossterm>

        <glossdef>
          <para>Your /etc/shorewall/ipsec file is non-empty but your kernel
          and/or iptables do not include policy match support. That support in
          turn requires a set of ipsec-netfilter patches in order to work
          correctly.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: No hosts on &lt;interface&gt; have the maclist
        option specified</glossterm>

        <glossdef>
          <para>The named <emphasis>&lt;interface&gt;</emphasis> appears in a
          record in <filename>/etc/shorewall/maclist</filename> yet that
          interface's record in <filename>/etc/shorewall/interfaces</filename>
          does not specify the <emphasis role="bold">maclist</emphasis> option
          and no record in <filename>/etc/shorewall/hosts</filename> that
          names that interface includes the <emphasis
          role="bold">maclist</emphasis> option.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Interface &lt;interface&gt; must be up before
        Shorewall can start</glossterm>

        <glossdef>
          <para>You have specified the <emphasis
          role="bold">maclist</emphasis> option for this interface but the
          command <command>ip list show &lt;interface&gt;</command>
          fails.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Unknown interface &lt;interface&gt;</glossterm>

        <glossdef>
          <para>The interface appears in a configuration file but is not
          defined in <filename>/etc/shorewall/interfaces</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: BRIDGING=Yes requires Physdev Match support in your
        Kernel and iptables</glossterm>

        <glossdef>
          <para>You have set BRIDGING=Yes in
          <filename>/etc/shorewall/shorewall.conf</filename> but it appears
          that your kernel and/or iptables do not have physdev match
          support.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Unknown interface &lt;interface&gt; in rule:
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>You have BRIDGING=No in
          <filename>/etc/shorewall/shorewall.conf</filename> and the
          <emphasis>&lt;interface&gt;</emphasis> given in a rule does not
          match an entry in
          <filename>/etc/shorewall/interfaces</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: SNAT may no longer be specified in a DNAT rule; use
        /etc/shorewall/masq instead</glossterm>

        <glossdef>
          <para>In earlier Shorewall versions, the ORIGINAL DEST column
          allowed following the original destination IP address with ":" and
          an address to use as the source of the forwarded connection request.
          Now that /etc/shorewall/masq supports qualification of SNAT rules by
          protocol and port, this feature is no longer required and has been
          deimplemented.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: "Invalid Source in rule "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The SOURCE column has the firewall zone name immediately
          followed by "!". This syntax is use to exclude a subzone and
          Shorewall currently doesn't support subzones of the firewall
          zone.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Rule "&lt;rule&gt;" - Destination may not be
        specified by MAC Address</glossterm>

        <glossdef>
          <para>Netfilter (and hence Shorewall) does not allow qualification
          of a rule by destination source IP address.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Destination interface not allowed with
        &lt;action&gt;</glossterm>

        <glossdef>
          <para>The named <emphasis>&lt;action&gt;</emphasis> will be ACCEPT+
          or NONAT. These actions are inforced in part in the PREROUTING nat
          chain where the destination interface is not yet known (because the
          packet has not yet been routed). As a result, the DESTINATION column
          may not contain an interface name.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Only DNAT and REDIRECT rules may specify destination
        mapping; rule "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The <emphasis>&lt;rule&gt;</emphasis> specifies a server
          address that is different from the ORIGINAL DEST address and/or it
          specifies a server port that is different from the destination port
          but the ACTION is neither DNAT[-] nor REJECT[-].</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Empty source zone or qualifier: rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The SOURCE column is of one of the forms
          <emphasis>&lt;zone&gt;</emphasis>:,
          :<emphasis>&lt;qualifier&gt;</emphasis> or :.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Exclude list only allowed with DNAT or
        REDIRECT</glossterm>

        <glossdef>
          <para>In DNAT[-] and REDIRECT[-] rules, you can have a SOURCE of the
          form
          <emphasis>&lt;zone&gt;</emphasis>:<emphasis>&lt;net1&gt;</emphasis>!<emphasis>&lt;net2&gt;</emphasis>.
          This means <emphasis>&lt;net1&gt;</emphasis> in the
          <emphasis>&lt;zone&gt;</emphasis> zone <emphasis role="bold">except
          for</emphasis> <emphasis>&lt;net2&gt;</emphasis>. This syntax is not
          available with other ACTIONs.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Invalid use of a user-qualification: rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The USER/GROUP column may only have and entry if the SOURCE is
          the firewall zone.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Empty destination zone or qualifier: rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The DEST column is of one of the forms
          <emphasis>&lt;zone&gt;</emphasis>:,
          :<emphasis>&lt;qualifier&gt;</emphasis> or :.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Undefined Client Zone in rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The zone given in the SOURCE column was not defined in
          <filename>/etc/shorewall/zones</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Undefined Server Zone in rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The zone given in the DEST column was not defined in
          <filename>/etc/shorewall/zones</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Rules may not override a NONE policy: rule
        "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>If the policy from zone z1 to zone z2 is NONE that means that
          Shorewall sets up no infrastructure to handle traffic from z1 to z2.
          Consequently, you cannot have any rules that control traffic from z1
          to z2.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Invalid Action in rule "&lt;rule&gt;"</glossterm>

        <glossdef>
          <para>The ACTION column contains an action that is not one of the
          built-in actions and it is not defined in
          <filename>/etc/shorewall/actions</filename> or in
          <filename>/usr/share/shorewall/actions.std</filename>.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>ERROR: Unable to determine the routes through interface
        &lt;interface&gt;</glossterm>

        <glossdef>
          <para>You have specified <emphasis>&lt;interface&gt;</emphasis> in
          the SUBNET column of <filename>/etc/shorewall/masq</filename> which
          means that Shorewall is supposed to determine the network(s) routed
          through that interface. To do that, Shorewall issues the command
          <command>ip addr ls dev &lt;interface&gt;</command> and that command
          failed. This usually means that you are trying to start Shorewall
          before the <emphasis>&lt;interface&gt;</emphasis> is brought
          up.</para>
        </glossdef>
      </glossentry>
    </glosslist>
  </section>

  <section>
    <title>Warnings</title>

    <para>This sections describes some of the more common warnings generated
    by Shorewall.</para>

    <glosslist>
      <glossentry>
        <glossterm>Warning: default route ignored on interface
        &lt;interface&gt;</glossterm>

        <glossdef>
          <para>This means that the interface named in the SUBNET column of
          <filename>/etc/shorewall/masq</filename> has the default route. This
          almost always means that you have the contents of the INTERFACE and
          SUBNET columns reversed.</para>
        </glossdef>
      </glossentry>

      <glossentry>
        <glossterm>Warning: Zone &lt;zone&gt; is empty</glossterm>

        <glossdef>
          <para>This warning alerts you to the fact tha &lt;zone&gt; is
          defined in <filename>/etc/shorewall/zones</filename> but has no
          corresponding entries in
          <filename>/etc/shorewall/interfaces</filename> or in
          <filename>/etc/shorewall/hosts</filename>.</para>
        </glossdef>
      </glossentry>
    </glosslist>
  </section>

  <section>
    <title>Iptables Error Messages</title>

    <para>By far the most asked about iptables error message is:</para>

    <glosslist>
      <glossentry>
        <glossterm>iptables: No chain/target/match by that name</glossterm>

        <glossdef>
          <para>This almost always means that you are trying to use a
          Shorewall feature that your iptables and/or kernel do not support.
          Beginning with version 2.2.0, Shorewall follows this message with a
          copy of the iptables command that is failing. Most commonly, the
          problem is that one of the match types (keyword following "-m" in
          the command) isn't supported by your iptables/kernel. The output of
          "shorewall check" shows you what your iptables/kernel
          support:</para>

          <programlisting>gateway:~# shorewall check
Loading /usr/share/shorewall/functions...
Processing /etc/shorewall/params ...
Processing /etc/shorewall/shorewall.conf...
Loading Modules...
<emphasis role="bold">Shorewall has detected the following iptables/netfilter capabilities:
   NAT: Available
   Packet Mangling: Available
   Multi-port Match: Available
   Extended Multi-port Match: Available
   Connection Tracking Match: Available
   Packet Type Match: Not available
   Policy Match: Available
   Physdev Match: Available
   IP range Match: Available</emphasis>
Verifying Configuration...

...</programlisting>
        </glossdef>
      </glossentry>
    </glosslist>
  </section>
</article>