extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-12-19 12:50:57 +01:00
Code Issues Packages Projects Releases Wiki 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"> <section id="Trace">
<title>Tracing Command Execution and other Debugging Aids</title> <title>Tracing Command Execution and other Debugging Aids</title>
<para>If you include the word <emphasis role="bold">trace</emphasis> as <para>Shorewall includes features for tracing and debugging. Commands
the first parameter to an <filename>/sbin/shorewall</filename> command involving the compiler can have the word <emphasis
that transfers control to role="bold">trace</emphasis> inserted immediately after the
<filename>/usr/share/shorewall/firewall</filename>, execution of the command.</para>
latter program will be traced to STDERR.</para>
<example id="trace"> <para>Example:</para>
<title>Tracing <command>shorewall start</command></title>
<para>To trace the execution of <command>shorewall start</command> and <programlisting>shorewall trace check -r</programlisting>
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>
<para>You may also include the word <emphasis <para>This produces a large amount of diagnostic output to standard out
role="bold">debug</emphasis> as the first argument to the during the compilation step. If entered on a command that doesn't invoke
<filename>/sbin/shorewall</filename> and the compiler, <emphasis role="bold">trace</emphasis> is ignored.</para>
<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 <para>Commands that invoke a compiled fireawll script can have the word
<emphasis role="bold">trace</emphasis>. The exceptions are:</para> 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> <itemizedlist>
<listitem> <listitem>
<para><emphasis role="bold">debug</emphasis> is ignored by the <para>The firewall is made 'wide open' before the rules are
Shorewall-perl compiler.</para> applied.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">debug</emphasis> causes altered behavior <para>The <filename>stoppedrules</filename> file is not
of scripts generated by the Shorewall-perl compiler. These scripts consulted.</para>
normally use<command> iptables-restore</command> to install the </listitem>
Netfilter ruleset but with <emphasis role="bold">debug</emphasis>,
the commands normally passed to <command>iptables-restore</command> <listitem>
in its input file are passed individually to <para>The rules are applied in the canonical ip[6]tables-restore
<command>iptables</command>. This is a diagnostic aid which allows order. So if you need critical hosts to be always available during
identifying the individual command that is causing start/restart, you may not be able to use debug.</para>
<command>iptables-restore</command> to fail; it should be used when
iptables-restore fails when executing a <command>COMMIT</command>
command.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</warning>
<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> </section>
<section id="Boot"> <section id="Boot">
@ -629,7 +608,7 @@
<para>The Shorewall State Diagram is depicted below.</para> <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> <informaltable>
<tgroup cols="3"> <tgroup cols="3">
@ -725,7 +704,7 @@
unsuccessful then firewall start (standard configuration) If unsuccessful then firewall start (standard configuration) If
timeout then firewall restart (standard configuration)</entry> timeout then firewall restart (standard configuration)</entry>
<entry></entry> <entry/>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>