Document new 'debug' feature

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@7428 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb

docs/starting_and_stopping_shorewall.xml

@@ -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>
 

docs/support.xml

@@ -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>
 

docs/troubleshoot.xml

@@ -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>