shorewall_code/docs/support.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="IPIP">
  <!--$Id$-->

  <articleinfo>
    <title>Shorewall Support Guide</title>

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

    <copyright>
      <year>2001-2011</year>

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

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

  <caution>
    <para><emphasis role="bold">This article applies to Shorewall 4.0 and
    later. If you are running a version of Shorewall earlier than Shorewall
    4.0.0 then please see the documentation for that
    release.</emphasis></para>
  </caution>

  <section id="First">
    <title>Before Reporting a Problem or Asking a Question</title>

    <para>There are a number of sources of Shorewall information. Please try
    these before you post.</para>

    <itemizedlist>
      <listitem>
        <para>The currently-supported Shorewall <ulink
        url="ReleaseModel.html">major release</ulink>s are , 5.1 and 5.2.</para>

        <note>
          <para>Shorewall versions earlier than 5.1.0 are no longer supported;
          we will try to help but we will not spend time reading earlier code
          to try to help you solve a problem and we will not release a patch
          to correct any defect found.</para>
        </note>
      </listitem>

      <listitem>
        <para>More than half of the questions posted on the support list have
        answers directly accessible from the <ulink
        url="Documentation_Index.html">Documentation Index</ulink></para>
      </listitem>

      <listitem>
        <para>The <ulink url="FAQ.htm">FAQ</ulink> has solutions to more than
        100 common problems.</para>
      </listitem>

      <listitem>
        <para>The <ulink url="troubleshoot.htm">Troubleshooting
        Information</ulink> contains a number of tips to help you solve common
        problems.</para>
      </listitem>

      <listitem>
        <para>The <ulink
        url="http://dir.gmane.org/gmane.comp.security.shorewall">Shorewall
        Users Mailing List Archives</ulink> are a good source of
        information.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Guidelines">
    <title>Problem Reporting Guidelines</title>

    <para>Please refer to the following flowchart to guide you through the
    problem reporting process. It will ensure that you provide us with the
    information we need to solve your problem as quickly as possible.</para>

    <graphic align="center" fileref="images/Troubleshoot.png"/>

    <orderedlist>
      <important>
        <para><emphasis role="bold">Please don't use distribution specific
        programs like "service" or init scripts to start/restart Shorewall
        while trying to solve a problem</emphasis>, just follow carefully the
        instructions below.</para>
      </important>

      <important>
        <para>As a general matter, <emphasis role="bold">please do not edit
        the diagnostic information</emphasis> in an attempt to conceal your IP
        address, netmask, nameserver addresses, domain name, etc. These
        <emphasis role="bold">aren't secrets</emphasis>, and concealing them
        often misleads us (and 80% of the time, a cracker could derive them
        anyway from information contained in the SMTP headers of your
        post).</para>
      </important>

      <listitem>
        <para>If your problem is that an <emphasis
        role="bold">error</emphasis> occurs when you try to
        <quote><command>shorewall start</command></quote> or if Shorewall is
        otherwise failing to start properly, then please do the
        following.</para>

        <blockquote>
          <para>If your VERBOSITY setting in shorewall.conf is less than 2 and
          you are running the Shorewall-shell compiler, then try running with
          a higher verbosity level by using the "-vv" option:</para>

          <blockquote>
            <programlisting><command>shorewall -vv [re]start</command></programlisting>
          </blockquote>

          <para>That will give you additional progress messages that may make
          it clear which entry in which file is generating the error.</para>

          <para>If that didn't solve your problem, then please</para>

          <programlisting><command>/sbin/shorewall trace start &gt; /tmp/trace 2&gt;&amp;1</command></programlisting>

          <para>Forward the <filename>/tmp/trace</filename> file as an
          attachment compressed with gzip or bzip2.</para>

          <para>If compilation succeeds but the compiled program fails, then
          please include the compiled program with your report. The compiled
          program will be named <filename>/var/lib/shorewall/.start</filename>
          if the command is <command>shorewall start</command> and it will be
          named <filename>/var/lib/shorewall/.restart</filename> if the
          command is <command>shorewall restart</command>.</para>

          <para>If you are running Shorewall-perl 4.0.5 or later, you may also
          include the word <emphasis role="bold">debug</emphasis> as the first
          argument to the <filename>/sbin/shorewall</filename> and
          <filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In
          most cases, <emphasis role="bold">debug</emphasis> is a synonym for
          <emphasis role="bold">trace</emphasis>. The exceptions are:</para>

          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">debug</emphasis> is ignored by the
              Shorewall-perl compiler.</para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">debug</emphasis> causes altered
              behavior of scripts generated by the Shorewall-perl compiler.
              These scripts normally use<command> iptables-restore</command>
              to install the Netfilter ruleset but with <emphasis
              role="bold">debug</emphasis>, the commands normally passed to
              <command>iptables-restore</command> in its input file are passed
              individually to <command>iptables</command>. This is a
              diagnostic aid which allows identifying the individual command
              that is causing <command>iptables-restore</command> to fail; it
              should be used when iptables-restore fails when executing a
              <command>COMMIT</command> command.</para>
            </listitem>
          </itemizedlist>

          <warning>
            <para>The <emphasis role="bold">debug</emphasis> feature is
            strictly for problem analysis. When <emphasis
            role="bold">debug</emphasis> is used:</para>

            <orderedlist>
              <listitem>
                <para>The firewall is made 'wide open' before the rules are
                applied.</para>
              </listitem>

              <listitem>
                <para>The <filename>routestopped</filename> file is not
                consulted.</para>
              </listitem>

              <listitem>
                <para>The rules are applied in the canonical
                <command>iptables-restore</command> order. So if you need
                critical hosts to be always available during start/restart,
                you may not be able to use <emphasis
                role="bold">debug</emphasis>.</para>
              </listitem>
            </orderedlist>
          </warning>
        </blockquote>
      </listitem>

      <listitem>
        <para>If you are unsure if Shorewall is starting successfully or not
        then first note that if Shorewall starts successfully, the last
        message produced by Shorewall 3.0 is "Shorewall Started" and the last
        message produced by Shorewall is "done.":</para>

        <blockquote>
          <para/>

          <programlisting>…
