Documentation updates

docs/Actions.xml

@@ -64,6 +64,9 @@
     which each packet/rule match within the action causes a log message to be
     generated.</para>
 
+    <para>For readers familiar with iptables, actions are the way in which you
+    can create your own filter-table chains.</para>
+
     <para>There are three types of Shorewall actions:</para>
 
     <orderedlist>
@@ -158,7 +161,7 @@ ACCEPT   -              -               tcp     135,139,445
 
     <para>In addition, the default specified in
     <filename>/etc/shorewall/shorewall.conf</filename> may be overridden by
-    specifying a different default in the POLICY column of <filename><ulink
+    specifying a different action in the POLICY column of <filename><ulink
     url="manpages/shorewall-policy.html">/etc/shorewall/policy</ulink></filename>.</para>
 
     <warning>
@@ -169,107 +172,6 @@ ACCEPT   -              -               tcp     135,139,445
     </warning>
   </section>
 
-  <section id="Limit">
-    <title>Limiting Per-IP Connection Rate</title>
-
-    <para>Shorewall supports a <quote>Limit</quote> <ulink
-    url="Actions.html">action</ulink>. Limit is invoked with a comma-separated
-    list in place of a logging tag. The list has three elements:</para>
-
-    <orderedlist>
-      <listitem>
-        <para>The name of a <quote>recent</quote> list. You select the list
-        name which must conform to the rules for a valid chain name. Different
-        rules that specify the same list name will use the same set of
-        counters.</para>
-      </listitem>
-
-      <listitem>
-        <para>The number of connections permitted in a specified time
-        period.</para>
-      </listitem>
-
-      <listitem>
-        <para>The time period, expressed in seconds.</para>
-      </listitem>
-    </orderedlist>
-
-    <para>Connections that exceed the specified rate are dropped.</para>
-
-    <para>For example, to use a recent list name of <emphasis
-    role="bold">SSHA</emphasis>, and to limit SSH connections to 3 per minute,
-    use this entry in <filename>/etc/shorewall/rules</filename>:</para>
-
-    <programlisting>#ACTION                SOURCE            DEST           PROTO       DEST PORT(S)
-Limit:none:SSHA,3,60   net               $FW            tcp         22</programlisting>
-
-    <para>If you want dropped connections to be logged at the info level, use
-    this rule instead:</para>
-
-    <programlisting>#ACTION                SOURCE            DEST           PROTO       DEST PORT(S)
-Limit:info:SSHA,3,60   net               $FW            tcp         22</programlisting>
-
-    <para>To summarize, you pass four pieces of information to the Limit
-    action:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para>The log level. If you don't want to log, specify
-        <quote>none</quote>.</para>
-      </listitem>
-
-      <listitem>
-        <para>The name of the recent list that you want to use
-        (<quote>SSHA</quote> in this example).</para>
-      </listitem>
-
-      <listitem>
-        <para>The maximum number of connections to accept (3 in this
-        example).</para>
-      </listitem>
-
-      <listitem>
-        <para>The number of seconds over which you are willing to accept that
-        many connections (60 in this example).</para>
-      </listitem>
-    </itemizedlist>
-
-    <section id="LimitImp">
-      <title>How Limit is Implemented</title>
-
-      <para>For those who are curious, the Limit action is implemented as
-      follows:</para>
-
-      <programlisting>my @tag = split /,/, $tag;
-
-fatal_error 'Limit rules must include &lt;list name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag (' . join( ':', 'Limit', $level eq '' ? 'none' : $level , $tag ) . ')'
-    unless @tag == 3;
-
-my $list = $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 $list --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 $list --update --seconds $tag[2] --hitcount $count -j $xchainref-&gt;{name}";
-} else {
-    add_rule $chainref, "-m recent --update --name $list --seconds $tag[2] --hitcount $count -j DROP";
-}
-
-add_rule $chainref, '-j ACCEPT';
-
-1; </programlisting>
-    </section>
-  </section>
-
   <section id="Defining">
     <title>Defining your own Actions</title>
 
@@ -699,7 +601,107 @@ add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );
 1;</programlisting></para>
     </example>
 
