More documentation

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
 

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>
+</refentry>

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>