From a5c25bea19f4ebdb9a9b02758707573275c47e6b Mon Sep 17 00:00:00 2001
From: teastep <teastep@fbd18981-670d-0410-9b5c-8dc0c1a9a2bb>
Date: Sun, 19 Apr 2009 20:41:46 +0000
Subject: [PATCH] More documentation

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9941 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
---
 Shorewall/releasenotes.txt       |  2 +-
 manpages/shorewall-tcclasses.xml | 39 +++++++++++++++++++++-
 manpages/shorewall-tcrules.xml   | 56 +++++++++++++++++++++++++++++---
 3 files changed, 91 insertions(+), 6 deletions(-)

diff --git a/Shorewall/releasenotes.txt b/Shorewall/releasenotes.txt
index ff6a7d0b7..71334f738 100644
--- a/Shorewall/releasenotes.txt
+++ b/Shorewall/releasenotes.txt
@@ -178,7 +178,7 @@ None.
 
      Example:
 
-	IPMASK(dst, 0XFF00, 0x8000,8)
+	IPMARK(dst, 0XFF00, 0x8000,8)
 
         Destination IP address is 192.168.4.3 = 0xc0a80103
 
diff --git a/manpages/shorewall-tcclasses.xml b/manpages/shorewall-tcclasses.xml
index 771eeb9fb..31abf0163 100644
--- a/manpages/shorewall-tcclasses.xml
+++ b/manpages/shorewall-tcclasses.xml
@@ -1,4 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
 <refentry>
   <refmeta>
     <refentrytitle>shorewall-tcclasses</refentrytitle>
@@ -286,6 +288,41 @@
                 </note>
               </listitem>
             </varlistentry>
+
+            <varlistentry>
+              <term><emphasis
+              role="bold">occurs</emphasis>=<emphasis>number</emphasis></term>
+
+              <listitem>
+                <para>Typically used with an IPMARK entry in tcrules. Causes
+                the rule to be replicated for a total of
+                <emphasis>number</emphasis> rules. Each rule has a
+                successively class number and mark value.</para>
+
+                <para> When 'occurs' is used:</para>
+
+                <itemizedlist>
+                  <listitem>
+                    <para>The associated device may not have the 'classify'
+                    option.</para>
+                  </listitem>
+
+                  <listitem>
+                    <para>The class may not be the default class.</para>
+                  </listitem>
+
+                  <listitem>
+                    <para>The class may not have any 'tos=' options (including
+                    'tcp-ack').</para>
+                  </listitem>
+                </itemizedlist>
+
+                <para>The 'RATE' and 'CEIL' parameters apply to each instance
+                of the class. So the total RATE represented by an entry with
+                'occurs' will be the listed RATE multiplied by
+                <emphasis>number</emphasis>. </para>
+              </listitem>
+            </varlistentry>
           </variablelist>
         </listitem>
       </varlistentry>
@@ -365,4 +402,4 @@
     shorewall.conf(5), shorewall-tcdevices(5), shorewall-tcrules(5),
     shorewall-tos(5), shorewall-tunnels(5), shorewall-zones(5)</para>
   </refsect1>
-</refentry>
\ No newline at end of file
+</refentry>
diff --git a/manpages/shorewall-tcrules.xml b/manpages/shorewall-tcrules.xml
index 34e86a4eb..d635b9a51 100644
--- a/manpages/shorewall-tcrules.xml
+++ b/manpages/shorewall-tcrules.xml
@@ -50,7 +50,9 @@
         role="bold">SAVE</emphasis>[<emphasis
         role="bold">/</emphasis><emphasis>mask</emphasis>]|<emphasis
         role="bold">CONTINUE</emphasis>|SAME|<emphasis
-        role="bold">COMMENT</emphasis>}[<emphasis
+        role="bold">COMMENT</emphasis>|IPMARK[([(<emphasis
+        role="bold">src</emphasis>|<emphasis
+        role="bold">dst</emphasis>}][,[<emphasis>mask1</emphasis>][,[<emphasis>mask2</emphasis>][,[<emphasis>shift</emphasis>]]]]])]}[<emphasis
         role="bold">:</emphasis>{<emphasis role="bold">C</emphasis>|<emphasis
         role="bold">F</emphasis>|<emphasis role="bold">P</emphasis>|<emphasis
         role="bold">T</emphasis>|<emphasis role="bold">CF</emphasis>|<emphasis
@@ -224,7 +226,7 @@
 
             <listitem>
               <para><emphasis role="bold">CONTINUE</emphasis> Don't process
-              any more marking rules in the table.</para>
+              any more marking rules ‒in the table.</para>
 
               <para>As in 1) above, may be followed by <emphasis
               role="bold">:P</emphasis> or <emphasis
@@ -250,7 +252,7 @@ SAME:P            192.168.1.0/24 0.0.0.0/0    tcp        80,443</programlisting>
               If a host in 192.168.1.0/24 attempts a connection on TCP port 80
               or 443 and it has sent a packet on either of those ports in the
               last five minutes then the new connection will use the same
-              provider as the connection over which that last packet was
+              provider as the connection over which that ‒‒last packet was
               sent.</para>
 
               <para>When used in the OUTPUT chain, it causes all matching
@@ -262,7 +264,7 @@ SAME              $FW            0.0.0.0/0    tcp        80,443</programlisting>
               it has sent a packet on either of those ports in the last five
               minutes to the same remote system then the new connection will
               use the same provider as the connection over which that last
-              packet was sent. </para>
+              packet was sent.</para>
             </listitem>
 
             <listitem>
@@ -275,6 +277,52 @@ SAME              $FW            0.0.0.0/0    tcp        80,443</programlisting>
               <para>To stop the comment from being attached to further rules,
               simply include COMMENT on a line by itself.</para>
             </listitem>
+
+            <listitem>
+              <para><emphasis role="bold">IPMARK</emphasis> ‒ Assigns a mark
+              to each matching packet based on the either the source or
+              destination IP address. By default, it assigns a mark value
+              equal to the low-order 8 bits of the source address. Default
+              values are: </para>
+
+              <simplelist>
+                <member>src</member>
+
+                <member><emphasis>mask1</emphasis> = 0xFF</member>
+
+                <member><emphasis>mask2</emphasis> = 0x00</member>
+
+                <member><emphasis>shift</emphasis> = 0</member>
+              </simplelist>
+
+              <para>'src' and 'dst' specify whether the mark is to be based on
+              the source or destination address respectively. The selected
+              address is first LANDed with <emphasis>mask1</emphasis> then
+              LORed with <emphasis>ma<emphasis>s</emphasis>k2</emphasis>. The
+              result is then shifted <emphasis>shift</emphasis> bits to the
+              right.</para>
+
+              <para>Example:</para>
+
+              <blockquote>
+                <para><simplelist>
+                    <member>IPMARK(dst, 0XFF00, 0x8000,8)</member>
+
+                    <member>Destination IP address is 192.168.4.3 =
+                    0xc0a80103</member>
+                  </simplelist>Meaning:</para>
+
+                <simplelist>
+                  <member>0xc0a80403 LAND 0xFF00 = 0x0400</member>
+
+                  <member>0x0400 LOR 0x80 = 0x8400</member>
+
+                  <member>0x8400 &gt;&gt; 8 = 0x84</member>
+
+                  <member>Mark = 0x84 = 132 </member>
+                </simplelist>
+              </blockquote>
+            </listitem>
           </orderedlist>
         </listitem>
       </varlistentry>