-    <para>For a richer example, see <ulink url="PortKnocking.html">this
+    <para>For a richer example, see the next section.</para>
-    article</ulink>.</para>
+  </section>
+
+  <section id="Limit">
+    <title>Limiting Per-IP Connection Rate using the Limit Action</title>
+
+    <para>Shorewall supports a <quote>Limit</quote> built-in action. Limit is
+    invoked with a comma-separated list in place of a logging tag. The list
+    has three elements:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>The name of a <quote>recent</quote> list. You select the list
+        name which must conform to the rules for a valid chain name. Different
+        rules that specify the same list name will use the same set of
+        counters.</para>
+      </listitem>
+
+      <listitem>
+        <para>The number of connections permitted in a specified time
+        period.</para>
+      </listitem>
+
+      <listitem>
+        <para>The time period, expressed in seconds.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Connections that exceed the specified rate are dropped.</para>
+
+    <para>For example, to use a recent list name of <emphasis
+    role="bold">SSHA</emphasis>, and to limit SSH connections to 3 per minute,
+    use this entry in <filename>/etc/shorewall/rules</filename>:</para>
+
+    <programlisting>#ACTION                SOURCE            DEST           PROTO       DEST PORT(S)
+Limit:none:SSHA,3,60   net               $FW            tcp         22</programlisting>
+
+    <para>If you want dropped connections to be logged at the info level, use
+    this rule instead:</para>
+
+    <programlisting>#ACTION                SOURCE            DEST           PROTO       DEST PORT(S)
+Limit:info:SSHA,3,60   net               $FW            tcp         22</programlisting>
+
+    <para>To summarize, you pass four pieces of information to the Limit
+    action:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The log level. If you don't want to log, specify
+        <quote>none</quote>.</para>
+      </listitem>
+
+      <listitem>
+        <para>The name of the recent list that you want to use
+        (<quote>SSHA</quote> in this example).</para>
+      </listitem>
+
+      <listitem>
+        <para>The maximum number of connections to accept (3 in this
+        example).</para>
+      </listitem>
+
+      <listitem>
+        <para>The number of seconds over which you are willing to accept that
+        many connections (60 in this example).</para>
+      </listitem>
+    </itemizedlist>
+
+    <section id="LimitImp">
+      <title>How Limit is Implemented</title>
+
+      <para>For those who are curious, the Limit action is implemented as
+      follows:</para>
+
+      <programlisting>my @tag = split /,/, $tag;
+
+fatal_error 'Limit rules must include &lt;list name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag (' . join( ':', 'Limit', $level eq '' ? 'none' : $level , $tag ) . ')'
+    unless @tag == 3;
+
+my $list = $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 $list --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 $list --update --seconds $tag[2] --hitcount $count -j $xchainref-&gt;{name}";
+} else {
+    add_rule $chainref, "-m recent --update --name $list --seconds $tag[2] --hitcount $count -j DROP";
+}
+
+add_rule $chainref, '-j ACCEPT';
+
+1; </programlisting>
+    </section>
   </section>
 </article>

docs/Build.xml

@@ -139,7 +139,8 @@
       <title>setversion</title>
 
       <para>The <command>setversion</command> script updates the version
-      number is a directory.</para>
+      number in a directory. The script is run with the current working
+      directory being <filename class="directory">trunk</filename>.</para>
 
       <blockquote>
         <para><command>setversion</command>
@@ -153,8 +154,7 @@
     <section>
       <title>build44</title>
 
-      <para>This is the script that builds Shorewall packages from Git.
+      <para>This is the script that builds Shorewall packages from Git.</para>
-      </para>
 
       <para>The script copies content from Git using the <command>git
       archive</command> command. It then uses that content to build the
@@ -344,22 +344,6 @@
                   <para>Build the shorewall6-lite package.</para>
                 </listitem>
               </varlistentry>
-
-              <varlistentry>
-                <term>p</term>
-
-                <listitem>
-                  <para>Build the shorewall-perl package</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term>s</term>
-
-                <listitem>
-                  <para>Build the shorewall-shell package</para>
-                </listitem>
-              </varlistentry>
             </variablelist>
           </listitem>
         </varlistentry>
@@ -386,14 +370,14 @@
       4.3.6:</para>
 
       <blockquote>
-        <para><command>buildshorewall 4.3.7 4.3.6</command></para>
+        <para><command>build44 4.3.7 4.3.6</command></para>
       </blockquote>
 
-      <para>Example 2 - Build Shorewall 4.2.7.1 Shorewall-perl and generate
+      <para>Example 2 - Build Shorewall 4.2.7.1 Shorewall and generate patches
-      patches against 4.2.7:</para>
+      against 4.2.7:</para>
 
       <blockquote>
-        <para><command>buildshorewall -trSp 4.3.7.1 4.3.7</command></para>
+        <para><command>build44 -trSc 4.3.7.1 4.3.7</command></para>
       </blockquote>
     </section>
 
