From c7352303f4e89245bccb8cbc169acf907c635109 Mon Sep 17 00:00:00 2001 From: Tom Eastep Date: Mon, 4 May 2009 13:14:25 -0700 Subject: [PATCH] Clean up documentation --- Shorewall/releasenotes.txt | 15 +++--- manpages/shorewall-tcclasses.xml | 12 ++++- manpages/shorewall-tcrules.xml | 86 +++++++++++++++++++++++++----- manpages6/shorewall6-tcclasses.xml | 35 ------------ manpages6/shorewall6-tcrules.xml | 51 +----------------- 5 files changed, 91 insertions(+), 108 deletions(-) diff --git a/Shorewall/releasenotes.txt b/Shorewall/releasenotes.txt index ef8a0e1e5..74426c3b0 100644 --- a/Shorewall/releasenotes.txt +++ b/Shorewall/releasenotes.txt @@ -537,15 +537,16 @@ None. Example: - IPMARK(dst, 0XFF00, 0x8000,8) + IPMARK(src,0xff,0x10100) Destination IP address is 192.168.4.3 = 0xc0a80403 - 0xc0a80403 LAND 0xFF00 = 0x0400 - 0x0400 LOR 0x80 = 0x8400 - 0x8400 >> 8 = 0x84 + 0xc0a80403 >> 0 = 0xc0a80403 + 0xc0a80403 LAND 0xFF = 0x03 + 0x03 LOR 0x10100 = 0x10103 - Mark = 0x84 = 132 + So the mark value is 0x10103 which corresponds to class id + 1:103. It is important to realize that, while class IDs are composed of a and a value, the set of values must be unique. That @@ -559,8 +560,8 @@ None. might be to use IPMARK(src,0xFF,0x10000) so as to produce class IDs 1:1 through 1:6. But 1:1 is an invalid class ID since the and classes are equal. So you might chose instent to use - IPMARK(src,0xFF,0x10100) so that all of your classes will - have a value > 256. + IPMARK(src,0xFF,0x10100) as shown in the example above so that all + of your classes will have a value > 256. The 'occurs' option in /etc/shorewall/tcclasses causes the class definition to be replicated many times. The synax is: diff --git a/manpages/shorewall-tcclasses.xml b/manpages/shorewall-tcclasses.xml index 31abf0163..c9b6e671d 100644 --- a/manpages/shorewall-tcclasses.xml +++ b/manpages/shorewall-tcclasses.xml @@ -299,7 +299,7 @@ number rules. Each rule has a successively class number and mark value. - When 'occurs' is used: + When 'occurs' is used: @@ -315,12 +315,20 @@ The class may not have any 'tos=' options (including 'tcp-ack'). + + + The class should not specify a MARK value. If one is + specified, it will be ignored with a warning + message. + 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 - number. + number. For additional information, see + tcrules + (5). diff --git a/manpages/shorewall-tcrules.xml b/manpages/shorewall-tcrules.xml index f9bdad456..52e543ab7 100644 --- a/manpages/shorewall-tcrules.xml +++ b/manpages/shorewall-tcrules.xml @@ -299,31 +299,89 @@ SAME $FW 0.0.0.0/0 tcp 80,443 '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 mask1 then - LORed with mask2. The - result is then shifted shift bits to the - right. + address is first shifted to the right by + shift bits. The result is then LANDed with + mask1 then LORed with + mask2. + + In a sense, the IPMARK target is more like an IPCLASSIFY + target in that the mark value is later interpreted as a class + ID. A packet mark is 32 bits wide; so is a class ID. The + <major> class occupies the high-order 16 bits and the + <minor> class occupies the low-order 16 bits. So the class + ID 1:4ff (remember that class IDs are always in hex) is + equivalent to a mark value of 0x104ff. Remember that Shorewall + uses the interface number as the <major> number where the + first interface in tcdevices has <major> number 1, the + second has <major> number 2, and so on. + + The IPMARK target 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. The syntax is as follows: + +
+ [([{|}][,[mask1][,[mask2][,[shift]]]])] +
+ + Default values are: + + + + + mask1 = 0xFF + + mask2 = 0x00 + + shift = 0 + + + and specify + whether the mark is to be based on the source or destination + address respectively. The selected address is first shifted + right by shift, then LANDed with + mask1 and then LORed with + mask2. The + shift argument is intended to be used + primarily with IPv6 addresses. Example:
- - IPMARK(dst, 0XFF00, 0x8000,8) - - Destination IP address is 192.168.4.3 = - 0xc0a80103 - Meaning: + IPMARK(src,0xff,0x10100) - 0xc0a80403 LAND 0xFF00 = 0x0400 + Suppose that the source IP address is 192.168.4.3 = + 0xc0a80403; then - 0x0400 LOR 0x80 = 0x8400 + 0xc0a80403 >> 0 = 0xc0a80403 - 0x8400 >> 8 = 0x84 + 0xc0a80403 LAND 0xFF = 0x03 - Mark = 0x84 = 132 + 0x03 LOR 0x0x10100 = 0x10103 or class ID + 1:103
+ + It is important to realize that, while class IDs are + composed of a major and a + minor value, the set of values must + be unique. That is, the same numeric value cannot be used as + both a major and a <minor> + number for the same interface unless class nesting occurs (which + is not currently possible with Shorewall). You should keep this + in mind when deciding how to map IP addresses to class + IDs. + + For example, suppose that your internal network is + 192.168.1.0/29 (host IP addresses 192.168.1.1 - 192.168.1.6). + Your first notion might be to use IPMARK(src,0xFF,0x10000) so as + to produce class IDs 1:1 through 1:6. But 1:1 is an invalid + class ID since the major and + minor classes are equal. So you might + chose instent to use IPMARK(src,0xFF,0x10100) as in the example + above so that all of your minor + classes will have a value > 256. diff --git a/manpages6/shorewall6-tcclasses.xml b/manpages6/shorewall6-tcclasses.xml index f330e386c..4eefbe800 100644 --- a/manpages6/shorewall6-tcclasses.xml +++ b/manpages6/shorewall6-tcclasses.xml @@ -287,41 +287,6 @@ - - - occurs=number - - - Typically used with an IPMARK entry in tcrules. Causes - the rule to be replicated for a total of - number rules. Each rule has a - successively class number and mark value. - - When 'occurs' is used: - - - - The associated device may not have the 'classify' - option. - - - - The class may not be the default class. - - - - The class may not have any 'tos=' options (including - 'tcp-ack'). - - - - 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 - number. - - diff --git a/manpages6/shorewall6-tcrules.xml b/manpages6/shorewall6-tcrules.xml index a050981bd..f0b894e69 100644 --- a/manpages6/shorewall6-tcrules.xml +++ b/manpages6/shorewall6-tcrules.xml @@ -50,10 +50,7 @@ role="bold">SAVE[/mask]|CONTINUE|COMMENT|IPMARK[([(src|dst}][,[mask1][,[mask2][,[shift]]]]])]}[COMMENT}[:{C|F|P|T|CF|To stop the comment from being attached to further rules, simply include COMMENT on a line by itself. - - - IPMARK ‒ 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: - - - src - - mask1 = 0xFF - - mask2 = 0x00 - - shift = 0 - - - '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 mask1 then - LORed with mask2. The - result is then shifted shift bits to the - right. - - Example: - -
- - IPMARK(dst, 0XFF00, 0x8000,8) - - Destination IP address is 192.168.4.3 = - 0xc0a80103 - Meaning: - - - 0xc0a80403 LAND 0xFF00 = 0x0400 - - 0x0400 LOR 0x80 = 0x8400 - - 0x8400 >> 8 = 0x84 - - Mark = 0x84 = 132 - -
-