diff --git a/docs/Documentation_Index.xml b/docs/Documentation_Index.xml
index 2a43dda11..c9fc355e9 100644
--- a/docs/Documentation_Index.xml
+++ b/docs/Documentation_Index.xml
@@ -152,8 +152,7 @@
Ipsets
- Shorewall
- Lite
+ Samba
@@ -162,8 +161,8 @@
Kazaa
Filtering
- Shorewall Setup
- Guide
+ Shorewall
+ Lite
@@ -172,7 +171,8 @@
Kernel
Configuration
- SMB
+ Shorewall Setup
+ Guide
@@ -182,8 +182,7 @@
Limiting per-IPaddress
Connection Rate
- Squid with
- Shorewall
+ SMB
@@ -192,9 +191,8 @@
Logging
- Starting/stopping the
- Firewall
+ Squid with
+ Shorewall
@@ -203,8 +201,9 @@
Macros
- Static (one-to-one)
- NAT
+ Starting/stopping the
+ Firewall
@@ -214,7 +213,8 @@
MAC
Verification
- Support
+ Static (one-to-one)
+ NAT
@@ -224,8 +224,7 @@
Multiple Internet Connections
from a Single Firewall
- Traffic
- Accounting
+ Support
@@ -235,8 +234,8 @@
Multiple Zones Through One
Interface
- Traffic
- Shaping/QOS
+ Traffic
+ Accounting
@@ -246,8 +245,8 @@
My Shorewall
Configuration
- Troubleshooting
+ Traffic
+ Shaping/QOS
@@ -257,7 +256,8 @@
Netfilter
Overview
- UPnP
+ Troubleshooting
@@ -266,8 +266,7 @@
Network Mapping
- Upgrade
- Issues
+ UPnP
@@ -276,7 +275,8 @@
One-to-one NAT (Static
NAT)
- VPN
+ Upgrade
+ Issues
@@ -285,8 +285,7 @@
OpenVPN
- White List
- Creation
+ VPN
@@ -296,14 +295,25 @@
Operating
Shorewall
- Xen - The way that I use
- it
+ White List
+ Creation
Extension
Scripts (User Exits)
+ Packet
+ Marking
+
+ Xen - The way that I use
+ it
+
+
+
+ Fallback/Uninstall
+
Packet Processing in a
Shorewall-based Firewall
@@ -311,19 +321,10 @@
Dom0
-
- Fallback/Uninstall
-
- 'Ping' Management
-
-
-
-
FAQs
- Port Information
+ 'Ping' Management
@@ -332,8 +333,7 @@
Features
- Port Knocking and Other Uses
- of the 'Recent Match'
+ Port Information
@@ -342,7 +342,8 @@
Forwarding Traffic on the
Same Interface
- PPTP
+ Port Knocking and Other Uses
+ of the 'Recent Match'
@@ -350,7 +351,7 @@
FTP and Shorewall
- Proxy ARP
+ PPTP
@@ -359,8 +360,7 @@
Getting help or answers to
questions
- Release
- Model
+ Proxy ARP
@@ -369,6 +369,15 @@
Installation/Upgrade
+ Release
+ Model
+
+
+
+
+
+ IPP2P
+
Requirements
@@ -376,7 +385,7 @@
- IPP2P
+ IPSEC
Routing and
Shorewall
@@ -384,20 +393,12 @@
-
- IPSEC
-
- Routing on One
- Interface
-
-
-
-
IPSEC using Kernel 2.6 and
Shorewall 2.1 or Later
- Samba
+ Routing on One
+ Interface
diff --git a/docs/PacketMarking.xml b/docs/PacketMarking.xml
new file mode 100644
index 000000000..7c4d906ae
--- /dev/null
+++ b/docs/PacketMarking.xml
@@ -0,0 +1,455 @@
+
+
+
+
+
+
+ Packet Marking using /etc/shorewall/tcrules
+
+
+
+ Tom
+
+ Eastep
+
+
+
+
+
+
+ 2006
+
+ Thomas M. Eastep
+
+
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License, Version
+ 1.2 or any later version published by the Free Software Foundation; with
+ no Invariant Sections, with no Front-Cover, and with no Back-Cover
+ Texts. A copy of the license is included in the section entitled
+ GNU Free Documentation
+ License
.
+
+
+
+
+ This article includes information that applies to Shorewall version
+ 3.2.5 and later. Not all features described here will be available in
+ earlier releases.
+
+
+
+ Packet and Connection Marks
+
+ Perhaps no aspect of Shorewall causes more confusion than packet
+ marking. This article will attempt to clear up some of that
+ confusion.
+
+ Each packet has a mark whose value is initially 0. Mark values are
+ stored in the skb (socket buffer) structure used by
+ the Linux kernel to track packets; the mark value is not part of the
+ packet itself and cannot be seen with tcpdump,
+ ethereal or any other packet sniffing program.
+
+ Each active connection (even those that are not yet in ESTABLISHED
+ state) has a mark value that is distinct from the packet marks. Connection
+ mark values can be seen using the shorewall show
+ connections command. The default connection mark value is
+ 0.
+
+ Example (output has been folded for display ):
+
+ shorewall show connections
+Shorewall 3.3.2 Connections at gateway - Mon Oct 2 09:08:18 PDT 2006
+
+tcp 6 19 TIME_WAIT src=206.124.146.176 dst=192.136.34.98 sport=58597 dport=80
+ packets=23 bytes=4623 src=192.136.34.98 dst=206.124.146.176 sport=80 dport=58597
+ packets=23 bytes=22532 [ASSURED] mark=256 use=1
+…
+
+ Packet marks are valid only while the packet is being processed by
+ the firewall. Once the packet has been given to a local process or sent on
+ to another system, the packet's mark value is no longer available.
+ Connection mark values, on the other hand, persist for the life of the
+ connection.
+
+
+
+ Packet Marking "Programs"
+
+ Packet marking occurs in Netfilter's mangle
+ table. See the Netfilter
+ Overview article.
+
+ You can think of entries in the tcrules file like instructions in a
+ program coded in a crude assembly language. The program gets executed for
+ each packet.
+
+ That is another way of saying that if you
+ don't program, you may have difficulty making full use of
+ Netfilter/Shorewall's Packet Marking.
+
+ Actually, the tcrules define several programs. Each program
+ corresponds to one of the built-in chains in the mangle table.
+
+
+
+ PREROUTING program — If MARK_IN_FORWARD_CHAIN=No in
+ shorewall.conf, then by default entries in
+ /etc/shorewall/tcrules are part of the PREROUTING
+ program. Entries specifying the ":P" suffix in the MARK column are
+ also part of the PREROUTING program. The PREROUTING program gets
+ executed for each packet entering the firewall.
+
+
+
+ FORWARD program — If MARK_IN_FORWARD_CHAIN=Yes in
+ shorewall.conf, then by default entries in
+ /etc/shorewall/tcrules are part of the FORWARD
+ program. Entries specifying the ":F" suffix in the MARK column are
+ also part of the FORWARD program. The FORWARD program gets executed
+ for each packet forwarded by the firewall.
+
+
+
+ OUTPUT program — Entries with $FW in the SOURCE column are part
+ of the OUTPUT program. The OUTPUT program is executed for each packet
+ originating on the firewall itself.
+
+
+
+ POSTROUTING program — Entries with a class-id in the MARK column
+ (and that don't specify $FW in the SOURCE column) are part of the
+ POSTROUTING program. These rules are executed for each packet leaving
+ the firewall.
+
+
+
+ INPUT program — No entries in tcrules will add entries to this
+ program. It is executed for each packet that is targeted to the
+ firewall itself.
+
+
+
+ Note that a packet being forwarded by your firewall actually gets
+ processed by three different programs: PREROUTING, FORWARD and
+ POSTROUTING. Similarly, packets address to the firewall itself are
+ processed by two programs (PREROUTING and INPUT) while packets originating
+ on the firewall are likewise processed by two programs (OUTPUT and
+ POSTROUTING).
+
+ Rules in each program are executed as
+ follows:
+
+
+
+ Rules are conditionally executed based on whether the current
+ packet matches the contents of the SOURCE, DEST, PROTO, PORT(S),
+ CLIENT PORT(S_, USER, TEST, LENGTH and TOS columns.
+
+
+
+ When a rule is executed, either:
+
+
+
+ the current packet receives a new mark value; or
+
+
+
+ the connection to which the current packet belongs receives
+ a new mark value (":C", ":CF" or ":CP" suffix in the MARK column);
+ or
+
+
+
+ the packet is classified for traffic shaping (class-id in
+ the MARK column); or
+
+
+
+ the packet mark in the current packet is moved to the
+ connection mark for the connection that the current packet is part
+ of ("SAVE" in the MARK column); or
+
+
+
+ the connection mark value for the connection that the
+ current packet is part of is moved to the current packet's mark
+ ("RESTORE" in the MARK column); or
+
+
+
+ jump to a subroutine (another chain in the mangle table).
+ These jumps are generated by Shorewall; or
+
+
+
+ exit the current subroutine ("CONTINUE" in the MARK
+ column).
+
+
+
+
+
+ Unless the subroutine is exited using CONTINUE, the current packet is always passed to the next tcrule in
+ the subroutine.
+
+
+
+
+
+ Mark and Mask Values
+
+ The mark value is held in a 32-bit field. Because packet marking is
+ the Netfilter kludge of last resort for solving many
+ hard technical problems, Shorewall reserves half of this field (16 bits)
+ for future use. The remainder is split into two 8-bit values:
+
+
+
+ The low-order eight bits are used for traffic shaping marks.
+ These eight bits are also used for selecting among multiple providers
+ when HIGH_ROUTE_MARKS=No in shorewall.conf. Some
+ rules that deal with only these bits use a mask value of 0xff.
+
+
+
+ The next 8 bits are used for selecting among multiple providers
+ when HIGH_ROUTE_MARKS=Yes in shorewall.conf.
+ These bits are manipulated using a mask value of 0xff00.
+
+
+
+ As hinted above, marking rules can specify both a mark value and a
+ mask. The mask determines the subset of the 32 bits in the mark are to be
+ used in the operation — only those bits that are on in the mask are
+ manipulated when the rule is executed. For entries in tcrules,
+ Shorewall-generated rules use a mask value that depends on which program
+ the rule is part of, what the rule does, and the setting of
+ HIGH_ROUTE_MARKS.
+
+ For entries in tcrules, the default mask value is 0xffff except in
+ these cases:
+
+
+
+ RESTORE rules use a default mask value of 0xff.
+
+
+
+ SAVE rules use a default mask value of 0xff.
+
+
+
+
+
+ Shorewall-defined Chains in the Mangle Table
+
+ Shorewall creates a set of chains in the mangle table to hold rules
+ defined in your /etc/shorewall/tcrules file. As
+ mentioned above, chains are like subroutines in the packet marking
+ programming language. By placing all of your rules in subroutines,
+ CONTINUE (which generates a Netfilter RETURN rule) can be used to stop
+ processing your rules while still allowing following Shorewall-generated
+ rules to be executed.
+
+
+
+ tcpre
+
+
+ PREROUTING rules.
+
+
+
+
+ tcfor
+
+
+ FORWARD rules.
+
+
+
+
+ tcout
+
+
+ OUTPUT rules.
+
+
+
+
+ tcpost
+
+
+ POSTROUTING rules.
+
+
+
+
+ Shorewall generates jumps to these chains from the built-in chains
+ (PREROUTING, FORWARD, etc.).
+
+
+
+ Examining the Marking Programs on a Running System
+
+ You can see the tcrules in action using the shorewall show
+ mangle command.
+
+ The sample output from that command shown below has the following in
+ /etc/shorewall/providers:
+
+ #NAME NUMBER MARK DUPLICATE INTERFACE GATEWAY OPTIONS COPY
+Blarg 1 0x100 main eth3 206.124.146.254 track,balance br0,eth1
+#LAST LINE -- ADD YOUR ENTRIES ABOVE THIS LINE -- DO NOT REMOVE
+
+
+ Here is /etc/shorewall/tcrules:
+
+ #MARK SOURCE DEST PROTO PORT(S) CLIENT USER TEST
+# PORT(S)
+1:110 192.168.0.0/22 eth3 #Our internel nets get priority
+ #over the server
+1:130 206.124.146.177 eth3 tcp - 873
+#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+
+ And here is /etc/shorewall/tcdevices and
+ /etc/shorewall/tcclasses:
+
+ #INTERFACE IN-BANDWITH OUT-BANDWIDTH
+eth3 1.3mbit 384kbit
+#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+#INTERFACE MARK RATE CEIL PRIORITY OPTIONS
+eth3 10 full full 1 tcp-ack,tos-minimize-delay
+eth3 20 9*full/10 9*full/10 2 default
+eth3 30 6*full/10 6*full/10 3
+#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
+
+
+ I've annotated the following output with comments beginning with
+ "<<<<" and ending with ">>>>". This example uses
+ HIGH_ROUTE_MARKS=Yes and TC_EXPERT=No in
+ shorewall.conf.
+
+ gateway:~ # shorewall show mangle
+Shorewall 3.3.2 Mangle Table at gateway - Mon Oct 2 15:07:32 PDT 2006
+
+Counters reset Mon Oct 2 07:49:52 PDT 2006
+
+<<<< The PREROUTING Program >>>>
+
+Chain PREROUTING (policy ACCEPT 409K packets, 122M bytes)
+ pkts bytes target prot opt in out source destination
+
+<<<< Restore the provider mark from the connection, if any >>>>
+
+ 185K 77M CONNMARK all -- * * 0.0.0.0/0 0.0.0.0/0 CONNMARK match !0x0/0xff00 CONNMARK restore mask 0xff00
+
+<<<< If there is no mark in the connection and the packet came in on eth3, then jump to the routemark chain
+ This rule is generated as a result of 'track' being specified in the providers file entry for eth3 >>>>
+
+ 8804 1396K routemark all -- eth3 * 0.0.0.0/0 0.0.0.0/0 MARK match 0x0/0xff00
+
+<<<< If the packet came in on eth3, jump the the tcpre chain -- packets entering on a 'track'ed interface can have their mark set to zero there >>>>
+
+ 102K 52M tcpre all -- eth3 * 0.0.0.0/0 0.0.0.0/0
+
+<<<< Otherwise, jump to the tcpre chain if there is no current provider mark --
+ if we would have had TC_EXPERT=Yes, this jump would have been unconditional>>>>
+
+ 215K 44M tcpre all -- * * 0.0.0.0/0 0.0.0.0/0 MARK match 0x0/0xff00
+
+<<<< End of PREROUTING program >>>>
+
+<<<< INPUT Program -- Shorewall generates the single rule here which turns off the provider mark in the packet after routing
+ The rule does that by logically ANDing the mark value with 0xff which will turn off all but the low-order 8 bits >>>>
+
+Chain INPUT (policy ACCEPT 98238 packets, 16M bytes)
+ pkts bytes target prot opt in out source destination
+98234 16M MARK all -- * * 0.0.0.0/0 0.0.0.0/0 MARK and 0xff
+
+<<<< End of INPUT program >>>>
+
+<<<< FORWARD Program -- Shorewall generates the first rule here which turns off the provider mark in the packet after routing >>>>
+
+Chain FORWARD (policy ACCEPT 312K packets, 106M bytes)
+ pkts bytes target prot opt in out source destination
+ 312K 106M MARK all -- * * 0.0.0.0/0 0.0.0.0/0 MARK and 0xff
+
+<<<< Jump unconditionally to the tcfor chain >>>>
+
+ 312K 106M tcfor all -- * * 0.0.0.0/0 0.0.0.0/0
+
+<<<< End of FORWARD program >>>>
+
+<<<< OUTPUT Program >>>>
+
+Chain OUTPUT (policy ACCEPT 1462K packets, 396M bytes)
+ pkts bytes target prot opt in out source destination
+
+<<<< Restore the provider mark from the connection -- this rule was generated by Shorewall because of the 'track' option >>>>
+
+ 3339 615K CONNMARK all -- * * 0.0.0.0/0 0.0.0.0/0 CONNMARK match !0x0/0xff00 CONNMARK restore mask 0xff00
+
+<<<< If there is no provider mark, then jump to the tcout chain --
+ if we would have had TC_EXPERT=Yes, this jump would have been unconditional >>>>
+
+92747 28M tcout all -- * * 0.0.0.0/0 0.0.0.0/0 MARK match 0x0/0xff00
+
+<<<< End of FORWARD program >>>>
+
+<<<< POSTROUTING Program -- Unconditionally jump to the tcpost chain >>>>
+
+Chain POSTROUTING (policy ACCEPT 407K packets, 135M bytes)
+ pkts bytes target prot opt in out source destination
+ 407K 135M tcpost all -- * * 0.0.0.0/0 0.0.0.0/0
+
+<<<< End of FORWARD program >>>>
+
+Chain routemark (1 references)
+ pkts bytes target prot opt in out source destination
+
+<<<< Set connection 'track' mark for packets coming in on eth3 >>>>
+
+ 8804 1396K MARK all -- eth3 * 0.0.0.0/0 0.0.0.0/0 MARK or 0x100
+
+<<<< Save any mark added above in the connection mark >>>>
+
+ 8804 1396K CONNMARK all -- * * 0.0.0.0/0 0.0.0.0/0 MARK match !0x0/0xff00 CONNMARK save mask 0xff00
+
+Chain tcfor (1 references)
+ pkts bytes target prot opt in out source destination
+
+Chain tcout (1 references)
+ pkts bytes target prot opt in out source destination
+
+Chain tcpost (1 references)
+ pkts bytes target prot opt in out source destination
+
+<<<< The next two rules are the entries in the /etc/shorewall/tcrules file >>>>
+
+65061 11M CLASSIFY all -- * eth3 192.168.0.0/22 0.0.0.0/0 CLASSIFY set 1:110
+ 2224 2272K CLASSIFY tcp -- * eth3 206.124.146.177 0.0.0.0/0 tcp spt:873 CLASSIFY set 1:130
+
+<<<< These rules are generated by Shorewall and classify the traffic according to the marks in /etc/shorewall/classes >>>>
+
+ 0 0 CLASSIFY all -- * eth3 0.0.0.0/0 0.0.0.0/0 MARK match 0xa/0xff CLASSIFY set 1:110
+ 0 0 CLASSIFY all -- * eth3 0.0.0.0/0 0.0.0.0/0 MARK match 0x14/0xff CLASSIFY set 1:120
+ 0 0 CLASSIFY all -- * eth3 0.0.0.0/0 0.0.0.0/0 MARK match 0x1e/0xff CLASSIFY set 1:130
+
+Chain tcpre (2 references)
+ pkts bytes target prot opt in out source destination
+gateway:~ #
+
+
\ No newline at end of file
diff --git a/docs/traffic_shaping.xml b/docs/traffic_shaping.xml
index 778163591..35e270fbc 100644
--- a/docs/traffic_shaping.xml
+++ b/docs/traffic_shaping.xml
@@ -464,7 +464,9 @@ ppp0 6000kbit 500kbit
The fwmark classifier provides a convenient way to classify
packets for traffic shaping. The /etc/shorewall/tcrules
- file is used for specifying these marks in a tabular fashion.
+ file is used for specifying these marks in a tabular fashion. For an
+ in-depth look at the packet marking facility in Netfilter/Shorewall,
+ please see this article.
Normally, packet marking occurs in the PREROUTING chain before any
address rewriting takes place. This makes it impossible to mark inbound