@@ -452,24 +436,6 @@
                   <para>Upload the shorewall6-lite package.</para>
                 </listitem>
               </varlistentry>
-
-              <varlistentry>
-                <term>p</term>
-
-                <listitem>
-                  <para>Upload the shorewall-perl package (versions 4.0 and
-                  4.2 only)</para>
-                </listitem>
-              </varlistentry>
-
-              <varlistentry>
-                <term>s</term>
-
-                <listitem>
-                  <para>Upload the shorewall-shell package (versions 4.0 and
-                  4.2 only)</para>
-                </listitem>
-              </varlistentry>
             </variablelist>
           </listitem>
         </varlistentry>

docs/CompiledPrograms.xml

@@ -58,11 +58,6 @@
       attempting to use them.</para>
 
       <orderedlist>
-        <listitem>
-          <para>The <emphasis role="bold">detectnets</emphasis> interface
-          option is not supported.</para>
-        </listitem>
-
         <listitem>
           <para>All extension scripts used are copied into the program (with
           the exception of <ulink url="shorewall_extension_scripts.htm">those
@@ -115,8 +110,8 @@
     command:</para>
 
     <blockquote>
-      <para><command>shorewall compile [ -e ] [ &lt;directory name&gt; ]
+      <para><command>shorewall compile [ -e ] [ &lt;directory name&gt; ] [
-      &lt;path name&gt;</command></para>
+      &lt;path name&gt; ]</command></para>
     </blockquote>
 
     <para>where</para>
@@ -162,7 +157,9 @@
           <term>&lt;path name&gt;</term>
 
           <listitem>
-            <para>specifies the name of the script to be created.</para>
+            <para>specifies the name of the script to be created. If not
+            given, ${VARDIR}/firewall is assumed (by default, ${VARDIR} is
+            <filename>/var/lib/shorewall/</filename>)</para>
           </listitem>
         </varlistentry>
       </variablelist>
@@ -239,8 +236,9 @@
           <listitem>
             <para>modify the files in the corresponding export directory
             appropriately. It's a good idea to include the IP address of the
-            administrative system in the <filename>routestopped</filename>
+            administrative system in the <ulink
-            file.</para>
+            url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
+            file</ulink>.</para>
 
             <para>It is important to understand that with Shorewall Lite, the
             firewall's export directory on the administrative system acts as
@@ -288,8 +286,9 @@
             -e</command>), copies that file to the remote system via scp and
             starts Shorewall Lite on the remote system via ssh. The -c option
             causes the capabilities of the remote system to be generated and
