Update Shorewall5 article for 5.1

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

docs/Shorewall-5.xml

@@ -20,6 +20,8 @@
     <copyright>
       <year>2015</year>
 
+      <year>2016</year>
+
       <holder>Thomas M. Eastep</holder>
     </copyright>
 
@@ -37,8 +39,8 @@
   <section>
     <title>Introduction</title>
 
-    <para>There are currently two principle groups of changes that distinguish
+    <para>There are currently three principle groups of changes that
-    Shorewall 5 from Shorewall 4:</para>
+    distinguish Shorewall 5 from Shorewall 4:</para>
 
     <orderedlist>
       <listitem>
@@ -54,6 +56,13 @@
         commands have been renamed or the function that they perform has been
         changed.</para>
       </listitem>
+
+      <listitem>
+        <para>CLI unification - Beginning with Shorewall 5.1.0, there is a
+        single CLI program (<filename>/sbin/shorewall </filename>or
+        <filename>/usr/sbin/shorewall</filename> depending on your
+        distribution). </para>
+      </listitem>
     </orderedlist>
 
     <para>Each of these groups is described in more detail in the sections
@@ -120,6 +129,10 @@
         <listitem>
           <para>LEGACY_FASTSTART</para>
         </listitem>
+
+        <listitem>
+          <para>CHAIN_SCRIPTS (Removed in Shorewall 5.1).</para>
+        </listitem>
       </itemizedlist>
 
       <para>A compilation warning is issued when any of these options are
@@ -354,6 +367,57 @@
     </section>
   </section>
 
+  <section>
+    <title>CLI Unification</title>
+
+    <para>Prior to Shorewall 5.1, there were four separate CLI
+    programs:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><filename>/sbin/shorewall </filename>or
+        <filename>/usr/sbin/shorewall</filename> depending on your
+        distribution. Packaged with Shorewall and used to control
+        Shorewall.</para>
+      </listitem>
+
+      <listitem>
+        <para><filename>/sbin/shorewall6 </filename>or
+        <filename>/usr/sbin/shorewall6</filename> depending on your
+        distribution. Packaged with Shorewall6 and used to control
+        Shorewall6.</para>
+      </listitem>
+
+      <listitem>
+        <para><filename>/sbin/shorewall-lite </filename>or
+        <filename>/usr/sbin/shorewall-lite</filename> depending on your
+        distribution. Packaged with Shorewall-lite and used to control
+        Shorewall-lite.</para>
+      </listitem>
+
+      <listitem>
+        <para><filename>/sbin/shorewall6-lite </filename>or
+        <filename>/usr/sbin/shorewall6-lite</filename> depending on your
+        distribution. Packaged with Shorewall6-lite and used to control
+        Shorewall6-lite.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Each of these programs had their own (largely duplicated)
+    manpage.</para>
+
+    <para>Beginning with Shorewall 5.1, there is a single CLI program
+    (<filename>/sbin/shorewall</filename> or
+    <filename>/usr/sbin/shorewall</filename>) packaged with Shorewall-core.
+    The Shorewall6, Shorewall-lite and Shorewall6-lite packages create a
+    symbolic link to that program; the links are named shorewall6,
+    shorewall-lite and shorewall6-lite respectively. These symbolic links are
+    for backward compatibility only; all four products can be managed using
+    the single CLI program itself. The manpages shorewall6(8),
+    shorewall-lite(8) and shorewall6-lite(8) are skeletal and refer the reader
+    to shorewall(8).</para>
+  </section>
+
   <section>
     <title>Upgrading to Shorewall 5</title>
 
@@ -380,5 +444,125 @@
     performed unconditionally. The <option>-i </option>and <option>-A
     </option>options have been retained - both enable checking for issues that
     could result if INLINE_MATCHES were to be set to Yes.</para>
