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

Signed-off-by: Tom Eastep <teastep@shorewall.net>

docs/starting_and_stopping_shorewall.xml

@@ -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
+    <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
-    latter program will be traced to STDERR.</para>
-
-    <example id="trace">
-      <title>Tracing <command>shorewall start</command></title>
-
-      <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>
-
-      <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>
-
-      <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>Example:</para>
-          <para>The <emphasis role="bold">debug</emphasis> feature is strictly
+
-          for problem analysis. When <emphasis role="bold">debug</emphasis> is
+    <programlisting>shorewall trace check -r</programlisting>
+
+    <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>
 
-          <orderedlist>
+      <itemizedlist>
         <listitem>
           <para>The firewall is made 'wide open' before the rules are
           applied.</para>
         </listitem>
 
         <listitem>
-              <para>The <filename>routestopped</filename> file is not
+          <para>The <filename>stoppedrules</filename> file is not
           consulted.</para>
         </listitem>
 
         <listitem>
-              <para>The rules are applied in the canonical
+          <para>The rules are applied in the canonical ip[6]tables-restore
-              <command>iptables-restore</command> order. So if you need
+          order. So if you need critical hosts to be always available during
-              critical hosts to be always available during start/restart, you
+          start/restart, you may not be able to use debug.</para>
-              may not be able to use <emphasis
-              role="bold">debug</emphasis>.</para>
         </listitem>
-          </orderedlist>
+      </itemizedlist>
-        </warning></para>
+    </warning>
-    </example>
   </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>