shorewall_code/Shorewall/manpages/shorewall-tcclasses.xml
Tom Eastep 780e7014d4 Cleanup of tcclasses manpages
Signed-off-by: Tom Eastep <teastep@shorewall.net>
2012-06-15 10:34:09 -07:00

643 lines
26 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>tcclasses</refname>
<refpurpose>Shorewall file to define HTB classes</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>/etc/shorewall/tcclasses</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>A note on the <emphasis>rate</emphasis>/bandwidth definitions used
in this file:</para>
<itemizedlist>
<listitem>
<para>don't use a space between the integer value and the unit: 30kbit
is valid while 30 kbit is NOT.</para>
</listitem>
<listitem>
<para>you can use one of the following units:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">kpbs</emphasis></term>
<listitem>
<para>Kilobytes per second.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">mbps</emphasis></term>
<listitem>
<para>Megabytes per second.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">kbit</emphasis></term>
<listitem>
<para>Kilobits per second.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">mbit</emphasis></term>
<listitem>
<para>Megabits per second.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">bps</emphasis> or <emphasis
role="bold">number</emphasis></term>
<listitem>
<para>Bytes per second.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
<listitem>
<para>if you want the values to be calculated for you depending on the
output bandwidth setting defined for an interface in tcdevices, you
can use expressions like the following:</para>
<variablelist>
<varlistentry>
<term>full/3</term>
<listitem>
<para>causes the bandwidth to be calculated as 1/3 of the full
outgoing speed that is defined.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>full*9/10</term>
<listitem>
<para>will set this bandwidth to 9/10 of the full
bandwidth</para>
</listitem>
</varlistentry>
</variablelist>
<para>Note that in a sub-class (a class that has a specified parent
class), full refers to the RATE or CEIL of the parent class rather
than to the OUT-BANDWIDTH of the device.</para>
<para>DO NOT add a unit to the rate if it is calculated !</para>
</listitem>
</itemizedlist>
<para>The columns in the file are as follows.</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">INTERFACE</emphasis> -
<emphasis>interface</emphasis>[[:<emphasis>parent</emphasis>]:<emphasis>class</emphasis>]</term>
<listitem>
<para>Name of <emphasis>interface</emphasis>. 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="http://www.shorewall.net/FAQ.htm#faq18">http://www.shorewall.net/FAQ.htm#faq18</ulink></para>
<para>You may specify the interface number rather than the interface
name. If the <emphasis role="bold">classify</emphasis> option is
given for the interface in <ulink
url="shorewall-tcdevices.html">shorewall-tcdevices</ulink>(5), then
you must also specify an interface class (an integer that must be
unique within classes associated with this interface). If the
classify option is not given, you may still specify a
<emphasis>class</emphasis> or you may have Shorewall generate a
class number from the MARK value. Interface numbers and class
numbers are always assumed to be specified in hex and class number 1
is reserved as the root class of the queuing discipline.</para>
<para>You may NOT specify wildcards here, e.g. if you have multiple
ppp interfaces, you need to put them all in here!</para>
<para>Please note that you can only use interface names in here that
have a bandwidth defined in the <ulink
url="shorewall-tcdevices.html">shorewall-tcdevices</ulink>(5)
file.</para>
<para>Normally, all classes defined here are sub-classes of a root
class that is implicitly defined from the entry in <ulink
url="shorewall-tcdevices.html">shorewall-tcdevices</ulink>(5). You
can establish a class hierarchy by specifying a
<emphasis>parent</emphasis> class -- the number of a class that you
have previously defined. The sub-class may borrow unused bandwidth
from its parent.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">MARK</emphasis> -
{-|<emphasis>value</emphasis>}</term>
<listitem>
<para>The mark <emphasis>value</emphasis> which is an integer in the
range 1-255. You set mark values in the <ulink
url="shorewall-tcrules.html">shorewall-tcrules</ulink>(5) file,
marking the traffic you want to fit in the classes defined in here.
Must be specified as '-' if the <emphasis
role="bold">classify</emphasis> option is given for the interface in
<ulink
url="shorewall-tcdevices.html">shorewall-tcdevices</ulink>(5)</para>
<para>You can use the same marks for different interfaces.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">RATE</emphasis> -
{-|<emphasis>rate</emphasis>[:<emphasis>dmax</emphasis>[:<emphasis>umax</emphasis>]]}</term>
<listitem>
<para>The minimum bandwidth this class should get, when the traffic
load rises. If the sum of the rates in this column exceeds the
INTERFACE's OUT-BANDWIDTH, then the OUT-BANDWIDTH limit may not be
honored. Similarly, if the sum of the rates of sub-classes of a
class exceed the CEIL of the parent class, things don't work
well.</para>
<para>When using the HFSC queuing discipline, this column specify
the real-time (RT) service curve. leaf classes may specify
<replaceable>dmax</replaceable>, the maximum delay in milliseconds
that the first queued packet for this class should experience. May
be expressed as an integer, optionally followed by 'ms' with no
intervening white space (e.g., 10ms).</para>
<para>HFSC leaf classes may also specify
<replaceable>umax</replaceable>, the largest packet expected in this
class. May be expressed as an integer. The unit of measure is
<emphasis>bytes</emphasis> and the integer may be optionally
followed by 'b' with no intervening white space (e.g., 800b).
<replaceable>umax</replaceable> may only be given if
<replaceable>dmax</replaceable> is also given.</para>
<para>Beginning with Shorewall 4.5.6, HFSC classes may omit this
column (e.g, '-' in the column), provided that an
<replaceable>lsrate</replaceable> is specified (see CEIL below).
These rates are used to arbitrate between classes of the same
priority.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">CEIL</emphasis> -
[<emphasis>lsrate</emphasis>:]<emphasis>rate</emphasis></term>
<listitem>
<para>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 needed services (e.g. ssh) are not used.</para>
<para>You can use the value <emphasis role="bold">full</emphasis> in
here for setting the maximum bandwidth to the RATE of the parent
class, or the OUT-BANDWIDTH of the device if there is no parent
class.</para>
<para>Beginning with Shorewall 4.5.6, you can also specify an
<replaceable>lsrate</replaceable> (link sharing rate).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">PRIORITY</emphasis> -
<emphasis>priority</emphasis></term>
<listitem>
<para>The <emphasis>priority</emphasis> in which classes will be
serviced by the packet shaping scheduler and also the priority in
which bandwidth in excess of the rate will be given to each
class.</para>
<para>Higher priority classes will experience less delay since they
are serviced first. Priority values are serviced in ascending order
(e.g. 0 is higher priority than 1).</para>
<para>Classes may be set to the same priority, in which case they
will be serviced as equals.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">OPTIONS</emphasis> (Optional) -
[<emphasis>option</emphasis>[<emphasis
role="bold">,</emphasis><emphasis>option</emphasis>]...]</term>
<listitem>
<para>A comma-separated list of options including the
following:</para>
<variablelist>
<varlistentry>
<term><emphasis role="bold">default</emphasis></term>
<listitem>
<para>This is the default class for that interface where all
traffic should go, that is not classified otherwise.</para>
<para/>
<note>
<para>You must define <emphasis
role="bold">default</emphasis> for exactly one class per
interface.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">tos=0x</emphasis><emphasis>value</emphasis>[/0x<emphasis>mask</emphasis>]
(mask defaults to 0xff)</term>
<listitem>
<para>This lets you define a classifier for the given
<emphasis>value</emphasis>/<emphasis>mask</emphasis>
combination of the IP packet's TOS/Precedence/DiffSrv octet
(aka the TOS byte).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis
role="bold">tos-</emphasis><emphasis>tosname</emphasis></term>
<listitem>
<para>Aliases for the following TOS octet value and mask
encodings. TOS encodings of the "TOS byte" have been
deprecated in favor of diffserve classes, but programs like
ssh, rlogin, and ftp still use them.</para>
<programlisting> <emphasis role="bold">tos-minimize-delay</emphasis> 0x10/0x10
<emphasis role="bold">tos-maximize-throughput</emphasis> 0x08/0x08
<emphasis role="bold">tos-maximize-reliability</emphasis> 0x04/0x04
<emphasis role="bold">tos-minimize-cost</emphasis> 0x02/0x02
<emphasis role="bold">tos-normal-service</emphasis> 0x00/0x1e</programlisting>
<note>
<para>Each of these options is only valid for ONE class per
interface.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis role="bold">tcp-ack</emphasis></term>
<listitem>
<para>If defined, causes a tc filter to be created that puts
all tcp ack packets on that interface that have a 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 packets is
limited to 64 bytes because we want only packets WITHOUT
payload to match.</para>
<para/>
<note>
<para>This option is only valid for ONE class per
interface.</para>
</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>
<listitem>
<para>The class should not specify a MARK value. If one is
specified, it will be ignored with a warning
message.</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>. For additional information, see
<ulink url="shorewall-tcrules.html">tcrules</ulink>
(5).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>flow=<emphasis>keys</emphasis></term>
<listitem>
<para>Shorewall attaches an SFQ queuing discipline to each
leaf HTB class. SFQ ensures that each
<firstterm>flow</firstterm> gets equal access to the
interface. The default definition of a flow corresponds
roughly to a Netfilter connection. So if one internal system
is running BitTorrent, for example, it can have lots of
'flows' and can thus take up a larger share of the bandwidth
than a system having only a single active connection. The
<option>flow</option> classifier (module cls_flow) works
around this by letting you define what a 'flow' is. The
clasifier must be used carefully or it can block off all
traffic on an interface! The flow option can be specified for
an HTB leaf class (one that has no sub-classes). We recommend
that you use the following:</para>
<simplelist>
<member>Shaping internet-bound traffic:
flow=nfct-src</member>
<member>Shaping traffic bound for your local net:
flow=dst</member>
</simplelist>
<para>These will cause a 'flow' to consists of the traffic
to/from each internal system.</para>
<para>When more than one key is give, they must be enclosed in
parenthesis and separated by commas.</para>
<para>To see a list of the possible flow keys, run this
command:</para>
<blockquote>
<para><command>tc filter add flow help</command></para>
</blockquote>
<para>Those that begin with "nfct-" are Netfilter connection
tracking fields. As shown above, we recommend flow=nfct-src;
that means that we want to use the source IP address
<emphasis>before NAT</emphasis> as the key.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pfifo</term>
<listitem>
<para>When specified for a leaf class, the pfifo queing
discipline is applied to the class rather than the sfq queuing
discipline.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>limit=<emphasis>number</emphasis></term>
<listitem>
<para>Added in Shorewall 4.4.3. When specified for a leaf
class, determines the maximum number of packets that may be
queued within the class. The <emphasis>number</emphasis> must
be &gt; 2 and &lt;=128. If not specified, the value 127 is
assumed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>red=(<replaceable>redoption</replaceable>=<replaceable>value</replaceable>,
...)</term>
<listitem>
<para>Added in Shorewall 4.5.6. When specified on a leaf
class, causes the class to use the RED (Random Early
Detection) queuing discipline rather than SFQ. See tc-red (8)
for additional information.</para>
<para>Allowable redoptions are:</para>
<variablelist>
<varlistentry>
<term>min <replaceable>min</replaceable></term>
<listitem>
<para>Average queue size at which marking becomes a
possibility.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>max <replaceable>max</replaceable></term>
<listitem>
<para>At this average queue size, the marking
probability is maximal. Must be at least twice
<replaceable>min</replaceable> to prevent synchronous
retransmits, higher for low min.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>probability
<replaceable>probability</replaceable></term>
<listitem>
<para>Maximum probability for marking, specified as a
floating point number from 0.0 to 1.0. Suggested values
are 0.01 or 0.02 (1 or 2%, respectively).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>limit <replaceable>limit</replaceable></term>
<listitem>
<para>Hard limit on the real (not average) queue size in
bytes. Further packets are dropped. Should be set higher
than
<replaceable>max</replaceable>+<replaceable>burst</replaceable>.
It is advised to set this a few times higher than
<replaceable>max</replaceable>. Shorewall requires that
max be at least twice
<replaceable>min</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>burst <replaceable>burst</replaceable></term>
<listitem>
<para>Used for determining how fast the average queue
size is influenced by the real queue size. Larger values
make the calculation more sluggish, allowing longer
bursts of traffic before marking starts. Real life
experiments support the following guideline:
(<replaceable>min</replaceable>+<replaceable>min</replaceable>+<replaceable>max</replaceable>)/(3*<replaceable>avpkt</replaceable>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>avpkt <replaceable>avpkt</replaceable></term>
<listitem>
<para>Optional. Specified in bytes. Used with burst to
determine the time constant for average queue size
calculations. 1000 is a good value and is the Shorewall
default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>bandwidth
<replaceable>bandwidth</replaceable></term>
<listitem>
<para>Optional. This rate is used for calculating the
average queue size after some idle time. Should be set
to the bandwidth of your interface. Does not mean that
RED will shape for you!</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ecn</term>
<listitem>
<para>RED can either 'mark' or 'drop'. Explicit
Congestion Notification allows RED to notify remote
hosts that their rate exceeds the amount of bandwidth
available. Non-ECN capable hosts can only be notified by
dropping a packet. If this parameter is specified,
packets which indicate that their hosts honor ECN will
only be marked and not dropped, unless the queue size
hits <replaceable>limit</replaceable> bytes. Needs a tc
binary with RED support compiled in. Recommended.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<variablelist>
<varlistentry>
<term>Example 1:</term>
<listitem>
<para>Suppose you are using PPP over Ethernet (DSL) and ppp0 is the
interface for this. You have 4 classes here, the first you can use
for voice over IP traffic, the second interactive traffic (e.g.
ssh/telnet but not scp), the third will be for all unclassified
traffic, and the forth is for low priority traffic (e.g.
peer-to-peer).</para>
<para>The voice traffic in the first class will be guaranteed a
minimum of 100kbps and always be serviced first (because of the low
priority number, giving less delay) and will be granted excess
bandwidth (up to 180kbps, the class ceiling) first, before any other
traffic. A single VOIP stream, depending upon codecs, after
encapsulation, can take up to 80kbps on a PPOE/DSL link, so we pad a
little bit just in case. (TOS byte values 0xb8 and 0x68 are DiffServ
classes EF and AFF3-1 respectively and are often used by VOIP
devices).</para>
<para>Interactive traffic (tos-minimum-delay) and TCP acks (and ICMP
echo traffic if you use the example in tcrules) and any packet with
a mark of 2 will be guaranteed 1/4 of the link bandwidth, and may
extend up to full speed of the link.</para>
<para>Unclassified traffic and packets marked as 3 will be
guaranteed 1/4th of the link bandwidth, and may extend to the full
speed of the link.</para>
<para>Packets marked with 4 will be treated as low priority packets.
(The tcrules example marks p2p traffic as such.) If the link is
congested, they're only guaranteed 1/8th of the speed, and even if
the link is empty, can only expand to 80% of link bandwidth just as
a precaution in case there are upstream queues we didn't account
for. This is the last class to get additional bandwidth and the last
to get serviced by the scheduler because of the low priority.</para>
<programlisting> #INTERFACE MARK RATE CEIL PRIORITY OPTIONS
ppp0 1 100kbit 180kbit 1 tos=0x68/0xfc,tos=0xb8/0xfc
ppp0 2 full/4 full 2 tcp-ack,tos-minimize-delay
ppp0 3 full/4 full 3 default
ppp0 4 full/8 full*8/10 4</programlisting>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>FILES</title>
<para>/etc/shorewall/tcclasses</para>
</refsect1>
<refsect1>
<title>See ALSO</title>
<para><ulink
url="http://shorewall.net/traffic_shaping.htm">http://shorewall.net/traffic_shaping.htm</ulink></para>
<para><ulink
url="http://shorewall.net/configuration_file_basics.htm#Pairs">http://shorewall.net/configuration_file_basics.htm#Pairs</ulink></para>
<para>tc-hfsc (7)</para>
<para>shorewall(8), shorewall-accounting(5), shorewall-actions(5),
shorewall-blacklist(5), shorewall-hosts(5), shorewall_interfaces(5),
shorewall-ipsets(5), shorewall-maclist(5), shorewall-masq(5),
shorewall-nat(5), shorewall-netmap(5), shorewall-params(5),
shorewall-policy(5), shorewall-providers(5), shorewall-proxyarp(5),
shorewall-rtrules(5), shorewall-routestopped(5), shorewall-rules(5),
shorewall.conf(5), shorewall-secmarks(5), shorewall-tcdevices(5),
shorewall-tcrules(5), shorewall-tos(5), shorewall-tunnels(5),
shorewall-zones(5)</para>
</refsect1>
</refentry>