More doc updates

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

docs/Actions.xml

@@ -414,7 +414,7 @@ Reject:REJECT   #Default Action for REJECT policy</programlisting>
 
         <para>If you don’t want to define a test but need to specify anything
         in the following columns, place a "-" in this field.<simplelist>
-            <member> ! — Inverts the test (not equal)</member>
+            <member>! — Inverts the test (not equal)</member>
 
             <member>&lt;<emphasis>value</emphasis>&gt; — Value of the packet
             or connection mark.</member>
@@ -554,8 +554,27 @@ acton:info:test  $FW              net</programlisting>
       </listitem>
     </itemizedlist>
 
-    <para>For an example of how to use these variables, see <ulink
+    <para>Shorewall-perl sets lexical variables as follows:</para>
-    url="PortKnocking.html">this article</ulink>.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>$chainref is a reference to the chain-table entry for the chain
+        where your rules are to be placed.</para>
+      </listitem>
+
+      <listitem>
+        <para>$level is the log level. If false, no logging was
+        specified.</para>
+      </listitem>
+
+      <listitem>
+        <para>$tag is the log tag.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For an example of how to use these variables in both Shorewall-shell
+    and Shorewall-perl, see <ulink url="PortKnocking.html">this
+    article</ulink>.</para>
   </section>
 
   <section id="Extension">
@@ -583,7 +602,9 @@ acton:info:test  $FW              net</programlisting>
         </blockquote>When using Shorewall-Perl:<blockquote>
           <para>/etc/shorewall/DropBcasts<programlisting>use Shorewall::Chains;
 
-add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );</programlisting></para>
+add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );
+
+1;</programlisting></para>
         </blockquote></para>
     </example>
 

docs/FTP.xml

@@ -293,6 +293,15 @@ xt_tcpudp               3328  0
   <section>
     <title>FTP on Non-standard Ports</title>
 
+    <note>
+      <para>If you are running <emphasis role="bold">kernel 2.6.20 or
+      later</emphasis>, replace <emphasis
+      role="bold">ip_conntrack_ftp</emphasis> with <emphasis
+      role="bold">nf_conntrack_ftp</emphasis> in the following instructions.
+      Similarly, replace <emphasis role="bold">ip_nat_ftp</emphasis> with
+      <emphasis role="bold">nf_nat_ftp</emphasis>.</para>
+    </note>
+
     <para>The above discussion about commands and responses makes it clear
     that the FTP connection-tracking and NAT helpers must scan the traffic on
     the control connection looking for PASV and PORT commands as well as PASV

docs/Install.xml

@@ -91,13 +91,27 @@
         page</ulink>.</para>
 
         <para>If you try to install the wrong package, it probably won't
-        work.</para>
+        work.<note>
+            <para>If you are installing Shorewall 4.0.0 or later then you need
+            to install at least two packages.<itemizedlist>
+                <listitem>
+                  <para>Shorewall</para>
+                </listitem>
+
+                <listitem>
+                  <para>Either Shorewall-shell (the classic shell-based
+                  configuration compiler) and/or Shorewall-perl (the newer and
+                  faster compiler written in Perl).</para>
+                </listitem>
+              </itemizedlist>If you are installing Shorewall for the first
+            time, we strongly suggest that you install Shorewall-perl.</para>
+          </note></para>
       </listitem>
 
       <listitem>
         <para>Install the RPM</para>
 
-        <programlisting><command>rpm -ivh &lt;shorewall rpm&gt;</command></programlisting>
+        <programlisting><command>rpm -ivh &lt;shorewall rpm&gt; &lt;compiler rpm&gt; ...</command></programlisting>
 
         <caution>
           <para>Some users are in the habit of using the <command>rpm
@@ -115,7 +129,7 @@
           though a 2.4 kernel is installed. If this happens, simply use the
           --nodeps option to rpm.</para>
 
-          <programlisting><filename><command>rpm -ivh --nodeps &lt;shorewall rpm&gt;</command></filename></programlisting>
+          <programlisting><filename><command>rpm -ivh --nodeps &lt;rpms&gt;</command></filename></programlisting>
         </note>
 
         <note>
@@ -129,7 +143,7 @@
           package (see 1., above) but may be worked around by using the
           --nodeps option of rpm.</para>
 
-          <programlisting><command>rpm -ivh --nodeps &lt;shorewall rpm&gt;</command></programlisting>
+          <programlisting><command>rpm -ivh --nodeps &lt;rpms&gt;</command></programlisting>
         </note>
       </listitem>
 
