From b2c03b824cd596c654ac522b5f0d41e38067e38a Mon Sep 17 00:00:00 2001
From: teastep <teastep@fbd18981-670d-0410-9b5c-8dc0c1a9a2bb>
Date: Tue, 3 Oct 2006 16:08:43 +0000
Subject: [PATCH] Extend packet marking document

git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@4619 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
---
 docs/PacketMarking.xml | 64 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/docs/PacketMarking.xml b/docs/PacketMarking.xml
index 7c4d906ae..bc0c5550b 100644
--- a/docs/PacketMarking.xml
+++ b/docs/PacketMarking.xml
@@ -295,11 +295,73 @@ tcp      6 19 TIME_WAIT src=206.124.146.176 dst=192.136.34.98 sport=58597 dport=
     (PREROUTING, FORWARD, etc.).</para>
   </section>
 
+  <section>
+    <title>An Example</title>
+
+    <para>Here's the example from the comments at the top of the
+    <filename>/etc/shorewall/tcrules</filename> file.</para>
+
+    <programlisting>#MARK    SOURCE          DEST            PROTO   PORT(S) CLIENT  USER    TEST    LENGTH  TOS
+#                                                        PORT(S)
+1        0.0.0.0/0       0.0.0.0/0       icmp    echo-request                 #Rule 1
+1        0.0.0.0/0       0.0.0.0/0       icmp    echo-reply                   #Rule 2
+
+RESTORE  0.0.0.0/0       0.0.0.0/0       all     -       -       -       0    #Rule 3
+CONTINUE 0.0.0.0/0       0.0.0.0/0       all     -       -       -       !0   #Rule 4
+4        0.0.0.0/0       0.0.0.0/0       ipp2p:all                            #Rule 5
+SAVE     0.0.0.0/0       0.0.0.0/0       all     -       -       -       !0   #Rule 6
+##LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE</programlisting>
+
+    <para>Let's take a look at each rule:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>This straight-forward rule simply marks all 'ping' requests
+        passing through the firewall with mark value 1. Note that it does not
+        mark pings that originate on the firewall itself; if we wanted that,
+        we would have to add another rule that had "$FW" in the SOURCE
+        column.</para>
+      </listitem>
+
+      <listitem>
+        <para>Similarly, this rule marks 'ping' replies.</para>
+      </listitem>
+
+      <listitem>
+        <para>Remember that even though 'ping' packets were marked in one of
+        the first two rules, they are still passed on to rule 3. That rule
+        moves the connection mark to the packet mark, <emphasis>if the packet
+        mark is still zero</emphasis> (note the '0' in the TEST column).
+        Without the '0' in the TEST column, this rule would overwrite the
+        marks assigned in the first two rules.</para>
+      </listitem>
+
+      <listitem>
+        <para>If the packet mark is non-zero (note the '!0' in the TEST
+        column), then exit — The remaining rules will not be executed in this
+        case. The packet mark will be non-zero if this is a 'ping' packet, or
+        if the connection mark restored in rule 3 was non-zero.</para>
+      </listitem>
+
+      <listitem>
+        <para>The packet mark is still zero. This rule checks to see if this
+        is a P2P packet and if it is, the packet mark is set to 4.</para>
+      </listitem>
+
+      <listitem>
+        <para>If the packet mark is non-zero (meaning that it was set to 4 in
+        rule 5), then save the value (4) in the connection. The next time that
+        a packet from this same connection comes through this program, rule 4
+        will be executed and the P2P check will be avoided.</para>
+      </listitem>
+    </orderedlist>
+  </section>
+
   <section>
     <title>Examining the Marking Programs on a Running System</title>
 
     <para>You can see the tcrules in action using the <command>shorewall show
-    mangle</command> command. </para>
+    mangle</command> command.</para>
 
     <para>The sample output from that command shown below has the following in
     <filename>/etc/shorewall/providers</filename>:</para>