+
+    <section>
+      <title id="CHAIN_SCRIPTS">CHAIN_SCRIPTS Removal</title>
+
+      <para>Prior to the availability of ?[BEGIN] PERL .... ?END PERL, the
+      only way to create Perl code to insert rules into a chain was to use a
+      per-Chain script with the same name as the chain. The most common use of
+      these scripts was with Actions where an action A would have an empty
+      action.A file and then a file named A that contained Perl code. This was
+      a hack, at best, and has been deprecated since embedded Perl has been
+      available in action files.</para>
+
+      <para>In Shorewall 5.1, the compiler notices that action.A is empty and
+      looks for a file named A on the CONFIG_PATH. If that file is found, the
+      compiler raises a fatal error:</para>
+
+      <programlisting>    ERROR: File action.A is empty and file A exists - the two must be combined as described in the Migration Considerations section of the Shorewall release notes</programlisting>
+
+      <para>To resolve this issue, one of two approaches can be taken
+      depending on what the script A does.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>If script A is simply inserting rules with ip[6]tables matches
+          and/or targets that Shorewall doesn't directly support, they can
+          probably be coded in the action.A file using the IP[6]TABLES action
+          and/or inline matches. For example, the following script
+          <filename>DNSDDOS</filename></para>
+
+          <programlisting>use Shorewall::Chains;
+
+add_rule $chainref, q(-m string --algo bm --from 30 --to 31 --hex-string "|010000010000000000000000020001|" -j DROP);
+add_rule $chainref, q(-m string --algo bm --from 30 --to 31 --hex-string "|000000010000000000000000020001|" -j DROP);
+add_rule $chainref, q(-j ACCEPT);
+
+1;</programlisting>
+
+          <para>can be coded in <filename>action.DNSDDOS</filename> as:</para>
+
+          <programlisting>DROP    -       -       ;; -m string --algo bm --from 30 --to 31 --hex-string "|010000010000000000000000020001|"
+DROP    -       -       ;; -m string --algo bm --from 30 --to 31 --hex-string "|000000010000000000000000020001|"
+ACCEPT  -       -</programlisting>
+        </listitem>
+
+        <listitem>
+          <para>The other approach is to simply convert A into embedded Perl
+          in action.A. Consider this <filename>SSHKnock</filename>
+          script:</para>
+
+          <programlisting>use Shorewall::Chains;
+
+if ( $level ) {
+    log_rule_limit( $level, 
+                    $chainref, 
+                    'SSHKnock',
+                    'ACCEPT',
+                    '',
+                    $tag,
+                    'add',
+                    '-p tcp --dport 22   -m recent --rcheck --name SSH ' );
+     log_rule_limit( $level,
+                     $chainref,
+                     'SSHKnock',
+                     'DROP',
+                     '',
+                     $tag,
+                     'add',
+                     '-p tcp --dport ! 22 ' );
+}
+add_rule( $chainref, '-p tcp --dport 22   -m recent --rcheck --seconds 60 --name SSH          -j ACCEPT' );
+add_rule( $chainref, '-p tcp --dport 632 -m recent                        --name SSH --remove -j DROP' );
+add_rule( $chainref, '-p tcp --dport 633 -m recent                        --name SSH --set    -j DROP' );
+add_rule( $chainref, '-p tcp --dport 634 -m recent                        --name SSH --remove -j DROP' );
+1;</programlisting>
+
+          <para>Because this script uses the implicit $level and $tag
+          variables, it must remail in Perl. This mostly involves simply
+          moving the <filename>SSHKnock</filename> script into
+          <filename>action.SSHKnock</filename>, but requires some additional
+          code in <filename>action.SSHKnock</filename> as shown in <emphasis
+          role="bold">bold font</emphasis> below:</para>
+
+          <programlisting><emphasis role="bold">?begin perl</emphasis>
+
+<emphasis role="bold">use Shorewall::Config;</emphasis>
+use Shorewall::Chains;
+
+<emphasis role="bold">my $chainref        = get_action_chain;
+my ( $level, $tag ) = get_action_logging;</emphasis>
+
+if ( $level ) {
+    log_rule_limit( $level, 
+                    $chainref, 
+                    'SSHKnock',
+                    'ACCEPT',
+                    '',
+                    $tag,
+                    'add',
+                    '-p tcp --dport 22   -m recent --rcheck --name SSH ' );
+
+    log_rule_limit( $level,
+                    $chainref,
+                    'SSHKnock',
+                    'DROP',
+                    '',
+                    $tag,
+                    'add',
+                    '-p tcp --dport ! 22 ' );
+}
+
+add_rule( $chainref, '-p tcp --dport 22   -m recent --rcheck --seconds 60 --name SSH          -j ACCEPT' );
+add_rule( $chainref, '-p tcp --dport 632 -m recent                        --name SSH --remove -j DROP' );
+add_rule( $chainref, '-p tcp --dport 633 -m recent                        --name SSH --set    -j DROP' );
+add_rule( $chainref, '-p tcp --dport 634 -m recent                        --name SSH --remove -j DROP' );
+1;
+
+<emphasis role="bold">?end perl</emphasis></programlisting>
+        </listitem>
+      </itemizedlist>
+    </section>
   </section>
 </article>