@@ -165,6 +179,43 @@
   <section id="Install_Tarball">
     <title>Install using tarball</title>
 
+    <note>
+      <para>If you are installing Shorewall 4.0.0 or later, then you need to
+      install one of the configuration compilers <emphasis
+      role="bold">before</emphasis> you install Shorewall itself. You can
+      choose to install one or both compilers:<itemizedlist>
+          <listitem>
+            <para>Shorewall-shell - the classic configuration compiler written
+            in Bourne Shell.</para>
+          </listitem>
+
+          <listitem>
+            <para>Shorewall-perl - a newer and faster compiler written in
+            Perl.</para>
+          </listitem>
+        </itemizedlist>If you are installing Shorewall for the first time, we
+      strongly suggest that you install Shorewall-perl.</para>
+
+      <para>To install Shorewall-perl:<orderedlist>
+          <listitem>
+            <para>unpack the tarball (tar -zxf
+            shorewall-perl-x.y.z.tgz).</para>
+          </listitem>
+
+          <listitem>
+            <para>cd to the shorewall-perl directory (the version is encoded
+            in the directory name as in
+            <quote>shorewall-perl-4.0.0</quote>).</para>
+          </listitem>
+
+          <listitem>
+            <para>Type:</para>
+
+            <programlisting><command>./install.sh</command></programlisting>
+          </listitem>
+        </orderedlist>Installing Shorewall-shell is similar.</para>
+    </note>
+
     <para>To install Shorewall using the tarball and install script:</para>
 
     <orderedlist>
@@ -312,7 +363,7 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
       <listitem>
         <para>Upgrade the RPM</para>
 
-        <programlisting><command>rpm -Uvh &lt;shorewall rpm file&gt;</command></programlisting>
+        <programlisting><command>rpm -Uvh &lt;shorewall rpm file&gt; &lt;compiler rpm file&gt; ...</command></programlisting>
 
         <note>
           <para>Some <trademark>SUSE</trademark> users have encountered a
@@ -320,7 +371,7 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
           though a 2.4 kernel is installed. If this happens, simply use the
           --nodeps option to rpm.</para>
 
-          <programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt;</command></programlisting>
+          <programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt; &lt;compiler rpm&gt; ...</command></programlisting>
         </note>
 
         <note>
@@ -333,7 +384,7 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
           <para>This may be worked around by using the --nodeps option of
           rpm.</para>
 
-          <programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt;</command></programlisting>
+          <programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt; &lt;compiler-rpm&gt; ...</command></programlisting>
         </note>
       </listitem>
 
@@ -530,7 +581,7 @@ tar -xzvf /mnt/package2.lrp
     </blockquote>
 
     <para>For information on other LEAF/Bering upgrade tools, check out <ulink
-			url="http://leaf.cvs.sourceforge.net/*checkout*/leaf/devel/alexrh/lck/README.html">this
+    url="http://leaf.cvs.sourceforge.net/*checkout*/leaf/devel/alexrh/lck/README.html">this
     article by Alex Rhomberg</ulink>.</para>
   </section>
 

docs/PortKnocking.xml

@@ -40,7 +40,7 @@
     <para>The feature described in this article require '<ulink
     url="http://snowman.net/projects/ipt_recent/">Recent Match</ulink>' in
     your iptables and kernel. See the output of <command>shorewall show
-    capabilities</command> to see if you have that match. </para>
+    capabilities</command> to see if you have that match.</para>
   </note>
 
   <section>
@@ -88,7 +88,9 @@
 
       <listitem>
         <para>Create /etc/shorewall/SSHKnock with the following
-        contents:</para>
+        contents.</para>
+
+        <para>If using Shorewall-shell:</para>
 
         <programlisting>if [ -n "$LEVEL" ]; then
     log_rule_limit $LEVEL $CHAIN SSHKnock ACCEPT "" "$TAG" -A -p tcp --dport 22   -m recent --rcheck --name SSH
@@ -98,6 +100,35 @@ run_iptables -A $CHAIN -p tcp --dport 22   -m recent --rcheck --seconds 60 --nam
 run_iptables -A $CHAIN -p tcp --dport 1599 -m recent                       --name SSH --remove -j DROP
 run_iptables -A $CHAIN -p tcp --dport 1600 -m recent                       --name SSH --set    -j DROP
 run_iptables -A $CHAIN -p tcp --dport 1601 -m recent                       --name SSH --remove -j DROP</programlisting>
