Add example to Manual Chains document

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

docs/Documentation_Index.xml

@@ -54,23 +54,13 @@
     <informaltable frame="none">
       <tgroup align="left" cols="3">
         <tbody>
-          <row>
-            <entry></entry>
-
-            <entry><ulink url="PortKnocking.html#Limit">Limiting per-IPaddress
-            Connection Rate</ulink></entry>
-
-            <entry><ulink url="ScalabilityAndPerformance.html">Scalability and
-            Performance</ulink></entry>
-          </row>
-
           <row>
             <entry><ulink url="Accounting.html">Accounting</ulink></entry>
 
             <entry><ulink url="shorewall_logging.html">Logging</ulink></entry>
 
-            <entry><ulink url="CompiledPrograms.html#Lite">Shorewall
+            <entry><ulink url="ScalabilityAndPerformance.html">Scalability and
-            Lite</ulink></entry>
+            Performance</ulink></entry>
           </row>
 
           <row>
@@ -78,8 +68,8 @@
 
             <entry><ulink url="Macros.html">Macros</ulink></entry>
 
-            <entry><ulink url="Modularization.html">Shorewall
+            <entry><ulink url="CompiledPrograms.html#Lite">Shorewall
-            Modularization</ulink></entry>
+            Lite</ulink></entry>
           </row>
 
           <row>
@@ -89,8 +79,8 @@
             <entry><ulink url="MAC_Validation.html">MAC
             Verification</ulink></entry>
 
-            <entry><ulink url="Shorewall-4.html">Shorewall 4.x</ulink> --
+            <entry><ulink url="Modularization.html">Shorewall
-            What's new</entry>
+            Modularization</ulink></entry>
           </row>
 
           <row>
@@ -99,14 +89,26 @@
 
             <entry><ulink url="Manpages.html">Man Pages</ulink></entry>
 
-            <entry><ulink url="Shorewall-perl.html">Shorewall
+            <entry><ulink url="Shorewall-4.html">Shorewall 4.x</ulink> --
-            Perl</ulink></entry>
+            What's new</entry>
           </row>
 
           <row>
             <entry><ulink url="traffic_shaping.htm">Bandwidth Control</ulink>
             (<ulink url="traffic_shaping_ru.html">Russian</ulink>)</entry>
 
+            <entry><ulink url="ManualChains.html">Manual
+            Chains</ulink></entry>
+
+            <entry><ulink url="Shorewall-perl.html">Shorewall
+            Perl</ulink></entry>
+          </row>
+
+          <row>
+            <entry><ulink url="blacklisting_support.htm">Blacklisting</ulink>
+            (<ulink
+            url="blacklisting_support_ru.html">Russian</ulink>)</entry>
+
             <entry><ulink
             url="two-interface.htm#SNAT">Masquerading</ulink></entry>
 
@@ -115,9 +117,8 @@
           </row>
 
           <row>
