Fixes to 'rules' man page

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

manpages/shorewall-rules.xml

@@ -21,11 +21,12 @@
   <refsect1>
     <title>Description</title>
 
-    <para>Rules in this file govern connection establishment. Requests and
+    <para>Rules in this file govern connection establishment. Subsequent
-    responses are automatically allowed using connection tracking. For any
+    requests and responses are automatically allowed using connection
-    particular (source,dest) pair of zones, the rules are evaluated in the
+    tracking. For any particular (source,dest) pair of zones, the rules are
-    order in which they appear in this file and the first match is the one
+    evaluated in the order in which they appear in this file and the first
-    that determines the disposition of the request.</para>
+    terminating match is the one that determines the disposition of the
+    request. All rules are terminating except LOG and QUEUE rules.</para>
 
     <para>In most places where an IP address or subnet is allowed, you can
     preceed the address/subnet with "!" (e.g., !192.168.1.0/24) to indicate
@@ -36,12 +37,13 @@
     <warning>
       <para>If you masquerade or use SNAT from a local system to the internet,
       you cannot use an ACCEPT rule to allow traffic from the internet to that
-      system. You *must* use a DNAT rule instead.</para>
+      system. You <emphasis role="bold">must</emphasis> use a DNAT rule
+      instead.</para>
     </warning>
 
     <para>The rules file is divided into sections. Each section is introduced
-    by a "Section Header" which is a line beginning with SECTION followed by
+    by a "Section Header" which is a line beginning with SECTION and followed
-    the section name.</para>
+    by the section name.</para>
 
     <para>Sections are as follows and must appear in the order listed:</para>
 
@@ -132,7 +134,8 @@
         role="bold">:</emphasis><emphasis>tag</emphasis>]]</term>
 
         <listitem>
-          <para>Must be one of the following.</para>
+          <para>Specifies the action to be taken if the connection request
+          matches the rule. Must be one of the following.</para>
 
           <variablelist>
             <varlistentry>
@@ -148,7 +151,8 @@
 
               <listitem>
                 <para>like ACCEPT but also excludes the connection from any
