forked from extern/shorewall_code
eb34e4cc48
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@7770 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
489 lines
19 KiB
XML
489 lines
19 KiB
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><?dbtimestamp format="Y/m/d"?></pubdate>
|
|
|
|
<copyright>
|
|
<year>2001-2007</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 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 three currently-supported Shorewall <ulink
|
|
url="ReleaseModel.html">major releases</ulink> are 3.2, 3.4 and
|
|
4.0.</para>
|
|
|
|
<note>
|
|
<para>Shorewall versions earlier than 3.2.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 and I 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
|
|
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>
|
|
|
|
<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 2> /tmp/trace</command></programlisting>
|
|
|
|
<para>Forward the <filename>/tmp/trace</filename> file as an
|
|
attachment compressed with gzip or bzip2 (If you are running
|
|
Shorewall-perl, there is no need to compress the file — it will be
|
|
very short).</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>
|
|
|
|
<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 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 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 do not include Shorewall configuration file 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 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 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="ReleaseModel.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>. If you wish to keep the details of your configuration
|
|
private, then you may forward the accompanying dumps/traces etc. to <ulink
|
|
url="mailto:support@shorewall.net">support@shorewall.net</ulink>; the
|
|
report itself should still go to the appropriate mailing list.</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>If you are really dim-witted enough to have to ask -- you
|
|
unsubscribe at the same place that you subscribed. <emphasis
|
|
role="bold">Doh.......</emphasis></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> |