+
+        <para>If using Shorewall-perl:<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 1599 -m recent                       --name SSH --remove -j DROP' );
+add_rule( $chainref, '-p tcp --dport 1600 -m recent                       --name SSH --set    -j DROP' );
+add_rule( $chainref, '-p tcp --dport 1601 -m recent                       --name SSH --remove -j DROP' );
+
+1;</programlisting></para>
       </listitem>
 
       <listitem>
@@ -240,14 +271,45 @@ else
     run_iptables -A $CHAIN -m recent --update --name $1 --seconds $3 --hitcount $(( $2 + 1 )) -j DROP
 fi
 
-run_iptables -A $CHAIN -j ACCEPT
+run_iptables -A $CHAIN -j ACCEPT</programlisting>
-</programlisting>
         </listitem>
       </itemizedlist>
 
       <para>In Shorewall 3.3, Limit is made into a built-in action; basically
       that means that the above code now lives inside of Shorewall rather than
       in a separate file.</para>
+
+      <para>For completeness, here's the above
+      <filename>/usr/share/shorewall/Limit</filename> for use with
+      Shorewall-perl:</para>
+
+      <programlisting>my @tag = split /,/, $tag;
+
+fatal_error 'Limit rules must include &lt;set name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag (' . join( ':', 'Limit', $level eq '' ? 'none' : $level , $tag ) . ')'
+    unless @tag == 3;
+
+my $set = $tag[0];
+
+for ( @tag[1,2] ) {
+    fatal_error 'Max connections and interval in Limit rules must be numeric (' . join( ':', 'Limit', $level eq '' ? 'none' : $level, $tag ) . ')' unless /^\d+$/
+}
+
+my $count = $tag[1] + 1;
+
+add_rule $chainref, "-m recent --name $set --set";
+
+if ( $level ) {
+    my $xchainref = new_chain 'filter' , "$chainref-&gt;{name}%";
+    log_rule_limit $level, $xchainref, $tag[0], 'DROP', '', '', 'add', '';
+    add_rule $xchainref, '-j DROP';
+    add_rule $chainref,  "-m recent --name $set --update --seconds $tag[2] --hitcount $count -j $xchainref-&gt;{name}";
+} else {
+    add_rule $chainref, "-m recent --update --name $set --seconds $tag[2] --hitcount $count -j DROP";
+}
+
+add_rule $chainref, '-j ACCEPT';
+
+1; </programlisting>
     </section>
   </section>
 </article>

docs/configuration_file_basics.xml

@@ -614,10 +614,25 @@ Shorewall has detected the following iptables/netfilter capabilities:
   </section>
 
   <section id="Ports">
-    <title>Port Numbers/Service Names</title>
+    <title>Protocol Number/Names and Port Numbers/Service Names</title>
 
-    <para>Unless otherwise specified, when giving a port number you can use
+    <para>Unless otherwise specified, when giving a protocol number you can
-    either an integer or a service name from /etc/services.</para>
+    use either an integer or a protocol name from
+    <filename>/etc/protocols</filename>. Similarly, when giving a port number
+    you can use either an integer or a service name from
+    <filename>/etc/services</filename>.<note>
+        <para>Shorewall-perl translates protocol names to protocol numbers and
+        service names to port numbers itself. The mapping that it uses is
+        contained in the Perl module
+        <filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename>.
+        That module is built when Shorewall is installed or upgraded using the
+        current <filename>/etc/protocols</filename> and
+        <filename>/etc/services</filename> files as input (if the build
+        program fails, a fallback version of the module is installed).</para>
+
+        <para>To generate a new Ports.pm module:<programlisting>cp /usr/share/shorewall-perl/Shorewall/Ports.pm /usr/share/shorewall-perl/Shorewall/Ports.pm.backup
+/usr/share/shorewall/buildports.pm &gt; /usr/share/shorewall-perl/Shorewall/Ports.pm</programlisting></para>
+      </note></para>
   </section>
 
   <section id="Ranges">
@@ -661,6 +676,17 @@ DNAT       net        loc:192.168.1.3 tcp       4000:4100</programlisting>
         15.</para>
       </listitem>
     </orderedlist>
+
+    <note>
+      <para>Shorewall-perl requires <emphasis role="bold">multiport</emphasis>
+      match in order to accept port lists in Shorewall configuration files. It
+      further requires Extended <emphasis role="bold">multiport</emphasis>
+      match in order to accept port ranges in port lists. Shorewall-perl will
+      never break a list longer than 15 ports (with each range counting as two
+      ports) into smaller lists. So you must be sure that your port lists can
+      be handled directly by the Netfilter/iptables capabilities
+      available.</para>
+    </note>
   </section>
 
   <section id="Variables">