-                subsequent <emphasis role="bold">DNAT</emphasis>[<emphasis
+                subsequent matching <emphasis
+                role="bold">DNAT</emphasis>[<emphasis
                 role="bold">-</emphasis>] or <emphasis
                 role="bold">REDIRECT</emphasis>[<emphasis
                 role="bold">-</emphasis>] rules</para>
@@ -222,7 +226,7 @@
               <listitem>
                 <para>Advanced users only.</para>
 
-                <para>Like SAME but only generates the NAT iptables rule and
+                <para>Like SAME but only generates the nat iptables rule and
                 not the companion <emphasis role="bold">ACCEPT</emphasis>
                 rule.</para>
               </listitem>
@@ -232,7 +236,8 @@
               <term><emphasis role="bold">REDIRECT</emphasis></term>
 
               <listitem>
-                <para>Redirect the request to a server on the firewall.</para>
+                <para>Redirect the request to a server running on the
+                firewall.</para>
               </listitem>
             </varlistentry>
 
@@ -258,8 +263,9 @@
                 <para>Do not process any of the following rules for this
                 (source zone,destination zone). If the source and/or
                 destination IP address falls into a zone defined later in
-                shorewall-zones(5), this connection request will be passed to
+                shorewall-zones(5) or in a parent zone of the source or
-                the rules defined for that (those) zone(s).</para>
+                destination zones, then this connection request will be passed
+                to the rules defined for that (those) zone(s).</para>
               </listitem>
             </varlistentry>
 
@@ -267,7 +273,8 @@
               <term><emphasis role="bold">LOG</emphasis></term>
 
               <listitem>
-                <para>Simply log the packet and continue.</para>
+                <para>Simply log the packet and continue with the next
+                rule.</para>
               </listitem>
             </varlistentry>
 
@@ -276,7 +283,8 @@
 
               <listitem>
                 <para>Queue the packet to a user-space application such as
-                ftwall (http://p2pwall.sf.net).</para>
+                ftwall (http://p2pwall.sf.net). The application may reinsert
+                the packet for further processing.</para>
               </listitem>
             </varlistentry>
 
@@ -307,9 +315,10 @@
               <term><emphasis>macro</emphasis></term>
 
               <listitem>
-                <para>The name of a macro defined in a file named macro.If the
+                <para>The name of a macro defined in a file named
-                macro accepts an action parameter (Look at the macro source to
+                macro.<emphasis>macro</emphasis>. If the macro accepts an
-                see if it has PARAM in the TARGET column) then the
+                action parameter (Look at the macro source to see if it has
+                PARAM in the TARGET column) then the
                 <emphasis>macro</emphasis> name is followed by "/" and the
                 <emphasis>target</emphasis> (<emphasis
                 role="bold">ACCEPT</emphasis>, <emphasis
@@ -328,7 +337,11 @@
             <para>The <emphasis role="bold">ACTION</emphasis> may optionally
             be followed by ":" and a syslog log level (e.g, REJECT:info or
             DNAT:debug). This causes the packet to be logged at the specified
-            level.</para>
+            level. Note that if the <emphasis role="bold">ACTION</emphasis>
+            involves destination network address translation (DNAT, REDIRECT,
+            SAME, etc.) then the packet is logged <emphasis
+            role="bold">before</emphasis> the destination address is
+            rewritten.</para>
 
             <para>If the <emphasis role="bold">ACTION</emphasis> names an
             <emphasis>action</emphasis> defined in shorewall-actions(5) or in
@@ -347,18 +360,19 @@
               </listitem>
 
               <listitem>
-                <para>The special log level 'none!' suppresses logging by the
+                <para>The special log level <emphasis
+                role="bold">none!</emphasis> suppresses logging by the
                 action.</para>
               </listitem>
             </itemizedlist>
 
-            <para>You may also specify ULOG (must be in upper case) as a log
+            <para>You may also specify <emphasis role="bold">ULOG</emphasis>
-            level.This will log to the ULOG target for routing to a separate
+            (must be in upper case) as a log level.This will log to the ULOG
-            log through use of ulogd
+            target for routing to a separate log through use of ulogd
             (http://www.gnumonks.org/projects/ulogd).</para>
 
             <para>Actions specifying logging may be followed by a log tag (a
-            string of alphanumeric characters) are appended to the string
+            string of alphanumeric characters) which is appended to the string
             generated by the LOGPREFIX (in shorewall.conf(5)).</para>
 
             <para>Example: ACCEPT:info:ftp would include 'ftp ' at the end of
@@ -374,8 +388,8 @@
         role="bold">+</emphasis>][<emphasis
         role="bold">-</emphasis>]}<emphasis
         role="bold">[:</emphasis><emphasis>interface</emphasis>][<emphasis
-        role="bold">:</emphasis>{<emphasis>address-or-range</emphasis>[,<emphasis>address-or-range</emphasis>]...|<emphasis
+        role="bold">:</emphasis>{<emphasis>address-or-range</emphasis>[,<emphasis>address-or-range</emphasis>]...[<emphasis>exclusion</emphasis>]|<emphasis>exclusion</emphasis>|<emphasis
-        role="bold">+</emphasis><emphasis>ipset</emphasis>}[<emphasis>exclusion</emphasis>]</term>
+        role="bold">+</emphasis><emphasis>ipset</emphasis>}</term>
 
         <listitem>
           <para>Source hosts to which the rule applies. May be a zone defined
@@ -465,6 +479,15 @@
               </listitem>
             </varlistentry>
 
+            <varlistentry>
+              <term>net:!192.0.2.11-192.0.2.17</term>
+
+              <listitem>
+                <para>All hosts in the net zone except for
+                192.0.2.11-192.0.2.17.</para>
+              </listitem>
+            </varlistentry>
+
             <varlistentry>
               <term>net:155.186.235.0/24!155.186.235.16/28</term>
 
@@ -493,8 +516,8 @@
         role="bold">+</emphasis>][<emphasis
         role="bold">-</emphasis>]}<emphasis
         role="bold">[:</emphasis><emphasis>interface</emphasis>][<emphasis
-        role="bold">:</emphasis>{<emphasis>address-or-range</emphasis>[,<emphasis>address-or-range</emphasis>]...|<emphasis
+        role="bold">:</emphasis>{<emphasis>address-or-range</emphasis>[,<emphasis>address-or-range</emphasis>]...[<emphasis>exclusion</emphasis>]|<emphasis>exclusion</emphasis>|<emphasis
-        role="bold">+</emphasis><emphasis>ipset</emphasis>}}[<emphasis>exclusion</emphasis>]</term>
+        role="bold">+</emphasis><emphasis>ipset</emphasis>}</term>
 
         <listitem>
           <para>Location of Server. May be a zone defined in
@@ -562,18 +585,19 @@
               <term>Example:</term>
 
               <listitem>
-                <para>"loc:192.168.1.3:3128" specifies a local server at IP
+                <para><emphasis role="bold">loc:192.168.1.3:3128</emphasis>
-                address 192.168.1.3 and listening on port 3128. The port
+                specifies a local server at IP address 192.168.1.3 and
-                number MUST be specified as an integer and not as a name from
+                listening on port 3128. The port number MUST be specified as
-                services(5).</para>
+                an integer and not as a name from services(5).</para>
               </listitem>
             </varlistentry>
           </variablelist>
 
           <blockquote>
             <para>if the <emphasis role="bold">ACTION</emphasis> is <emphasis
-            role="bold">REDIRECT</emphasis>, this column needs only to contain
+            role="bold">REDIRECT</emphasis> or <emphasis
-            the port number on the firewall that the request should be
+            role="bold">REDIRECT-</emphasis>, this column needs only to
+            contain the port number on the firewall that the request should be
             redirected to.</para>
           </blockquote>
         </listitem>