Document new 'debug' feature

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@7428 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2007-10-06 16:29:37 +00:00
parent 43f5514390
commit 49bfd9fd5b
3 changed files with 180 additions and 0 deletions

View File

@ -173,6 +173,25 @@
State Diagram</link> section.</para>
</section>
<section id="Init">
<title>/etc/init.d/shorewall and /etc/init.d/shorewall-lite</title>
<para>Because of the different requirements of distribution packaging
systems, the behavior of <filename>/etc/init.d/shorewall</filename> and
<filename>/etc/init.d/shorewall-lite</filename> is not consistent between
distributions. As an example, when using the distributon Shorewall
packages on <trademark>Debian</trademark> and
<trademark>Ubuntu</trademark> systems, running
<command>/etc/init.d/shorewall stop</command> will actually execute the
command <command>/sbin/shorewall clear</command> rather than
<command>/sbin/shorewall stop</command>! So don't expect the meaning of
<emphasis>start</emphasis>, <emphasis>stop</emphasis>,
<emphasis>restart</emphasis>, etc. to be consistent between
<filename>/sbin/shorewall</filename> (or
<filename>/sbin/shorewall-lite</filename>) and your init scripts unless
you got your Shorewall package from shorewall.net.</para>
</section>
<section id="Trace">
<title>Tracing Command Execution</title>
@ -194,6 +213,60 @@
additional diagnostic information to be included in warning and
error messages generated by the compiler.</para>
</note></para>
<para>Beginning with Shorewall 4.0.5, 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>
<para><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></para>
</example>
</section>

View File

@ -155,6 +155,60 @@
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>

View File

@ -162,6 +162,59 @@ gateway:~/test # </programlisting>A look at /var/lib/shorewall/restore at line
include REJECT target support (see <ulink
url="kernel.htm">kernel.htm</ulink>).</para>
<para>f 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>
<para>In other run-time failure cases:<itemizedlist>
<listitem>
<para>Make a note of the error message that you see.</para>