-            copied to a file named capabilities in the export directory. See
+            copied to a file named <filename>capabilities</filename> in the
-            <link linkend="Shorecap">below</link>.</para>
+            export directory. See <link
+            linkend="Shorecap">below</link>.</para>
 
             <para>Example (firewall's DNS name is 'gateway'):</para>
 
@@ -538,8 +537,9 @@ clean:
           <para>On the administrative system:</para>
 
           <para>It's a good idea to include the IP address of the
-          administrative system in the firewall system's
+          administrative system in the firewall system's <ulink
-          <filename>routestopped</filename> file.</para>
+          url="manpages/shorewall-routestopped.html"><filename>routestopped</filename>
+          file</ulink>.</para>
 
           <para>Also, edit the <filename>shorewall.conf</filename> file in the
           firewall's export directory and change the CONFIG_PATH setting to
@@ -727,8 +727,8 @@ CAPVERSION=40190</programlisting>
   <section id="Running">
     <title>Running compiled programs directly</title>
 
-    <para>Compiled firewall programs are complete programs that support the
+    <para>Compiled firewall programs are complete shell programs that support
-    following command line forms:</para>
+    the following command line forms:</para>
 
     <blockquote>
       <simplelist>

docs/Dynamic.xml

@@ -45,11 +45,144 @@
 
     <para>Shorewall provides basic support for defining such zones. This
     support is based on <ulink
-    url="http://ipset.netfilter.org/">ipset</ulink>, so to use dynamic zones,
+    url="http://ipset.netfilter.org/">ipset</ulink>. As of this writing, ipset
-    you must have installed the <ulink
+    is not included in the standard kernel distribution; so to use dynamic
+    zones, you must be running kernel 2.6.20 or later and have installed the
+    <ulink
     url="http://xtables-addons.sourceforge.net/">xtables-addons</ulink>.</para>
   </section>
 
+  <section>
+    <title>Installing xtables-addons</title>
+
+    <para>The xtables-addons are fairly easy to install. You do not need to
+    recompile your kernel. Basic steps are as follows:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Install gcc and make</para>
+      </listitem>
+
+      <listitem>
+        <para>Install the headers for the kernel you are running. In some
+        distributions, such as <trademark>Debian</trademark> and
+        <trademark>Ubuntu</trademark>, the packet is called kernel-headers.
+        For other distrubutions, such as OpenSuSE, you must install the
+        kernel-source package.</para>
+      </listitem>
+
+      <listitem>
+        <para>At a shell prompt, type 'locate libxtables'. If no output is
+        produced, then you must download and install the latest iptables.
+        </para>
+
+        <orderedlist numeration="loweralpha">
+          <listitem>
+            <para>download the iptables source tarball</para>
+          </listitem>
+
+          <listitem>
+            <para>untar the source</para>
+          </listitem>
+
+          <listitem>
+            <para>cd to the iptables source directory</para>
+          </listitem>
+
+          <listitem>
+            <para>run './configure'</para>
+          </listitem>
+
+          <listitem>
+            <para>run 'make'</para>
+          </listitem>
+
+          <listitem>
+            <para>As root, cd to the iptables source directory and run 'make
+            install'.</para>
+          </listitem>
+
+          <listitem>
+            <para>Your new iptables binary will now be installed in
+            /usr/local/sbin. Modify shorewall.conf to specify
+            IPTABLES=/usr/local/sbin/iptables</para>
+          </listitem>
+        </orderedlist>
+      </listitem>
+
+      <listitem>
+        <para>Download the latest xtables-addons source tarball</para>
+      </listitem>
+
+      <listitem>
+        <para>Untar the xtables-addons source</para>
+      </listitem>
+
+      <listitem>
+        <para>cd to the xtables-addons source directory</para>
+      </listitem>
+
+      <listitem>
+        <para>run './configure'</para>
+      </listitem>
+
+      <listitem>
+        <para>run 'make'</para>
+      </listitem>
+
+      <listitem>
+        <para>As root, cd to the xtables-addons directory and run 'make
+        install'.</para>
+      </listitem>
+
+      <listitem>
+        <para>Restart shorewall</para>
+      </listitem>
+
+      <listitem>
+        <para>'shorewall show capabilities' should now indicate<emphasis
+        role="bold"> Ipset Match: Available</emphasis></para>
+      </listitem>
+    </orderedlist>
+
+    <para>You will have to repeat steps 6-9 each time that you receive a
+    kernel upgrade from your distribution venrundor. You can install
+    xtables-addons before booting to the new kernel as follows
+    (<emphasis>new-kernel-version</emphasis> is the version of the
+    newly-installed kernel - example <emphasis
+    role="bold">2.6.28.11-generic</emphasis>. Look in the /lib/modules
+    directory to get the full version name)</para>
+
+    <orderedlist>
+      <listitem>
+        <para>cd to the xtables-addons source directory</para>
+      </listitem>
+
+      <listitem>
+        <para>run 'make clean'</para>
+      </listitem>
+
+      <listitem>
+        <para>run './configure --with-kbuild
+        /lib/modules/<emphasis>new-kernel-version</emphasis>/build'</para>
+      </listitem>
+
+      <listitem>
+        <para>run 'make'</para>
+      </listitem>
+
+      <listitem>
+        <para>As root, cd to the xtables-addons source directory and run 'make
+        install'.</para>
+      </listitem>
+
+      <listitem>
+        <para>As root, run 'depmod -a
+        <emphasis>new-kernel-version'</emphasis></para>
+      </listitem>
+    </orderedlist>
+  </section>
+
   <section>
     <title>Defining a Dynamic Zone</title>
 
@@ -93,6 +226,10 @@ webok       eth0           -                hosts=dynamic</programlisting>
     <blockquote>
       <para><command>shorewall add eth0:192.168.3.4 webok</command></para>
     </blockquote>
+
+    <para>The command can only be used when the ipset involved is of type
+    iphash. For other ipset types, the <command>ipset</command> command must
+    be used directly.</para>
   </section>
 
   <section>
@@ -112,6 +249,10 @@ webok       eth0           -                hosts=dynamic</programlisting>
     <blockquote>
       <para><command>shorewall delete eth0:192.168.3.4 webok</command></para>
     </blockquote>
+
+    <para>The command can only be used when the ipset involved is of type
+    iphash. For other ipset types, the <command>ipset</command> command must
+    be used directly.</para>
   </section>
 
   <section>
@@ -152,7 +293,8 @@ eth0:
   <section>
     <title>Restrictions</title>
 
-    <para>When using dynamic zones, you may not use ipsets in your
+    <para>When using dynamic zones, you may not use ipsets in your <ulink
-    <filename>/etc/shorewall/routestopped</filename> file.</para>
+    url="manpages/shorewall-routestopped.html">/etc/shorewall/routestopped</ulink>
+    file.</para>
   </section>
 </article>

docs/configuration_file_basics.xml

@@ -227,6 +227,14 @@
           <filename>/etc/shorewall</filename> and modify the
           copy</emphasis>.</para>
         </listitem>
+
+        <listitem>
+          <para><filename>/usr/share/modules</filename> — Specifies the kernel
+          modules to be loaded during shorewall start/restart . <emphasis
+          role="bold">If you need to change this file, copy it to
+          <filename>/etc/shorewall</filename> and modify the
+          copy</emphasis>.</para>
+        </listitem>
       </itemizedlist></para>
   </section>
 
@@ -600,8 +608,8 @@ SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
       <listitem>
         <para>The <filename>/etc/shorewall/params</filename> file is processed
         by the compiler at compile-time and by the compiled script at
-        run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if you have
+        run-time. If you have set EXPORTPARAMS=No in
-        set EXPORTPARAMS=No in <filename>shorewall.conf</filename>, then the
+        <filename>shorewall.conf</filename>, then the
         <filename><filename>params</filename></filename> file is only
         processed by the compiler; it is not run by the compiled
         script.</para>
@@ -865,8 +873,8 @@ POP(ACCEPT)     loc                  net:pop.gmail.com</programlisting>
 
       <listitem>
         <para>If you use line continuation to break a comma-separated list,
-        the continuation line(s) must begin in column 1 (or there would be
+        the comma must be the last thing on the continued line before '\'
-        embedded white space)</para>
+        unless the continuation line has no leading white space.</para>
       </listitem>
 
       <listitem>

docs/traffic_shaping.xml

@@ -1344,7 +1344,7 @@ ppp0            4       90kbit          200kbit         3           default</pro
     instructions.</para>
   </section>
 
-  <section>
+  <section id="HFSC">
     <title>An HFSC Example</title>
 
     <para>As mentioned at the top of this article, there is an excellent
@@ -1371,7 +1371,7 @@ eth0          -                1000kbit               hfsc</programlisting>
     <para>The following sub-section offers some notes about the
     article.</para>
 
-    <section>
+    <section id="MajicNumbers">
       <title>Where Did all of those Magic Numbers come from?</title>
 
       <para>As you read the article, numbers seem to be introduced out of thin

manpages/shorewall-routestopped.xml

@@ -12,7 +12,7 @@
     <refname>routestopped</refname>
 
     <refpurpose>The Shorewall file that governs what traffic flows through the
-    firewall while it is in 'stopped' state.</refpurpose>
+    firewall while it is in the 'stopped' state.</refpurpose>
   </refnamediv>
 
   <refsynopsisdiv>
@@ -29,6 +29,12 @@
     used, the file also determines those hosts that are accessible when the
     firewall is in the process of being [re]started.</para>
 
+    <warning>
+      <para>Changes to this file do not take effect until after the next
+      <command>shorewall start</command> or <command>shorewall
+      restart</command> command.</para>
+    </warning>
+
     <para>The columns in the file are as follows.</para>
 
     <variablelist>
@@ -102,34 +108,6 @@
               </listitem>
             </varlistentry>
 
-            <varlistentry>
-              <term><emphasis role="bold">critical</emphasis></term>
-
-              <listitem>
-                <para>Allow traffic between the firewall and these hosts
-                throughout '[re]start', 'stop' and 'clear'. Specifying
-                <emphasis role="bold">critical</emphasis> on one or more
-                entries will cause your firewall to be "totally open" for a
-                brief window during each of those operations. Examples of
-                where you might want to use this are:</para>
-
-                <itemizedlist>
-                  <listitem>
-                    <para>'Ping' nodes with heartbeat.</para>
-                  </listitem>
-
-                  <listitem>
-                    <para>LDAP server(s) if you use LDAP Authentication</para>
-                  </listitem>
-
-                  <listitem>
-                    <para>NFS Server if you have an NFS-mounted root
-                    filesystem.</para>
-                  </listitem>
-                </itemizedlist>
-              </listitem>
-            </varlistentry>
-
             <varlistentry>
               <term>notrack</term>