<?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><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2001-2006</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>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.</emphasis></para>
</caution>
<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 3.0 and 3.2.</para>
<note>
<para>Shorewall versions earlier than 3.0.0 are no longer supported;
we will try to help but I will personally not spend time reading
earlier code to try to help you solve a problem.</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
50 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>
</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>
<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:</para>
<blockquote>
<programlisting><command>/sbin/shorewall trace start 2> /tmp/trace</command></programlisting>
<para>Forward the <filename>/tmp/trace</filename> file as an
attachment compressed with gzip or bzip2.</para>
<para>If you are running Shorewall version 3.2.0 or later and
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>
</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 3.2 in "done.":</para>
<blockquote>
<para>Shorewall 3.0:</para>
<programlisting>…
Activating Rules...
<emphasis role="bold">Shorewall Started</emphasis>
gateway:~#</programlisting>
<para>Shorewall 3.2:</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-3.0.6 Status at gateway - Thu Mar 30 14:07:29 PDT 2006
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-3.0.6 Status at gateway - Thu Mar 30 14:08:11 PDT 2006
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%23State">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 mysterously
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>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 >
/tmp/status.txt</command></para>
</listitem>
<listitem>
<para>Post the <filename>/tmp/status.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 successfuly 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 give details about what doesn't work. 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 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>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 <emphasis role="bold">DO NOT INCLUDE SHOREWALL
CONFIGURATION FILES</emphasis> unless you have 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 acknowleges 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&PAGE_user_op=view_page&PAGE_id=6&MMN_position=21:21">here</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 HAVEN'T READ THE <link
linkend="Guidelines">PROBLEM REPORTING GUIDELINES</link> ABOVE, PLEASE
READ THEM NOW — IF YOU DON'T SUPPLY THE INFORMATION WE NEED, IT 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="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 MandrivaSoft Multi
Network Firewall (MNF) and you have not purchased an MNF license from
MandrivaSoft 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>Please <emphasis role="bold">read the list usage
instructions</emphasis> (found on the information page for each list)
before posting.</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/lists/listinfo/shorewall-users">https://lists.sourceforge.net/lists/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/lists/listinfo/shorewall-devel">https://lists.sourceforge.net/lists/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>