-            <entry><ulink url="blacklisting_support.htm">Blacklisting</ulink>
+            <entry>Bridge: <ulink
-            (<ulink
+            url="bridge-Shorewall-perl.html">Shorewall-perl</ulink></entry>
-            url="blacklisting_support_ru.html">Russian</ulink>)</entry>
 
             <entry><ulink url="MultiISP.html">Multiple Internet Connections
             from a Single Firewall</ulink> (<ulink
@@ -127,8 +128,8 @@
           </row>
 
           <row>
-            <entry>Bridge: <ulink
+            <entry>Bridge: <ulink url="SimpleBridge.html">No control of
-            url="bridge-Shorewall-perl.html">Shorewall-perl</ulink></entry>
+            traffic through the bridge</ulink></entry>
 
             <entry><ulink url="Multiple_Zones.html">Multiple Zones Through One
             Interface</ulink></entry>
@@ -139,8 +140,7 @@
           </row>
 
           <row>
-            <entry>Bridge: <ulink url="SimpleBridge.html">No control of
+            <entry>Commands</entry>
-            traffic through the bridge</ulink></entry>
 
             <entry><ulink url="XenMyWay-Routed.html">My Shorewall
             Configuration</ulink></entry>
@@ -150,8 +150,8 @@
           </row>
 
           <row>
-            <entry><ulink
+            <entry><ulink url="starting_and_stopping_shorewall.htm">Compiled
-            url="starting_and_stopping_shorewall.htm">Commands</ulink></entry>
+            Firewall Programs</ulink></entry>
 
             <entry><ulink url="NetfilterOverview.html">Netfilter
             Overview</ulink></entry>
@@ -162,8 +162,8 @@
           </row>
 
           <row>
-            <entry><ulink url="CompiledPrograms.html">Compiled Firewall
+            <entry><ulink url="CompiledPrograms.html">Configuration File
-            Programs</ulink></entry>
+            Basics</ulink></entry>
 
             <entry><ulink url="netmap.html">Network Mapping</ulink></entry>
 
@@ -172,8 +172,8 @@
           </row>
 
           <row>
-            <entry><ulink url="configuration_file_basics.htm">Configuration
+            <entry><ulink
-            File Basics</ulink></entry>
+            url="configuration_file_basics.htm">DHCP</ulink></entry>
 
             <entry><ulink url="NAT.htm">One-to-one NAT</ulink> (Static
             NAT)</entry>
@@ -182,7 +182,9 @@
           </row>
 
           <row>
-            <entry><ulink url="dhcp.htm">DHCP</ulink></entry>
+            <entry><ulink url="dhcp.htm"><ulink
+            url="two-interface.htm#DNAT">DNAT</ulink> (<firstterm>Destination
+            Network Address Translation</firstterm>)</ulink></entry>
 
             <entry><ulink url="Multiple_Zones.html"><ulink
             url="OPENVPN.html">OpenVPN</ulink></ulink></entry>
@@ -192,9 +194,7 @@
           </row>
 
           <row>
-            <entry><ulink url="two-interface.htm#DNAT">DNAT</ulink>
+            <entry>ECN Disabling by host or subnet</entry>
-            (<firstterm>Destination Network Address
-            Translation</firstterm>)</entry>
 
             <entry><ulink url="starting_and_stopping_shorewall.htm">Operating
             Shorewall</ulink></entry>
@@ -205,8 +205,9 @@
           </row>
 
           <row>
-            <entry><ulink url="ECN.html">ECN Disabling by host or
+            <entry><ulink url="ECN.html"><ulink
-            subnet</ulink></entry>
+            url="shorewall_extension_scripts.htm">Extension Scripts</ulink>
+            (User Exits)</ulink></entry>
 
             <entry><ulink url="PacketMarking.html">Packet
             Marking</ulink></entry>
@@ -215,8 +216,8 @@
           </row>
 
           <row>
-            <entry><ulink url="shorewall_extension_scripts.htm">Extension
+            <entry><ulink
-            Scripts</ulink> (User Exits)</entry>
+            url="fallback.htm">Fallback/Uninstall</ulink></entry>
 
             <entry><ulink url="PacketHandling.html">Packet Processing in a
             Shorewall-based Firewall</ulink></entry>
@@ -226,8 +227,7 @@
           </row>
 
           <row>
-            <entry><ulink
+            <entry><ulink url="FAQ.htm">FAQs</ulink></entry>
-            url="fallback.htm">Fallback/Uninstall</ulink></entry>
 
             <entry><ulink url="ping.html">'Ping' Management</ulink></entry>
 
@@ -235,7 +235,8 @@
           </row>
 
           <row>
-            <entry><ulink url="FAQ.htm">FAQs</ulink></entry>
+            <entry><ulink
+            url="shorewall_features.htm">Features</ulink></entry>
 
             <entry><ulink url="two-interface.htm#DNAT">Port
             Forwarding</ulink></entry>
@@ -244,8 +245,8 @@
           </row>
 
           <row>
-            <entry><ulink
+            <entry><ulink url="Multiple_Zones.html">Forwarding Traffic on the
-            url="shorewall_features.htm">Features</ulink></entry>
+            Same Interface</ulink></entry>
 
             <entry><ulink url="ports.htm">Port Information</ulink></entry>
 
@@ -254,8 +255,7 @@
           </row>
 
           <row>
-            <entry><ulink url="Multiple_Zones.html">Forwarding Traffic on the
+            <entry><ulink url="FTP.html">FTP and Shorewall</ulink></entry>
-            Same Interface</ulink></entry>
 
             <entry><ulink url="PortKnocking.html">Port Knocking and Other Uses
             of the 'Recent Match'</ulink></entry>
@@ -265,7 +265,8 @@
           </row>
 
           <row>
-            <entry><ulink url="FTP.html">FTP and Shorewall</ulink></entry>
+            <entry><ulink url="support.htm">Getting help or answers to
+            questions</ulink></entry>
 
             <entry><ulink url="PPTP.htm">PPTP</ulink></entry>
 
@@ -274,8 +275,8 @@
           </row>
 
           <row>
-            <entry><ulink url="support.htm">Getting help or answers to
+            <entry><ulink url="Install.htm">Installation/Upgrade</ulink>
-            questions</ulink></entry>
+            (<ulink url="Install_fr.html">Français</ulink>)</entry>
 
             <entry><ulink url="ProxyARP.htm">Proxy ARP</ulink></entry>
 
@@ -283,8 +284,7 @@
           </row>
 
           <row>
-            <entry><ulink url="Install.htm">Installation/Upgrade</ulink>
+            <entry><ulink url="IPP2P.html">IPP2P</ulink></entry>
-            (<ulink url="Install_fr.html">Français</ulink>)</entry>
 
             <entry><ulink url="shorewall_quickstart_guide.htm">QuickStart
             Guides</ulink></entry>
@@ -293,7 +293,8 @@
           </row>
 
           <row>
-            <entry><ulink url="IPP2P.html">IPP2P</ulink></entry>
+            <entry><ulink url="IPSEC-2.6.html">IPSEC using Kernel 2.6 and
+            Shorewall 2.1 or Later</ulink></entry>
 
             <entry><ulink url="ReleaseModel.html">Release
             Model</ulink></entry>
@@ -302,8 +303,7 @@
           </row>
 
           <row>
-            <entry><ulink url="IPSEC-2.6.html">IPSEC using Kernel 2.6 and
+            <entry><ulink url="ipsets.html">Ipsets</ulink></entry>
-            Shorewall 2.1 or Later</ulink></entry>
 
             <entry><ulink
             url="shorewall_prerequisites.htm">Requirements</ulink></entry>
@@ -312,7 +312,8 @@
           </row>
 
           <row>
-            <entry><ulink url="ipsets.html">Ipsets</ulink></entry>
+            <entry><ulink url="Shorewall_and_Kazaa.html">Kazaa
+            Filtering</ulink></entry>
 
             <entry><ulink url="Shorewall_and_Routing.html">Routing and
             Shorewall</ulink></entry>
@@ -321,8 +322,8 @@
           </row>
 
           <row>
-            <entry><ulink url="Shorewall_and_Kazaa.html">Kazaa
+            <entry><ulink url="kernel.htm">Kernel
-            Filtering</ulink></entry>
+            Configuration</ulink></entry>
 
             <entry><ulink url="Multiple_Zones.html">Routing on One
             Interface</ulink></entry>
@@ -331,8 +332,8 @@
           </row>
 
           <row>
-            <entry><ulink url="kernel.htm">Kernel
+            <entry><ulink url="PortKnocking.html#Limit">Limiting per-IPaddress
-            Configuration</ulink></entry>
+            Connection Rate</ulink></entry>
 
             <entry><ulink url="samba.htm">Samba</ulink></entry>
 

docs/ManualChains.xml

@@ -34,13 +34,13 @@
     </legalnotice>
   </articleinfo>
 
-  <section>
+  <section id="Intro">
     <title>Introduction</title>
 
     <para>Manual chains were introduced in Shorewall-perl 4.0.6; for Perl
     programmers, manual chains provide an alternative to Actions with
     extension scripts. Manual chains are chains which you create and populate
-    yourself using the low-level functions in Shorewall::Chains. </para>
+    yourself using the low-level functions in Shorewall::Chains.</para>
 
     <para>Manual chains work in conjunction with the
     <firstterm>compile</firstterm> <ulink
@@ -72,9 +72,139 @@
     </itemizedlist>
   </section>
 
-  <section>
+  <section id="Example">
     <title>Example</title>
 
-    <para></para>
+    <para>This example provides an alternative to the <ulink
+    url="PortKnocking.html">Port Knocking</ulink> example.</para>
+
+    <para>In this example, a Knock.pm module is created and placed in
+    /etc/shorewall:</para>
+
+    <programlisting>package Knock;
+
+use strict;
+use warnings;
+use base qw{Exporter};
+use Carp;
+use Shorewall::Chains;
+use Scalar::Util qw{reftype};
+use Shorewall::Config qw{shorewall};
+
+our @EXPORT = qw{Knock};
+
+my %recent_names;
+my %chains_created;
+
+sub scalar_or_array {
+  my $arg = shift;
+  my $name = shift;
+  return () unless defined $arg;
+  return ($arg) unless reftype($arg);
+  return @$arg if reftype($arg) eq 'ARRAY';
+  croak "Expecting argument '$name' to be scalar or array ref";
+}
+
+sub Knock {
+  my $src = shift;
+  my $dest = shift;
+  my $args = shift;
+
+  my $proto = $args-&gt;{proto} || 'tcp';
+  my $seconds = $args-&gt;{seconds} || 60;
+  my $original_dest = $args-&gt;{original_dest} || '-';
+  my @target = scalar_or_array($args-&gt;{target}, 'target');
+  my @knocker_ports = scalar_or_array($args-&gt;{knocker}, 'knocker');
+  my @trap_ports = scalar_or_array($args-&gt;{trap}, 'trap');
+
+  if (not defined $args-&gt;{name}) {
+    # If you don't supply a name, then this must be the single-call
+    # variant, so you have to specify all the arguments
+    unless (scalar @target) {
+      croak "No 'target' ports specified";
+    }
+
+    unless (scalar @knocker_ports) {
+      croak "No 'knock' ports specified";
+    }
+  }
+
+  # We'll need a unique name for the recent match list. Construct one
+  # from the port and a serial number, if the user didn't supply one.
+  my $name = $args-&gt;{name} || ($target[0] . '_' . ++$recent_names{$target[0]});
+  $name = 'Knock' . $name;
+
+  # We want one chain for all Knock rules that share a 'name' field
+  my $chainref = $chains_created{$name};
+  unless (defined $chainref) {
+    $chainref = $chains_created{$name} = new_manual_chain($name);
+  }
+  
+  # Logging
+  if ($args-&gt;{log_level}) {
+    foreach my $port (@target) {
+      log_rule_limit($args-&gt;{log_level},
+                     $chainref,
+                     'Knock',
+                     'ACCEPT',
+                     '',
+                     $args-&gt;{log_tag} || '',
+                     'add',
+                     "-p $proto --dport $port -m recent --rcheck --name $name"
+                    );
+
+      log_rule_limit($args-&gt;{log_level},
+                     $chainref,
+                     'Knock',
+                     'DROP',
+                     '',
+                     $args-&gt;{log_tag} || '',
+                     'add',
+                     "-p $proto --dport ! $port"
+                    );
+    }
+  }
+
+  # Add the recent match rules to the manual chain
+  foreach my $knock (@knocker_ports) {
+    add_rule($chainref, "-p $proto --dport $knock -m recent --name $name --set -j DROP");
+  }
+
+  foreach my $trap (@trap_ports) {
+    add_rule($chainref, "-p $proto --dport $trap -m recent --name $name --remove -j DROP");
+  }
+
+  foreach my $port (@target) {
+    add_rule($chainref, "-p $proto --dport $port -m recent --rcheck --seconds $seconds --name $name -j ACCEPT");
+  }
+
+  # And add a rule to the main chain(s) to jump into the manual chain at the appropriate points
+  my $all_dest_ports = join(',', @target, @knocker_ports, @trap_ports);
+  shorewall "$chainref-&gt;{name} $src $dest $proto $all_dest_ports - $original_dest";
+
+  return 1;
+}
+
+1;</programlisting>
+
+    <para>This simplifies /etc/shorewall/compile:<programlisting>use Knock;
+1;</programlisting></para>
+
+    <para>The rule from the Port Knocking article:</para>
+
+    <programlisting>#ACTION          SOURCE            DEST           PROTO       DEST PORT(S)
+SSHKnock         net               $FW            tcp         22,1599,1600,1601
+</programlisting>
+
+    <para>becomes:<programlisting>PERL Knock 'net', 'loc:192.168.1.5', {target =&gt; 22, knocker =&gt; 1600, trap =&gt; [1599, 1601]};</programlisting>Similarly<programlisting>#ACTION          SOURCE            DEST            PROTO       DEST PORT(S)  SOURCE      ORIGINAL
+#                                                                            PORT(S)     DEST
+DNAT-            net               loc:192.168.1.5 tcp         22            -           206.124.146.178
+SSHKnock         net               $FW             tcp         1599,1600,1601
+SSHKnock         net               loc:192.168.1.5 tcp         22            -           206.124.146.178</programlisting>becomes:<programlisting>#ACTION          SOURCE            DEST            PROTO       DEST PORT(S)  SOURCE      ORIGINAL
+#                                                                            PORT(S)     DEST
+DNAT-            net               loc:192.168.1.5 tcp         22            -           206.124.146.178
+
+PERL Knock 'net', '$FW', {name =&gt; 'SSH', knocker =&gt; 1600, trap =&gt; [1599, 1601]};
+PERL Knock 'net', 'loc:192.168.1.5', {name =&gt; 'SSH', target =&gt; 22, original_dest =&gt; '206.124.136.178'};</programlisting></para>
   </section>
 </article>

docs/PortKnocking.xml

@@ -165,6 +165,9 @@ SSHKnock         net               loc:192.168.1.5 tcp         22            -
         </note>
       </listitem>
     </orderedlist>
+
+    <para>For another way to implement Port Knocking, see the <ulink
+    url="ManualChains.html">Manual Chain</ulink> documentation.</para>
   </section>
 
   <section id="Limit">