Activating Rules...
<emphasis role="bold">done.</emphasis>
gateway:~#</programlisting>
        </blockquote>

        <para>If you are seeing this message then Shorewall is starting
        successfully.</para>

        <para>If you are still unsure if Shorewall is starting or not, enter
        the following command:</para>

        <blockquote>
          <programlisting><command>/sbin/shorewall status</command></programlisting>
        </blockquote>

        <para>If Shorewall has started successfully, you will see output
        similar to this:</para>

        <blockquote>
          <programlisting>Shorewall-4.0.6 Status at gateway - Thu Mar 30 14:07:29 PDT 2008

Shorewall is running
State:Started (Thu Mar 30 14:07:29 PDT 2006)</programlisting>
        </blockquote>

        <para>If Shorewall has not started properly, you will see output
        similar to this:</para>

        <blockquote>
          <programlisting>Shorewall-4.0.6 Status at gateway - Thu Mar 30 14:08:11 PDT 2008

Shorewall is stopped
State:Stopped (Thu Mar 30 14:08:11 PDT 2006)</programlisting>
        </blockquote>

        <para>The "State:" refers to the <ulink
        url="starting_and_stopping_shorewall.htm#State">Shorewall State
        Diagram</ulink>.</para>
      </listitem>

      <listitem>
        <para>If Shorewall is starting successfully and your problem is that
        some set of <emphasis role="bold">connections</emphasis> to/from or
        through your firewall <emphasis role="bold">isn't working</emphasis>
        (examples: local systems can't access the Internet, you can't send
        email through the firewall, you can't surf the web from the firewall,
        connections that you are certain should be rejected are mysteriously
        accepted, etc.) or <emphasis role="bold">you are having problems with
        traffic shaping</emphasis> then please perform the following six
        steps:</para>

        <orderedlist>
          <listitem>
            <para>Be sure that the LOGFILE setting in<filename>
            /etc/shorewall/shorewall.conf</filename> is correct (that it names
            the file where 'Shorewall' messages are being logged). See <ulink
            url="manpages/shorewall.conf.html">shorewall.conf </ulink>(5) and
            the <ulink url="shorewall_logging.html">Shorewall Logging
            Article</ulink>.</para>
          </listitem>

          <listitem>
            <para>If you are running <emphasis role="bold">Ubuntu Precise with
            Shorewall 4.4.26.1</emphasis>, then please edit
            <filename>/sbin/shorewall</filename> and change the first line
            to:</para>

            <simplelist>
              <member>#!/bin/bash</member>
            </simplelist>
          </listitem>

          <listitem>
            <para>If your problem has anything to do with IPsec, be sure that
            the ipsec-tools package is installed.</para>
          </listitem>

          <listitem>
            <para>If Shorewall isn't started then <command>/sbin/shorewall
            start</command>. Otherwise <command>/sbin/shorewall
            reset</command>.</para>
          </listitem>

          <listitem>
            <para>Try making the connection that is failing.</para>
          </listitem>

          <listitem>
            <para><command>/sbin/shorewall dump &gt;
            /tmp/shorewall_dump.txt</command></para>
          </listitem>

          <listitem>
            <para>Post the <filename>/tmp/shorewall_dump.txt</filename> file
            as an attachment compressed with gzip or bzip2.</para>
          </listitem>

          <listitem>
            <para>Describe where you are trying to make the connection from
            (IP address) and what host (IP address) you are trying to connect
            to.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Otherwise:</para>

        <para>Shorewall is starting successfully and you have <emphasis
        role="bold">no connection problems</emphasis> and you have <emphasis
        role="bold">no traffic shaping problems</emphasis>. Your problem is
        with performance, logging, etc. Please include the following:</para>

        <itemizedlist>
          <listitem>
            <para>the exact version of Shorewall you are running.</para>

            <programlisting><emphasis role="bold">/sbin/shorewall version</emphasis></programlisting>
          </listitem>

          <listitem>
            <para>the complete exact output of</para>

            <programlisting><command>ip addr show</command></programlisting>
          </listitem>

          <listitem>
            <para>the complete exact output of</para>

            <programlisting><command>ip route show</command></programlisting>
          </listitem>

          <listitem>
            <para>A detailed description of your problem.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </orderedlist>

    <itemizedlist>
      <listitem>
        <para>Please remember we only know what is posted in your message. Do
        not leave out any information that appears to be correct, or was
        mentioned in a previous post. There have been countless posts by
        people who were sure that some part of their configuration was correct
        when it actually contained a small error. We tend to be skeptics where
        detail is lacking.</para>
      </listitem>

      <listitem>
        <para>Please keep in mind that you're asking for <emphasis
        role="bold">free</emphasis> technical support. Any help we offer is an
        act of generosity, not an obligation. <emphasis role="bold">Try to
        make it easy for us to help you</emphasis>. Follow good, courteous
        practices in writing and formatting your e-mail. Provide details that
        we need if you expect good answers. Exact quoting of error messages,
        log entries, command output, and other output is better than a
        paraphrase or summary.</para>
      </listitem>

      <listitem>
        <para>Please <emphasis role="bold">give details about what doesn't
        work</emphasis>. Reports that say <quote>I followed the directions and
        it didn't work</quote> may elicit sympathy but probably little in the
        way of help. Again -- if ping from A to B fails, say so (and see below
        for information about reporting <quote>ping</quote> problems). If
        Computer B doesn't show up in <quote>Network Neighborhood</quote> then
        say so. If access by IP address works but by DNS names it doesn't then
        say so.</para>
      </listitem>

      <listitem>
        <para>Please don't describe your environment and then ask us to send
        you custom configuration files. We're here to answer your questions
        but we can't do your job for you.</para>
      </listitem>

      <listitem>
        <para>Please <emphasis role="bold">do NOT include the output
        of</emphasis> <command>iptables -L</command> — the output of <emphasis
        role="bold">shorewall show</emphasis> or <command>shorewall
        dump</command> is much more useful to us.</para>
      </listitem>

      <listitem>
        <para>Do you see any <quote>Shorewall</quote> messages
        (<quote><command>/sbin/shorewall show log</command></quote>) when you
        exercise the function that is giving you problems? If so, include the
        message(s) in your post.</para>
      </listitem>

      <listitem>
        <para>Please <emphasis role="bold">do not include Shorewall
        configuration files</emphasis> unless you have been specifically asked
        to do so. The output of <command>shorewall dump</command> collected as
        described above is much more useful.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">The list server limits the size of posts
        to the lists, so don't post graphics of your network layout, etc. to
        the Mailing List -- your post will be rejected</emphasis>.</para>
      </listitem>

      <listitem>
        <para>The author gratefully acknowledges that the above list was
        heavily plagiarized from the excellent LEAF document by <emphasis>Ray
        Olszewski</emphasis> found <ulink
        url="http://leaf-project.org/index.php?module=pagemaster&amp;PAGE_user_op=view_page&amp;PAGE_id=6&amp;MMN_position=21:21">here</ulink>.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Where">
    <title>Where to Send your Problem Report or to Ask for Help</title>

    <para><emphasis role="bold">If you haven't read the <link
    linkend="Guidelines">Problem Reporting Guidelines</link> above, please
    read them now — Failure to supply the information that we need will just
    delay a solution to your problem.</emphasis></para>

    <para><emphasis role="bold">If you run the current development release and
    your question involves a feature that is only available in the development
    release</emphasis> (see the <ulink url="NewRelease.html">Shorewall Release
    Model page</ulink>) then please post your question or problem to the
    <ulink url="mailto:shorewall-devel@lists.sourceforge.net">Shorewall
    Development Mailing List</ulink>.</para>

    <para>Otherwise, please post your question or problem report to the <ulink
    url="mailto:shorewall-users@lists.sourceforge.net">Shorewall users mailing
    list</ulink>.</para>

    <para><emphasis role="bold">IMPORTANT</emphasis>: You must subscribe to
    the mailing lists before you will be able to post to them (see links
    below).</para>

    <para>For <emphasis role="bold">quick questions</emphasis>, there is also
    a #shorewall channel at irc.freenode.net.</para>
  </section>

  <section id="Users">
    <title>Subscribing to the Users Mailing List</title>

    <para>To Subscribe to the users mailing list go to <ulink
    url="https://lists.sourceforge.net/lists/listinfo/shorewall-users">https://lists.sourceforge.net/lists/listinfo/shorewall-users</ulink>.</para>
  </section>

  <section id="Announce">
    <title>Subscribing to the Announce Mailing List</title>

    <para>To Subscribe to the announce mailing list (low-traffic,read only) go
    to:</para>

    <para><ulink
    url="https://lists.sourceforge.net/lists/listinfo/shorewall-announce">https://lists.sourceforge.net/lists/listinfo/shorewall-announce</ulink></para>
  </section>

  <section id="Devel">
    <title>Subscribing to the Development Mailing List</title>

    <para>To Subscribe to the development mailing list go to <ulink
    url="https://lists.sourceforge.net/lists/listinfo/shorewall-devel">https://lists.sourceforge.net/lists/listinfo/shorewall-devel</ulink>.</para>
  </section>

  <section id="Unsubscribe">
    <title>Unsubscribing from Shorewall Mailing Lists</title>

    <para>See <ulink url="FAQ.htm#faq98">Shorewall FAQ 98</ulink>.</para>
  </section>

  <section id="Other">
    <title>Other Mailing Lists</title>

    <para>For information on other Shorewall mailing lists, go to <ulink
    url="http://sourceforge.net/mail/?group_id=22587">http://sourceforge.net/mail/?group_id=22587</ulink>
    .</para>
  </section>
</article>