holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity

merge arne bernin docs for TS

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@2820 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
judas_iscariote 2005-10-06 23:29:16 +00:00
parent cc6caadf41
commit 1974e95454
1 changed files with 476 additions and 381 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

865
Shorewall-docs2/traffic_shaping.xml
View File

@ -13,108 +13,507 @@
<surname>Eastep</surname>
</author>
<author>
<firstname>Arne</firstname>
<surname>Bernin</surname></author>
</authorgroup>
<pubdate>2005-09-12</pubdate>
<pubdate>2005-10-07</pubdate>
<copyright>
<year>2001-2005</year>
<year>2001-2004</year>
<holder>Thomas M. Eastep</holder>
</copyright>
<copyright>
<year>2005</year>
<holder>Arne Bernin</holder>
</copyright>
<legalnotice>
<para>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
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation License</ulink></quote>.</para>
</legalnotice>
</articleinfo>
<section>
<title>Introduction</title>
<para>Shorewall does not do any type of Traffic Shaping/Bandwidth
management itself but it does contain some facilities to intergrate with
traffic shaping/control solutions. In order to use traffic shaping with
Shorewall, it is essential that you get a copy of the <ulink
url="http://ds9a.nl/lartc">Linux Advanced Routing and Shaping
HOWTO</ulink>, version 0.3.0 or later or <ulink
url="http://www.tldp.org/HOWTO/Traffic-Control-HOWTO/">The Traffic Control
HOWTO</ulink>. It is also necessary to be running Linux Kernel 2.4.18 or
later. Shorewall traffic shaping support consists of the following:</para>
<para>Starting with Version 2.5.5, shorewall has builtin support for traffic shaping
and control. Before this version, the support was quite limited. You were able
to use your own tcstart script (and you still are), but besides the tcrules file
it was not possible to define classes or queueing discplines inside the shorewall
config files.</para>
<para>The support for traffic shaping and control still does not cover all
options available (and especially all algorithms that can be used to queue traffic)
for the Linux kernel but it should fit most needs.
If you are using your own script for traffic control und you still want to use it rather
the builtin support in the future, you will find information on how to do this,
<link linkend="owntcstart">later in this document</link>. But for this to work,
you will also need to enable traffic shaping in the kernel and shorewall as
covered by the next sections.</para>
</section>
<section>
<title>Linux traffic shaping and control</title>
<para>This section gives a brief introduction of how controlling traffic with
the linux kernel works. Although this might be enough for configuring it in
the shorewall configuration files, it still might be a good idea to take a
deeper look into the <ulink url="http://ds9a.nl/lartc">Linux Advanced Routing and Shaping HOWTO</ulink>.
At the time of writing this, the current version is 1.0.0. </para>
<para>Since kernel 2.2 Linux has extensive support for controlling traffic. You can define different
algorithms that are used to queue the traffic before it leaves an interface. The standard one is called
pfifo and is (as the name suggests) of the type First In First out. This means, that it does not shape
anything, if you have a connection that eats up all your bandwidth, this qeueing algorithm will not
stop it from doing so.</para>
<para> For shorewall traffic shaping we use two algorithms, one is called HTB (Hierarchical
Token Bucket) and SFQ (Stochastic Fairness Queuing). SFQ is easy to explain: it just tries to track
your connections (tcp or udp streams) and balances the traffic between them. This normaly works ok.
HTB allows you to define a set of classes, and you can put the traffic you want into these classes.
You can define minimum and maximum bandwitdh settings for those classes and order the hierachically (the less
priorized classes only get bandwitdth if the more important have what they need).
Shorewall builtin traffic shaping allows you to define these classes (and their bandwidth limits), and it
uses SFW inside these classes to make sure, that different data streams are handled equally.</para>
<para>You can only shape outgoing traffic. The reason for this is simple,
the packets were already received by your network card before you can
decide what to do with them. So the only choice would be to drop them
which does normally makes no sense (since you received the packet already,
it went through the possible bottleneck (the incoming connection).
The next possible bottleneck might come if the packet leaves on another
interface, so this will be the place where queuing might occur. So,
defining queues for incoming packages is not very useful, you just want
to have it forwarded to the outgoing interface as fast as possible.</para>
<para>There is one exception, though. Limiting incoming traffic to a value
a bit slower than your actual line speed will avoid queuing on the other
end of that connection. This is mostly useful if you don't have access
to traffic control on the other side and if this other side has a
faster network connection than you do (the line speed between the systems
is the bottleneck, e.g. a DSL connection to you providers router).
So, if you drop packages that are coming in too fast, the underlaying
protocol might recognize this and slow down the connection. TCP has a
builtin mechanism for this, UDP has not (but the protocol over UDP might
recognize it , if there is any).</para>
<para>The reason why qeueing is bad in these cases is, that you might have
packets which need to be priorized over others, e.g. VoIP or ssh. For
this type of connections it is important that packets arrive in a certain
amount of time. For others like http downloads, it does not really
matter if it takes a few seconds more.</para>
<para>If you have a large queue on the other side and the router there does
not care about QoS or the QoS bits are not set properly, your
important packets will go into the same queue as your less timecritical
download packets which will result in a large delay.</para>
</section>
<section>
<title>Linux Kernel Configuration</title>
<para>You will need at least kernel 2.4.18 for this to work,
please take a look at the following screenshot for what settings you need
to enable. For builtin support, you need the HTB scheduler, the PRIO
pseudoscheduler and SFQ queue. The other scheduler or queue algorithms are
not needed.</para>
<para>This screen shot show how I&#39;ve configured QoS in my Kernel:<graphic fileref="images/QoS.png" align="center"/></para>
</section>
<section>
<title>Enable TC support in shorewall</title>
<para>You need this support whether you use the builtin support or
whether you provide your own tcstart script.</para>
<para>To enable general support for traffic shaping and control in shorewall,
you have to do the following:</para>
<itemizedlist>
<listitem>
<para>A new <emphasis role="bold">TC_ENABLED</emphasis> parameter in
/etc/shorewall.conf.</para>
<para>Set <emphasis role="bold">TC_ENABLED</emphasis> to Yes in /etc/shorewall/shorewall.conf</para>
</listitem>
<listitem>
<para>A new <emphasis role="bold">CLEAR_TC</emphasis> parameter in
/etc/shorewall.conf (Added in Shorewall 1.3.13). When Traffic Shaping
is enabled (TC_ENABLED=Yes), the setting of this variable determines
whether Shorewall clears the traffic shaping configuration during
Shorewall [re]start and Shorewall stop.</para>
<para>Setting <emphasis role="bold">CLEAR_TC</emphasis> parameter in
/etc/shorewall/shorewall.conf to Yes will clear the traffic shaping
configuration during Shorewall [re]start and Shorewall stop.
This is normally what you want when using the builtin support (and
also if you use your own tcstart script)</para>
</listitem>
<listitem>
<para><emphasis role="bold">/etc/shorewall/tcrules</emphasis> - A file
where you can specify firewall marking of packets. The firewall mark
value may be used to classify packets for traffic
shaping/control.</para>
</listitem>
<listitem>
<para><emphasis role="bold">/etc/shorewall/tcstart </emphasis>- A
user-supplied file that is sourced by Shorewall during
<quote>shorewall start</quote> and which you can use to define your
traffic shaping disciplines and classes. I have provided a <ulink
url="ftp://ftp.shorewall.net/pub/shorewall/cbq">sample</ulink> that
does table-driven CBQ shaping but if you read the traffic shaping
sections of the HOWTO mentioned above, you can probably code your own
faster than you can learn how to use my sample. I personally use
<ulink url="http://luxik.cdi.cz/%7Edevik/qos/htb/">HTB</ulink> (see
below). HTB support may eventually become an integral part of
Shorewall since HTB is a lot simpler and better-documented than CBQ.
As of 2.4.20, HTB is a standard part of the kernel but iproute2 must
be patched in order to use it.</para>
<para>In tcstart, when you want to run the <quote>tc</quote> utility,
use the run_tc function supplied by shorewall if you want tc errors to
stop the firewall.</para>
<para>You can generally use off-the-shelf traffic shaping scripts by
simply copying them to /etc/shorewall/tcstart. I use <ulink
url="http://lartc.org/wondershaper/">The Wonder Shaper </ulink>(HTB
version) that way (i.e., I just copied wshaper.htb to
/etc/shorewall/tcstart and modified it according to the Wonder Shaper
README). <emphasis role="bold">WARNING</emphasis>: If you use use
Masquerading or SNAT (i.e., you only have one external IP address)
then listing internal hosts in the NOPRIOHOSTSRC variable in the
wshaper[.htb] script won't work. Traffic shaping occurs after SNAT has
already been applied so when traffic shaping happens, all outbound
traffic will have as a source address the IP addresss of your
firewall's external interface.</para>
</listitem>
<listitem>
<para><emphasis role="bold">/etc/shorewall/tcclear</emphasis> - A
user-supplied file that is sourced by Shorewall when it is clearing
traffic shaping. This file is normally not required as Shorewall's
method of clearing qdisc and filter definitions is pretty
general.</para>
<para>The other steps that follow depend on whether you use your own script
or the builtin solution. They will be explained in the following sections.</para>
</listitem>
</itemizedlist>
<para>Shorewall allows you to start traffic shaping when Shorewall itself
starts or it allows you to bring up traffic shaping when you bring up your
interfaces.</para>
<para>To start traffic shaping when Shorewall starts:</para>
</section>
<section>
<title>Using builtin traffic shaping/control</title>
<para>For defining bandwidths (for either devices or classes) please
use kbit or kbps(for Kilobytes per second) and make sure there
is NO space between the number and the unit (100kbit not 100 kbit).
You generally could use mbit or mbps or just Bytes, but i suggest
to use kbit, as values lether than 1 are not supported (NO 0.5mbit).
</para>
<para>To properly configure the settings for your devices you might
need to find out, the real up- and downstream rates you have. This
is especially the case, if you are using a DSL connection or one
of another type that do not have a guaranteed bandwidth. There
are several online tools that help you find out, try .....
Don't trust the values your provider tells you for this, especially
measuring the real download speed is important!
</para>
<section>
<title>/etc/shorewall/tcrules</title>
<para>The fwmark classifier provides a convenient way to classify packets
for traffic shaping. The /etc/shorewall/tcrules file provides a means for
specifying these marks in a tabular fashion.</para>
<para>Normally, packet marking occurs in the PREROUTING chain before any
address rewriting takes place. This makes it impossible to mark inbound
packets based on their destination address when SNAT or Masquerading are
being used. You can cause packet marking to occur in the FORWARD chain
by using the MARK_IN_FORWARD_CHAIN option in shorewall.conf.</para>
<para>Columns in the file are as follows:</para>
<itemizedlist>
<listitem>
<para>MARK - Specifies the mark value is to be assigned in case of a
match. This is an integer in the range 1-255. This value may be optionally
followed by
<quote>:</quote> and either <quote>F</quote> or <quote>P</quote> to
designate that the marking will occur in the FORWARD or PREROUTING
chains respectively. If this additional specification is omitted, the
chain used to mark packets will be determined by the setting of the
MARK_IN_FORWARD_CHAIN option in shorewall.conf.</para>
</listitem>
<listitem>
<para>SOURCE - The source of the packet. If the packet originates on
the firewall, place <quote>fw</quote> in this column. Otherwise, this
is a comma-separated list of interface names, IP addresses, MAC
addresses in Shorewall Format and/or Subnets.</para>
<para>Examples <programlisting> eth0 192.168.2.4,192.168.1.0/24</programlisting></para>
</listitem>
<listitem>
<para>DEST -- Destination of the packet. Comma-separated list of IP
addresses and/or subnets.</para>
</listitem>
<listitem>
<para>PROTO - Protocol - Must be the name of a protocol from
/etc/protocol, a number or <quote>all</quote></para>
</listitem>
<listitem>
<para>PORT(S) - Destination Ports. A comma-separated list of Port
names (from /etc/services), port numbers or port ranges (e.g., 21:22);
if the protocol is <quote>icmp</quote>, this column is interpreted as
the destination icmp type(s).</para>
</listitem>
<listitem>
<para>CLIENT PORT(S) - (Optional) Port(s) used by the client. If
omitted, any source port is acceptable. Specified as a comma-separate
list of port names, port numbers or port ranges.</para>
</listitem>
<listitem>
<para>USER (Added in Shorewall version 1.4.10) - (Optional) This
column may only be non-empty if the SOURCE is the firewall itself.
When this column is non-empty, the rule applies only if the program
generating the output is running under the effective user and/or
group. It may contain :</para>
<para>[&#60;user name or number&#62;]:[&#60;group name or number&#62;]</para>
<para>The colon is optionnal when specifying only a user.</para>
<para>Examples : john: / john / :users / john:users</para>
</listitem>
</itemizedlist>
<example>
<title></title>
<para>All packets arriving on eth1 should be marked with 1. All packets
arriving on eth2 and eth3 should be marked with 2. All packets
originating on the firewall itself should be marked with 3.</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL USER/GROUP
1 eth1 0.0.0.0/0 all
2 eth2 0.0.0.0/0 all
2 eth3 0.0.0.0/0 all
3 fw 0.0.0.0/0 all</programlisting>
</example>
<example>
<title></title>
<para>All GRE (protocol 47) packets not originating on the firewall and
destined for 155.186.235.151 should be marked with 12.</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL USER/GROUP
12 0.0.0.0/0 155.182.235.151 47</programlisting>
</example>
<example>
<title></title>
<para>All SSH packets originating in 192.168.1.0/24 and destined for
155.186.235.151 should be marked with 22.</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL USER/GROUP
22 192.168.1.0/24 155.182.235.151 tcp 22</programlisting>
</example>
</section>
<section>
<title>/etc/shorewall/tcdevices</title>
<para>This file allows you to define the incoming and outgoing bandwidth for
the devices you want traffic shaping to be enabled. That means, if you want
to use traffic shaping for a device, you have to define it here.</para>
<para>Columns in the file are as follows:</para>
<itemizedlist>
<listitem>
<para>INTERFACE - Name of interface. Each interface may be listed only
once in this file. You may NOT specify the name of an alias (e.g., eth0:0)
here; see <ulink url="FAQ.htm#faq18">FAQ #18</ulink>. You man NOT specify
wildcards here, e.g. if you have multiple ppp interfaces, you need to put
them all in here!</para>
</listitem>
<listitem>
<para>IN-BANDWIDTH - The incoming Bandwidth of that interface. Please
note that you are not able to do traffic shaping on incoming traffic,
as the traffic is already received before you could do so. This Column allows
you to define the maximum traffic allowed for this interface in total, if
the rate is exceeded, the packets are dropped.
You want this mainly if you have a DSL or Cable Connection to avoid
queuing at your providers side.
If you don't want any traffic to be dropped set this to a value faster
than your interface maximum rate.</para>
</listitem>
<listitem>
<para>OUT-BANDWIDTH - Specifiy the outgoing bandwidth of that interface.
This is the maximum speed your connection can handle. It is also the speed
you can refer as "full" if you define the tc classes. Outgoing traffic above
this rate will be dropped.</para>
</listitem>
</itemizedlist>
<example>
<title></title>
<para>Suppose you are using PPP over Ethernet (DSL) and ppp0 is the interface
for this. The device has an outgoing bandwidth of 500kbit and an incoming bandwidth
of 6000kbit
</para>
<programlisting>#INTERFACE IN-BANDWITH OUT-BANDWIDTH
ppp0 6000kbit 500kbit</programlisting>
</example>
</section>
<section>
<title>/etc/shorewall/tcclasses</title>
<para>This file allows you to define the actual classes that are used to
split the outgoing traffic.</para>
<itemizedlist>
<listitem>
<para>INTERFACE - Name of interface. Each interface may be listed only
once in this file. You may NOT specify the name of an alias (e.g., eth0:0)
here; see <ulink url="FAQ.htm#faq18">FAQ #18</ulink>. You man NOT specify
wildcards here, e.g. if you have multiple ppp interfaces, you need to put
them all in here!</para>
</listitem>
<listitem>
<para>MARK - The mark value which is an integer in the range 1-255. You
define these marks in the tcrules file, marking the traffic you want
to go into the queueing classes defined in here.
You can use the same marks for different Interfaces.</para>
</listitem>
<listitem>
<para>RATE - The minimum bandwidth this class should get, when the traffic load
rises. Please note that first the classes which equal or a lesser priority
value are served even if there are others that have a guaranteed bandwith
but a lower priority.</para>
</listitem>
<listitem>
<para>CEIL - The maximum bandwidth this class is allowed to use when the link
is idle. Useful if you have traffic which can get full speed when more important
services (e.g. interactive like ssh) are not used.
You can use the value "full" in here for setting the maximum bandwidth
to the defined output bandwidth of that interface.</para>
</listitem>
<listitem>
<para>PRIORITY - you have to define a priority for the class. packets
in a class with a higher priority (=lesser value) are handled before less priorized
onces.
You can just define the mark value here also, if you are increasing the mark values
with lesser priority.</para>
</listitem>
<listitem>
<para>OPTIONS - A comma-separated list of options including the following:</para>
<itemizedlist>
<listitem>
<para>default - this is the default class for that interface where all
traffic should go, that is not classified otherwise.</para>
<note><para>defining default for exactly <emphasis role="bold">one</emphasis> class per interface
is mandatory!</para></note>
</listitem>
<listitem>
<para>tos-&lt;tosname&gt; - this lets you define a filter for the
given &lt;tosname&gt; which lets you define a value of the Type Of Service
bits in the ip package which causes the package to go in this class.
Please note, that this filter overrides all mark settings, so if you define
a tos filter for a class all traffic having that mark will go in it
regardless of the mark on the package.
You can use the following for this option:
tos-minimize-delay (16)
tos-maximize-throughput (8)
tos-maximize-reliability (4)
tos-minimize-cost (2)
tos-normal-service (0)
</para>
<note><para>Each of this options is only valid for <emphasis role="bold">one</emphasis> class per
interface.</para>
</note>
</listitem>
<listitem>
<para>tcp-ack - if defined causes an tc filter to be created that
puts all tcp ack packets on that interface that have an size of
&lt;=64 Bytes to go in this class. This is useful for speeding up
downloads. Please note that the size of the ack packages is
limited to 64 bytes as some applications (p2p for example) use
to make every package an ack package which would cause them
all into here. We want only packages WITHOUT payload to match,
so the size limit. Bigger packets just take their normal way
into the classes.</para>
<note>
<para>This option is only valid for <emphasis role="bold">class</emphasis> per interface.</para>
</note>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section>
<title>Real life examples</title>
<section>
<title>Configuration to replace Wondershaper</title>
<para>You are able to fully replace the wondershaper script by using the buitin
traffic control.You can find example configuration files at
<ulink url="http://www1.shorewall.net/pub/shorewall/Samples/tc4shorewall/">"http://www1.shorewall.net/pub/shorewall/Samples/tc4shorewall/</ulink>. Please note that they are just examples and need to be adjusted
to work for you. In this examples it is assumed that your interface for you internet connection is ppp0
(for DSL) , if you use another connection type, you have to change it. You also need to change
the settings in the tcdevices.wondershaper file to reflect your line speed. The relevant lines of
the config files follow here. Please note that this is just an 1:1 replacement doing exactly what
wondershaper should do. You are free to change it...
</para>
<para>tcclasses file</para>
<programlisting>#INTERFACE MARK RATE CEIL PRIORITY OPTIONS
ppp0 1 full full 1 tcp-ack,tos-minimize-delay
ppp0 2 9*full/10 9*full/10 2 default
ppp0 3 8*full/10 8*full/10 2</programlisting>
<para>tcdevices file</para>
<programlisting>#INTERFACE IN-BANDWITH OUT-BANDWIDTH
ppp0 5000kbit 500kbit</programlisting>
<para>tcrules file</para>
<programlisting>#MARK SOURCE DEST PROTO PORT(S) CLIENT USER
# PORT(S)
1:P 0.0.0.0/0 0.0.0.0/0 icmp echo-request
1:P 0.0.0.0/0 0.0.0.0/0 icmp echo-reply
# mark traffic which should have a lower priority with a 3:
# mldonkey
3 0.0.0.0/0 0.0.0.0/0 udp - 4666</programlisting>
<para>
Wondershaper allows you to define a set of hosts and/or ports you want to classify as low priority.
To achieve this , you have to add these hosts to tcrules and set the mark to 3 (true if you use
the example configuration files).
</para>
<para>Setting hosts to low priority</para>
<para>lets assume the following settings from you old wondershaper script (don't assume these
example values are really useful, they are only used for demonstrating):</para>
<programlisting>
# low priority OUTGOING traffic - you can leave this blank if you want
# low priority source netmasks
NOPRIOHOSTSRC="192.168.1.128/25 192.168.3.28"
# low priority destination netmasks
NOPRIOHOSTDST=60.0.0.0/24
# low priority source ports
NOPRIOPORTSRC="6662 6663"
# low priority destination ports
NOPRIOPORTDST="6662 6663"
</programlisting>
<para>This would result in the following additional settings to the tcrules file:</para>
<programlisting>
3 192.168.1.128/25 0.0.0.0/0 all
3 192.168.3.28 0.0.0.0/0 all
3 0.0.0.0/0 60.0.0.0/24 all
3 0.0.0.0/0 0.0.0.0/0 udp 6662,6663
3 0.0.0.0/0 0.0.0.0/0 udp - 6662,6663
3 0.0.0.0/0 0.0.0.0/0 tcp 6662,6663
3 0.0.0.0/0 0.0.0.0/0 tcp - 6662,6663</programlisting>
</section>
</section>
</section>
<section>
<title>Using your own tc script</title>
<section id="owntcstart">
<title>Replacing builtin tcstart file</title>
<para>If you prefer your own tcstart file, just replace /etc/shorewall/tcstart with your own. </para>
<para>In your tcstart script, when you want to run the <quote>tc</quote> utility,
use the run_tc function supplied by shorewall if you want tc errors to
stop the firewall.</para>
<orderedlist>
<listitem>
@ -137,7 +536,9 @@
/etc/shorewall/tcrules.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Traffic control outside shorewall</title>
<para>To start traffic shaping when you bring up your network interfaces,
you will have to arrange for your traffic shaping configuration script to
be run at that time. How you do that is distribution dependent and will
@ -145,325 +546,19 @@
<orderedlist>
<listitem>
<para>Set TC_ENABLED=Yes and CLEAR_TC=No</para>
<para>Set TC_ENABLED=No and CLEAR_TC=No</para>
</listitem>
<listitem>
<para>Do not supply /etc/shorewall/tcstart or /etc/shorewall/tcclear
scripts.</para>
</listitem>
<listitem>
<para>If your tcstart script uses the <quote>fwmark</quote>
<para>If your script uses the <quote>fwmark</quote>
classifier, you can mark packets using entries in
/etc/shorewall/tcrules.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Kernel Configuration</title>
<para>This screen shot show how I've configured QoS in my Kernel:<graphic
align="center" fileref="images/QoS.png" /></para>
</section>
<section>
<title>/etc/shorewall/tcrules</title>
<para>The fwmark classifier provides a convenient way to classify packets
for traffic shaping. The /etc/shorewall/tcrules file provides a means for
specifying these marks in a tabular fashion.</para>
<para>Normally, packet marking occurs in the PREROUTING chain before any
address rewriting takes place. This makes it impossible to mark inbound
packets based on their destination address when SNAT or Masquerading are
being used. Beginning with Shorewall 1.3.12, you can cause packet marking
to occur in the FORWARD chain by using the MARK_IN_FORWARD_CHAIN option in
shorewall.conf.</para>
<important>
<para>Unlike entries in <filename><ulink
url="Documentation.htm#Rules">/etc/shorewall/rules</ulink></filename>,
evaluation of entries in <filename>/etc/shorewall/tcrules</filename>
continues after a match. So the final mark assigned to each packet is
determined by the <emphasis role="bold">last</emphasis> matching entry
in the <filename>/etc/shorewall/tcrules</filename> file.</para>
</important>
<important>
<para>If you use providers (in /etc/shorewall/providers) with the
'track' option then there are restrictions about how you can mark
packets involving those providers; see the <ulink
url="Shorewall_and_Routing.html">Shorewall Routing documentation</ulink>
for details.</para>
</important>
<para>Columns in the file are as follows:</para>
<itemizedlist>
<listitem>
<para>MARK - Specifies the mark value is to be assigned in case of a
match. This is an integer in the range 1-255. Beginning with Shorewall
version 1.3.14, this value may be optionally followed by
<quote>:</quote> and either <quote>F</quote> or <quote>P</quote> to
designate that the marking will occur in the FORWARD or PREROUTING
chains respectively. If this additional specification is omitted, the
chain used to mark packets will be determined by the setting of the
MARK_IN_FORWARD_CHAIN option in shorewall.conf.</para>
<para>This possible values in this field were expanded in Shorewall
version 2.2.0:</para>
<itemizedlist>
<listitem>
<para>If your kernel and iptables include CONNMARK support then
you can also mark the connection rather than the packet</para>
<itemizedlist>
<listitem>
<para>The mark value may be optionally followed by "/" and a
mask value (used to determine those bits of the connection
mark to actually be set).</para>
</listitem>
<listitem>
<para>The mark and optional mask are then followed by one
of:<simplelist>
<member>C: Mark the connection in the chain determined by
the setting of MARK_IN_FORWARD_CHAIN</member>
<member>CF: Mark the conneciton in the FORWARD
chain</member>
<member>CP: Mark the connection in the PREROUTING
chain.</member>
</simplelist></para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>A classification of the form &lt;major&gt;:&lt;minor&gt;
where &lt;major&gt; and &lt;minor&gt; are integers. Corresponds to
the 'class' specification in these traffic shaping
modules:<simplelist>
<member>- atm</member>
<member>- cbq</member>
<member>- dsmark</member>
<member>- pfifo_fast</member>
<member>- htb</member>
<member>- prio</member>
</simplelist>Classification always occurs in the POSTROUTING
chain. This feature requires Shorewall 2.2.0 and requires that
your kernel and iptables include CLASSIFY target support.</para>
</listitem>
<listitem>
<para>RESTORE[/mask] -- restore the packet's mark from the
connection's mark using the supplied mask if any. Your kernel and
iptables must include CONNMARK support. As iabove, may be followed
by ":P" or ":F</para>
</listitem>
<listitem>
<para>SAVE[/mask] -- save the packet's mark to the connection's
mark using the supplied mask if any. Your kernel and iptables must
include CONNMARK support. As above, may be followed by ":P" or
":F</para>
</listitem>
<listitem>
<para>CONTINUE -- don't process any more marking rules in the
table. As above, may be followed by ":P" or ":F".</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>SOURCE - The source of the packet. If the packet originates on
the firewall, place <quote>$FW</quote> in this column. Otherwise, this
is a comma-separated list of interface names, IP addresses, MAC
addresses in Shorewall Format and/or Subnets.</para>
<para>Examples <programlisting> eth0
192.168.2.4,192.168.1.0/24</programlisting></para>
<para>Beginning with Shorewall version 2.2.2, "$FW" may be optionally
followed by a colon (":") and a host/net address or an address
range.</para>
</listitem>
<listitem>
<para>DEST -- Destination of the packet. Comma-separated list of IP
addresses and/or subnets.</para>
</listitem>
<listitem>
<para>PROTO - Protocol - Must be the name of a protocol from
/etc/protocol, "ipp2p", a number or "all". For "ipp2p", your kernel
and iptables must have ipp2p match support from <ulink
url="http://www.netfilter.org">Netfilter
Patch_o_matic_ng</ulink>.</para>
</listitem>
<listitem>
<para>PORT(S) - Destination Ports. A comma-separated list of Port
names (from /etc/services), port numbers or port ranges (e.g., 21:22);
if the protocol is <quote>icmp</quote>, this column is interpreted as
the destination icmp type(s). If the protocol is "ipp2p", then this
column is interpreted as an ipp2p option without the leading "--"
(default "ipp2p"). For a list of value ipp2p options, as root type
<command>iptables -m ipp2p --help</command>.</para>
</listitem>
<listitem>
<para>CLIENT PORT(S) (Renamed SOURCE PORT(S) in Shorewall 2.2.0) -
(Optional) Source port(s). If omitted, any source port is acceptable.
Specified as a comma-separate list of port names, port numbers or port
ranges.</para>
</listitem>
<listitem>
<para>USER (Added in Shorewall version 1.4.10) - (Optional) This
column may only be non-empty if the SOURCE is the firewall itself.
When this column is non-empty, the rule applies only if the program
generating the output is running under the effective user and/or
group. It may contain :</para>
<para>[&lt;user name or number&gt;]:[&lt;group name or
number&gt;]</para>
<para>The colon is optionnal when specifying only a user.</para>
<para>Examples : john: / john / :users / john:users</para>
</listitem>
<listitem>
<para>TEST (added in Shorewall version 2.2.0). Defines a test on the
existing packet or connection mark. The rule will match only if the
test returns true. Tests have the format</para>
<programlisting>[!]&lt;value&gt;[/&lt;mask&gt;][:C]</programlisting>
<para>where</para>
<simplelist>
<member>! Inverts the test (not equal)</member>
<member>&lt;<emphasis>value</emphasis>&gt; Value of the packet or
connection mark.</member>
<member>&lt;<emphasis>mask</emphasis>&gt; A mask to be applied to
the mark before testing</member>
<member>:C Designates a connection mark. If omitted, the packet
mark's value is tested.</member>
</simplelist>
</listitem>
</itemizedlist>
<example>
<title></title>
<para>All packets arriving on eth1 should be marked with 1. All packets
arriving on eth2 and eth3 should be marked with 2. All packets
originating on the firewall itself should be marked with 3.</para>
<programlisting>#MARK SOURCE DESTINATION PROTO PORT(S) SOURCE PORT(S) USER/GROUP TEST
1 eth1 0.0.0.0/0 all
2 eth2 0.0.0.0/0 all
2 eth3 0.0.0.0/0 all
3 $FW 0.0.0.0/0 all</programlisting>
</example>
<example>
<title></title>
<para>All GRE (protocol 47) packets not originating on the firewall and
destined for 155.186.235.151 should be marked with 12.</para>
<programlisting>#MARK SOURCE DESTINATION PROTO PORT(S) SOURCE PORT(S) USER/GROUP TEST
12 0.0.0.0/0 155.182.235.151 47</programlisting>
</example>
<example>
<title></title>
<para>All SSH packets originating in 192.168.1.0/24 and destined for
155.186.235.151 should be marked with 22.</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL PORT(S) SOURCE PORT(S) USER/GROUP TEST
22 192.168.1.0/24 155.182.235.151 tcp 22</programlisting>
</example>
</section>
<section>
<title>My Current Setup</title>
<para>I am currently using the HTB version of <ulink
url="http://lartc.org/wondershaper/">The Wonder Shaper </ulink>(I just
copied wshaper.htb to /etc/shorewall/tcstart and modified it as shown in
the Wondershaper README). WonderShaper DOES NOT USE THE
/etc/shorewall/tcrules file.</para>
</section>
<section>
<title>My Old Setup</title>
<para>I have also run with the following set of hand-crafted rules in my
<emphasis role="bold">/etc/shorewall/tcstart</emphasis> file.</para>
<blockquote>
<programlisting>run_tc qdisc add dev eth0 root handle 1: htb default 30
run_tc class add dev eth0 parent 1: classid 1:1 htb rate 384kbit burst 15k
echo <quote> Added Top Level Class -- rate 384kbit</quote>
run_tc class add dev eth0 parent 1:1 classid 1:10 htb rate 140kbit ceil 384kbit burst 15k prio 1
run_tc class add dev eth0 parent 1:1 classid 1:20 htb rate 224kbit ceil 384kbit burst 15k prio 0
run_tc class add dev eth0 parent 1:1 classid 1:30 htb rate 20kbit ceil 384kbit burst 15k quantum 1500 prio 1
echo <quote> Added Second Level Classes -- rates 140kbit, 224kbit, 20kbit</quote>
run_tc qdisc add dev eth0 parent 1:10 pfifo limit 5
run_tc qdisc add dev eth0 parent 1:20 pfifo limit 10
run_tc qdisc add dev eth0 parent 1:30 pfifo limit 5
echo <quote> Enabled PFIFO on Second Level Classes</quote>
run_tc filter add dev eth0 protocol ip parent 1:0 prio 1 handle 1 fw classid 1:10
run_tc filter add dev eth0 protocol ip parent 1:0 prio 0 handle 2 fw classid 1:20
run_tc filter add dev eth0 protocol ip parent 1:0 prio 1 handle 3 fw classid 1:30
echo <quote> Defined fwmark filters</quote>
</programlisting>
</blockquote>
<para>My tcrules file that went with this tcstart file is shown in Example
1 above. When I was using these rules:</para>
<orderedlist>
<listitem>
<para>I wanted to allow up to 140kbits/second for traffic outbound
from my DMZ (eth1 -- note that the ceiling is set to 384kbit so
outbound DMZ traffic can use all available bandwidth if there is no
traffic from the local systems or from my laptop or firewall).</para>
</listitem>
<listitem>
<para>My laptop (which at that time connected via eth3) and local
systems (eth2) could use up to 224kbits/second.</para>
</listitem>
<listitem>
<para>My firewall could use up to 20kbits/second.</para>
/etc/shorewall/tcrules. But you have to set TC_ENABLED=Yes. This
is normally ok, if your tcdevices and tcclasses file does not
contain entries.</para>
</listitem>
</orderedlist>
<para>Once www.shorewall.net was moved off-site, I no longer needed these
shaping rules and The Wonder Shaper does all that I now require.</para>
</section>
</section>
</article>