holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity

Rewrite the trace/debugging section of the start/stop article

Browse Source 
Signed-off-by: Tom Eastep <teastep@shorewall.net>
This commit is contained in:
Tom Eastep 2015-08-18 16:00:37 -07:00
parent 537f53f611
commit 0e67357d63
1 changed files with 42 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
docs/starting_and_stopping_shorewall.xml
View File

@ -204,78 +204,57 @@
<section id="Trace">
<title>Tracing Command Execution and other Debugging Aids</title>
<para>If you include the word <emphasis role="bold">trace</emphasis> as
the first parameter to an <filename>/sbin/shorewall</filename> command
that transfers control to
<filename>/usr/share/shorewall/firewall</filename>, execution of the
latter program will be traced to STDERR.</para>
<para>Shorewall includes features for tracing and debugging. Commands
involving the compiler can have the word <emphasis
role="bold">trace</emphasis> inserted immediately after the
command.</para>
<example id="trace">
<title>Tracing <command>shorewall start</command></title>
<para>Example:</para>
<para>To trace the execution of <command>shorewall start</command> and
write the trace to the file <filename>/tmp/trace</filename>, you would
enter:<programlisting><command>shorewall trace start 2&gt; /tmp/trace</command></programlisting><note>
<para>The <emphasis role="bold">trace</emphasis> keyword does not
result in a trace of the execution of the Shorewall rules compiler.
It rather causes additional diagnostic information to be included in
warning and error messages generated by the compiler.</para>
</note></para>
<programlisting>shorewall trace check -r</programlisting>
<para>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>
<para>This produces a large amount of diagnostic output to standard out
during the compilation step. If entered on a command that doesn't invoke
the compiler, <emphasis role="bold">trace</emphasis> is ignored.</para>
<para>Commands that invoke a compiled fireawll script can have the word
debug inserted immediately after the command.</para>
<para>Example:</para>
<programlisting>shorewall debug restart</programlisting>
<para><emphasis role="bold">debug</emphasis> causes altered behavior of
scripts generated by the Shorewall compiler. These scripts normally use
ip[6]tables-restore to install the Netfilter ruleset, but with debug, the
commands normally passed to iptables-restore in its input file are passed
individually to ip[6]tables. This is a diagnostic aid which allows
identifying the individual command that is causing ip[6]tables-restore to
fail; it should be used when ip[6]tables-restore fails when executing a
COMMIT command.</para>
<warning>
<para>The debug feature is strictly for problem analysis. When debug is
used:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">debug</emphasis> is ignored by the
Shorewall-perl compiler.</para>
<para>The firewall is made 'wide open' before the rules are
applied.</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>
<para>The <filename>stoppedrules</filename> file is not
consulted.</para>
</listitem>
<listitem>
<para>The rules are applied in the canonical ip[6]tables-restore
order. So if you need critical hosts to be always available during
start/restart, you may not be able to use debug.</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>
</warning>
</section>
<section id="Boot">
@ -629,7 +608,7 @@
<para>The Shorewall State Diagram is depicted below.</para>
<para><graphic align="center" fileref="images/State_Diagram.png" /></para>
<para><graphic align="center" fileref="images/State_Diagram.png"/></para>
<informaltable>
<tgroup cols="3">
@ -725,7 +704,7 @@
unsuccessful then firewall start (standard configuration) If
timeout then firewall restart (standard configuration)</entry>
<entry></entry>
<entry/>
</row>
</tbody>
</tgroup>