<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Shorewall Support Guide</title><link rel="stylesheet" href="html.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="article" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="IPIP"></a>Shorewall Support Guide</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Tom</span> <span class="surname">Eastep</span></h3></div></div></div><div><p class="copyright">Copyright © 2001-2008 Thomas M. Eastep</p></div><div><div class="legalnotice"><a id="id290337"></a><p>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
“<span class="quote"><a class="ulink" href="GnuCopyright.htm" target="_self">GNU Free Documentation
License</a></span>”.</p></div></div><div><p class="pubdate">2008/12/15</p></div></div><hr /></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#First">Before Reporting a Problem or Asking a Question</a></span></dt><dt><span class="section"><a href="#Guidelines">Problem Reporting Guidelines</a></span></dt><dt><span class="section"><a href="#Where">Where to Send your Problem Report or to Ask for Help</a></span></dt><dt><span class="section"><a href="#Users">Subscribing to the Users Mailing List</a></span></dt><dt><span class="section"><a href="#Announce">Subscribing to the Announce Mailing List</a></span></dt><dt><span class="section"><a href="#Devel">Subscribing to the Development Mailing List</a></span></dt><dt><span class="section"><a href="#Unsubscribe">Unsubscribing from Shorewall Mailing Lists</a></span></dt><dt><span class="section"><a href="#Other">Other Mailing Lists</a></span></dt></dl></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p><span class="bold"><strong>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.</strong></span></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="First"></a>Before Reporting a Problem or Asking a Question</h2></div></div></div><p>There are a number of sources of Shorewall information. Please try
these before you post.</p><div class="itemizedlist"><ul type="disc"><li><p>The two currently-supported Shorewall <a class="ulink" href="ReleaseModel.html" target="_self">major releases</a> are 4.0 and 4.2.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Shorewall versions earlier than 4.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 and I will not
release a patch to correct any defect found.</p></div></li><li><p>More than half of the questions posted on the support list have
answers directly accessible from the <a class="ulink" href="Documentation_Index.html" target="_self">Documentation Index</a></p></li><li><p>The <a class="ulink" href="FAQ.htm" target="_self">FAQ</a> has solutions to more than
50 common problems.</p></li><li><p>The <a class="ulink" href="troubleshoot.htm" target="_self">Troubleshooting
Information</a> contains a number of tips to help you solve common
problems.</p></li><li><p>The <a class="ulink" href="http://dir.gmane.org/gmane.comp.security.shorewall" target="_self">Shorewall
Users Mailing List Archives</a> are a good source of
information.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Guidelines"></a>Problem Reporting Guidelines</h2></div></div></div><p>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.</p><div align="center"><img src="images/Troubleshoot.png" align="middle" /></div><div class="orderedlist"><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p><span class="bold"><strong>Please don't use distribution specific
programs like "service" or init scripts to start/restart Shorewall
while trying to solve a problem</strong></span>, just follow carefully the
instructions below.</p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>As a general matter, <span class="bold"><strong>please do not edit
the diagnostic information</strong></span> in an attempt to conceal your IP
address, netmask, nameserver addresses, domain name, etc. These
<span class="bold"><strong>aren't secrets</strong></span>, 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).</p></div><ol type="1"><li><p>If your problem is that an <span class="bold"><strong>error</strong></span> occurs when you try to
“<span class="quote"><span class="command"><strong>shorewall start</strong></span></span>” or if Shorewall is
otherwise failing to start properly, then please do the
following.</p><div class="blockquote"><blockquote class="blockquote"><p>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:</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"><span class="command"><strong>shorewall -vv [re]start</strong></span></pre></blockquote></div><p>That will give you additional progress messages that may make
it clear which entry in which file is generating the error.</p><p>If that didn't solve your problem, then please</p><pre class="programlisting"><span class="command"><strong>/sbin/shorewall trace start 2> /tmp/trace</strong></span></pre><p>Forward the <code class="filename">/tmp/trace</code> 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).</p><p>If compilation succeeds but the compiled program fails, then
please include the compiled program with your report. The compiled
program will be named <code class="filename">/var/lib/shorewall/.start</code>
if the command is <span class="command"><strong>shorewall start</strong></span> and it will be
named <code class="filename">/var/lib/shorewall/.restart</code> if the
command is <span class="command"><strong>shorewall restart</strong></span>.</p><p>If you are running Shorewall-perl 4.0.5 or later, you may also
include the word <span class="bold"><strong>debug</strong></span> as the first
argument to the <code class="filename">/sbin/shorewall</code> and
<code class="filename">/sbin/shorewall-lite</code> commands.</p><pre class="programlisting"><span class="command"><strong>shorewall debug restart</strong></span></pre><p>In
most cases, <span class="bold"><strong>debug</strong></span> is a synonym for
<span class="bold"><strong>trace</strong></span>. The exceptions are:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="bold"><strong>debug</strong></span> is ignored by the
Shorewall-perl compiler.</p></li><li><p><span class="bold"><strong>debug</strong></span> causes altered
behavior of scripts generated by the Shorewall-perl compiler.
These scripts normally use<span class="command"><strong> iptables-restore</strong></span>
to install the Netfilter ruleset but with <span class="bold"><strong>debug</strong></span>, the commands normally passed to
<span class="command"><strong>iptables-restore</strong></span> in its input file are passed
individually to <span class="command"><strong>iptables</strong></span>. This is a
diagnostic aid which allows identifying the individual command
that is causing <span class="command"><strong>iptables-restore</strong></span> to fail; it
should be used when iptables-restore fails when executing a
<span class="command"><strong>COMMIT</strong></span> command.</p></li></ul></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>The <span class="bold"><strong>debug</strong></span> feature is
strictly for problem analysis. When <span class="bold"><strong>debug</strong></span> is used:</p><div class="orderedlist"><ol type="a"><li><p>The firewall is made 'wide open' before the rules are
applied.</p></li><li><p>The <code class="filename">routestopped</code> file is not
consulted.</p></li><li><p>The rules are applied in the canonical
<span class="command"><strong>iptables-restore</strong></span> order. So if you need
critical hosts to be always available during start/restart,
you may not be able to use <span class="bold"><strong>debug</strong></span>.</p></li></ol></div></div></blockquote></div></li><li><p>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.":</p><div class="blockquote"><blockquote class="blockquote"><p></p><pre class="programlisting">…
Activating Rules...
<span class="bold"><strong>done.</strong></span>
gateway:~#</pre></blockquote></div><p>If you are seeing this message then Shorewall is starting
successfully.</p><p>If you are still unsure if Shorewall is starting or not, enter
the following command:</p><div class="blockquote"><blockquote class="blockquote"><pre class="programlisting"><span class="command"><strong>/sbin/shorewall status</strong></span></pre></blockquote></div><p>If Shorewall has started successfully, you will see output
similar to this:</p><div class="blockquote"><blockquote class="blockquote"><pre class="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)</pre></blockquote></div><p>If Shorewall has not started properly, you will see output
similar to this:</p><div class="blockquote"><blockquote class="blockquote"><pre class="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)</pre></blockquote></div><p>The "State:" refers to the <a class="ulink" href="starting_and_stopping_shorewall.htm#State" target="_self">Shorewall State
Diagram</a>.</p></li><li><p>If Shorewall is starting successfully and your problem is that
some set of <span class="bold"><strong>connections</strong></span> to/from or
through your firewall <span class="bold"><strong>isn't working</strong></span>
(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 <span class="bold"><strong>you are having problems with
traffic shaping</strong></span> then please perform the following six
steps:</p><div class="orderedlist"><ol type="a"><li><p>If Shorewall isn't started then <span class="command"><strong>/sbin/shorewall
start</strong></span>. Otherwise <span class="command"><strong>/sbin/shorewall
reset</strong></span>.</p></li><li><p>Try making the connection that is failing.</p></li><li><p><span class="command"><strong>/sbin/shorewall dump >
/tmp/status.txt</strong></span></p></li><li><p>Post the <code class="filename">/tmp/status.txt</code> file as an
attachment compressed with gzip or bzip2.</p></li><li><p>Describe where you are trying to make the connection from
(IP address) and what host (IP address) you are trying to connect
to.</p></li></ol></div></li><li><p>Otherwise:</p><p>Shorewall is starting successfully and you have <span class="bold"><strong>no connection problems</strong></span> and you have <span class="bold"><strong>no traffic shaping problems</strong></span>. Your problem is
with performance, logging, etc. Please include the following:</p><div class="itemizedlist"><ul type="disc"><li><p>the exact version of Shorewall you are running.</p><pre class="programlisting"><span class="bold"><strong>/sbin/shorewall version</strong></span></pre></li><li><p>the complete exact output of</p><pre class="programlisting"><span class="command"><strong>ip addr show</strong></span></pre></li><li><p>the complete exact output of</p><pre class="programlisting"><span class="command"><strong>ip route show</strong></span></pre></li><li><p>A detailed description of your problem.</p></li></ul></div></li></ol></div><div class="itemizedlist"><ul type="disc"><li><p>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.</p></li><li><p>Please keep in mind that you're asking for <span class="bold"><strong>free</strong></span> technical support. Any help we offer is an
act of generosity, not an obligation. <span class="bold"><strong>Try to
make it easy for us to help you</strong></span>. 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.</p></li><li><p>Please <span class="bold"><strong>give details about what doesn't
work</strong></span>. Reports that say “<span class="quote">I followed the directions and
it didn't work</span>” 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 “<span class="quote">ping</span>” problems). If
Computer B doesn't show up in “<span class="quote">Network Neighborhood</span>” then
say so. If access by IP address works but by DNS names it doesn't then
say so.</p></li><li><p>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.</p></li><li><p>Please <span class="bold"><strong>do NOT include the output
of</strong></span> <span class="command"><strong>iptables -L</strong></span> — the output of <span class="bold"><strong>shorewall show</strong></span> or <span class="command"><strong>shorewall
dump</strong></span> is much more useful to us.</p></li><li><p>Do you see any “<span class="quote">Shorewall</span>” messages
(“<span class="quote"><span class="command"><strong>/sbin/shorewall show log</strong></span></span>”) when you
exercise the function that is giving you problems? If so, include the
message(s) in your post.</p></li><li><p>Please <span class="bold"><strong>do not include Shorewall
configuration files</strong></span> unless you have been specifically asked
to do so. The output of <span class="command"><strong>shorewall dump</strong></span> collected as
described above is much more useful.</p></li><li><p><span class="bold"><strong>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</strong></span>.</p></li><li><p>The author gratefully acknowledges that the above list was
heavily plagiarized from the excellent LEAF document by <span class="emphasis"><em>Ray
Olszewski</em></span> found <a class="ulink" href="http://leaf-project.org/index.php?module=pagemaster&PAGE_user_op=view_page&PAGE_id=6&MMN_position=21:21" target="_self">here</a>.</p></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Where"></a>Where to Send your Problem Report or to Ask for Help</h2></div></div></div><p><span class="bold"><strong>If you haven't read the <a class="link" href="#Guidelines" title="Problem Reporting Guidelines">Problem Reporting Guidelines</a> above, please
read them now — Failure to supply the information that we need will just
delay a solution to your problem.</strong></span></p><p><span class="bold"><strong>If you run the current development release and
your question involves a feature that is only available in the development
release</strong></span> (see the <a class="ulink" href="ReleaseModel.html" target="_self">Shorewall
Release Model page</a>) then please post your question or problem to
the <a class="ulink" href="mailto:shorewall-devel@lists.sourceforge.net" target="_self">Shorewall
Development Mailing List</a>.</p><p>Otherwise, please post your question or problem report to the <a class="ulink" href="mailto:shorewall-users@lists.sourceforge.net" target="_self">Shorewall users mailing
list</a>. If you wish to keep the details of your configuration
private, then you may forward the accompanying dumps/traces etc. to <a class="ulink" href="mailto:support@shorewall.net" target="_self">support@shorewall.net</a>; the
report itself should still go to the appropriate mailing list.</p><p><span class="bold"><strong>IMPORTANT</strong></span>: You must subscribe to
the mailing lists before you will be able to post to them (see links
below).</p><p>For <span class="bold"><strong>quick questions</strong></span>, there is also
a #shorewall channel at irc.freenode.net.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Users"></a>Subscribing to the Users Mailing List</h2></div></div></div><p>To Subscribe to the users mailing list go to <a class="ulink" href="https://lists.sourceforge.net/lists/listinfo/shorewall-users" target="_self">https://lists.sourceforge.net/lists/listinfo/shorewall-users</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Announce"></a>Subscribing to the Announce Mailing List</h2></div></div></div><p>To Subscribe to the announce mailing list (low-traffic,read only) go
to:</p><p><a class="ulink" href="https://lists.sourceforge.net/lists/listinfo/shorewall-announce" target="_self">https://lists.sourceforge.net/lists/listinfo/shorewall-announce</a></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Devel"></a>Subscribing to the Development Mailing List</h2></div></div></div><p>To Subscribe to the development mailing list go to <a class="ulink" href="https://lists.sourceforge.net/lists/listinfo/shorewall-devel" target="_self">https://lists.sourceforge.net/lists/listinfo/shorewall-devel</a>.</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Unsubscribe"></a>Unsubscribing from Shorewall Mailing Lists</h2></div></div></div><p>If you are really dim-witted enough to have to ask -- you
unsubscribe at the same place that you subscribed. <span class="bold"><strong>Doh.......</strong></span></p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="Other"></a>Other Mailing Lists</h2></div></div></div><p>For information on other Shorewall mailing lists, go to <a class="ulink" href="http://sourceforge.net/mail/?group_id=22587" target="_self">http://sourceforge.net/mail/?group_id=22587</a>
.</p></div></div></body></html>
