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

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

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

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

    <pubdate>2005-07-19</pubdate>

    <copyright>
      <year>2001-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>

      <important>
        <para>Problem reports that do not include the information requested in
        the <link linkend="Guidelines">Problem Reporting Guidelines</link>
        below <emphasis role="bold">will not be answered by the Shorewall
        author.</emphasis></para>
      </important>
    </legalnotice>
  </articleinfo>

  <section>
    <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 two currently-supported Shorewall <ulink
        url="ReleaseModel.html">major releases</ulink> are 2.4 and 2.2.
        Because of the short time between the releases of 2.2.0 and 2.4.0,
        Shorewall 2.0 will be supported until 1 December 2005 or until the
        release of 2.6.0, whichever comes first.</para>

        <note>
          <para>Shorewall versions earlier than 2.0.0 are no longer supported;
          we will only answer your question if it deals with upgrading from
          these old releases to a current one.</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
        40 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="errata.htm">Errata</ulink> has links to download
        updated components.</para>
      </listitem>

      <listitem>
        <para>The <ulink url="http://shorewall.net/search.html">Search
        facility</ulink> can locate documents and posts about similar
        problems:</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.</para>

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

    <orderedlist>
      <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:</para>

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

          <para>Forward the <filename>/tmp/trace</filename> file as an
          attachment (you may compress it if you like).</para>
        </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 it produces is "Shorewall Started":</para>

        <blockquote>
          <programlisting>…
Activating Rules...
<emphasis role="bold">Shorewall Started</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 show shorewall</command></programlisting>
        </blockquote>

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

        <blockquote>
          <programlisting>Shorewall-2.2.3 Chain shorewall at gateway - Wed Apr 20 14:41:53 PDT 2005

Counters reset Sat Apr 16 17:35:06 PDT 2005

<emphasis role="bold">Chain shorewall (0 references)
 pkts bytes target     prot opt in     out     source               destination</emphasis></programlisting>
        </blockquote>

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

        <blockquote>
          <programlisting>Shorewall-2.2.3 Chain shorewall at gateway - Wed Apr 20 14:43:13 PDT 2005

Counters reset Sat Apr 16 17:35:06 PDT 2005

<emphasis role="bold">iptables: No chain/target/match by that name</emphasis>
</programlisting>
        </blockquote>
      </listitem>

      <listitem>
        <para>If Shorewall is starting successfully and your problem is that
        some set of <emphasis role="bold">connection</emphasis>s 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,
        etc.) then please perform the following four steps:</para>

        <orderedlist>
          <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 status &gt;
            /tmp/status.txt</command></para>
          </listitem>

          <listitem>
            <para>Post the <filename>/tmp/status.txt</filename> file as an
            attachment (you may compress it if you like).</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>

          <listitem>
            <para><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 aren't
            secrets, and concealing them often misleads us and may prevent
            your problem from being looked at all together.</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>Otherwise please include the following information:</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>
        </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. Try to make it easy for us to
        help you. 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 give details about what doesn't work. Reports that say
        <quote>I followed the directions and it didn't work</quote> will
        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 do NOT include the output of <command>iptables
        -L</command> — the output of <emphasis role="bold">shorewall
        show</emphasis> or <command>shorewall status</command> is much more
        useful.</para>
      </listitem>

      <listitem>
        <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 aren't
        secrets, and concealing them often misleads us (and 80% of the time, a
        hacker could derive them anyway from information contained in the SMTP
        headers of your post).</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 along with a copy of your
        /etc/shorewall/interfaces file (and /etc/shorewall/hosts file if you
        have entries in that file).</para>
      </listitem>

      <listitem>
        <para>Please include any of the Shorewall configuration files
        (especially the /etc/shorewall/hosts file if you have modified that
        file) that you think are relevant. If you include
        /etc/shorewall/rules, please include /etc/shorewall/policy as well
        (rules are meaningless unless one also knows the policies).</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">The list server limits posts to 120kb 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 acknowleges that the above list was
        heavily plagiarized from the excellent LEAF document by <emphasis>Ray
        Olszewski</emphasis> found at <ulink
        url="http://leaf-project.org/pub/doc/docmanager/docid_1891.html">http://leaf-project.org/pub/doc/docmanager/docid_1891.html</ulink>.</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>When using the mailing list, please post in plain text</title>

    <para>A growing number of MTAs serving list subscribers are rejecting all
    HTML traffic. At least one MTA has gone so far as to blacklist
    shorewall.net <quote>for continuous abuse</quote> because it has been my
    policy to allow HTML in list posts!!</para>

    <para>I think that blocking all HTML is a Draconian way to control spam
    and that the ultimate losers here are not the spammers but the list
    subscribers whose MTAs are bouncing all shorewall.net mail. As one list
    subscriber wrote to me privately <quote>These e-mail admin's need to get a
    (expletive deleted) life instead of trying to rid the planet of HTML based
    e-mail</quote>. Nevertheless, to allow subscribers to receive list posts
    as must as possible, I have now configured the list server at
    shorewall.net to convert all HTML to plain text. Sometimes the conversion
    process fails in which case, the post sent to the list is empty. Even when
    conversion succeeds, the converted post is difficult to read so all of us
    will appreciate it if you just post in plain text to begin with.</para>
  </section>

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

    <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="ReleaseModel.html">Shorewall
    Release Model page</ulink>) -- please post your question or problem to the
    <ulink url="mailto:shorewall-devel@lists.sourceforge.net">Shorewall
    Development Mailing List</ulink>. <emphasis
    role="bold">IMPORTANT</emphasis>: You must subscribe to the list before
    you will be able to post to it (see link below).</para>

    <para><emphasis role="bold">If you run Shorewall under MandrakeSoft Multi
    Network Firewall (MNF) and you have not purchased an MNF license from
    MandrakeSoft then you can post non MNF-specific Shorewall questions to the
    <ulink url="mailto:shorewall-users@lists.sourceforge.net">Shorewall users
    mailing list</ulink>. Do not expect to get free MNF support on the
    list</emphasis>.</para>

    <para>Otherwise, please post your question or problem to the <ulink
    url="mailto:shorewall-users@lists.sourceforge.net">Shorewall users mailing
    list</ulink>. <emphasis role="bold">IMPORTANT</emphasis>: You must
    subscribe to the list before you will be able to post to it (see link
    below).</para>

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

  <section>
    <title>Subscribing to the Users Mailing List</title>

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

  <section>
    <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>
    <title>Subscribing to the Development Mailing List</title>

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

  <section>
    <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>