LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

Initial commit of source files. Not ready for distribution yet.

This commit is contained in:
mabrown 2003-09-08 17:07:55 +00:00
parent a8e7e13beb
commit 709721d8a4
22 changed files with 3539 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
LDP/guide/docbook/linux-ip/xsl/Traffic-Control-HOWTO-html-chunk.xsl Normal file
View File

@ -0,0 +1,29 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'
xmlns="http://www.w3.org/TR/xhtml1/transitional"
exclude-result-prefixes="#default">
<!-- $Id$ -->
<!-- This stylesheet calls Norman Walsh's 'docbook.xsl' stylesheet
and therefore generates MULTIPLE HTML FILES as output. -->
<!-- Note the the *order* of the import statements below is important and
should not be changed. -->
<!-- Change this to the path to where you have installed Norman
Walsh's XSL stylesheets -->
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
<!-- Imports the common LDP customization layer. -->
<xsl:import href="ldp-html-common.xsl"/>
<!-- If there was some reason to override 'ldp-html-common.xsl' or to
perform any other customizations that affect *only* the generation
of multiple HTML files, those templates or parameters could be
entered here. -->
<xsl:import href="Traffic-Control-HOWTO-html-common.xsl"/>
</xsl:stylesheet>

91
LDP/guide/docbook/linux-ip/xsl/Traffic-Control-HOWTO-html-common.xsl Normal file
View File

@ -0,0 +1,91 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version='1.0'
xmlns="http://www.w3.org/TR/xhtml1/transitional"
exclude-result-prefixes="#default"
>
<xsl:param name="html.stylesheet" select="'Traffic-Control-HOWTO.css'"/>
<!-- experimental -->
<xsl:param name="xref.with.number.and.title" select="1"/>
<xsl:param name="footer.rule" select="1"/>
<xsl:param name="header.rule" select="1"/>
<xsl:param name="callout.graphics.number.limit" select="20"/>
<!--
Tried chunk.tocs.and.lots, and got a main page with revision history
and abstract. Not quite what I had hoped.
<xsl:param name="chunk.tocs.and.lots" select="1"/>
Appears to be used by the LDP stylesheets, on which this is based
<xsl:param name="chunk.first.sections" select="1"/>
Not much happened with this. Hmph.
<xsl:param name="xref.properties" select="'local'"/>
Attempted, 2003-04-18, looks terrible; hard to navigate.
<xsl:param name="generate.toc">
book toc
part toc,title
appendix toc,title,example
section toc,title
</xsl:param>
-->
<xsl:template match="ulink" name="ulink">
<xsl:variable name="link">
<a class="nonlocal">
<xsl:if test="@id">
<xsl:attribute name="name">
<xsl:value-of select="@id"/>
</xsl:attribute>
</xsl:if>
<xsl:attribute name="href"><xsl:value-of select="@url"/></xsl:attribute>
<xsl:if test="$ulink.target != ''">
<xsl:attribute name="target">
<xsl:value-of select="$ulink.target"/>
</xsl:attribute>
</xsl:if>
<xsl:choose>
<xsl:when test="count(child::node())=0">
<xsl:value-of select="@url"/>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates/>
</xsl:otherwise>
</xsl:choose>
</a>
</xsl:variable>
<xsl:copy-of select="$link"/>
<!--
commented out because of problems with error messages from
xsltproc when trying to locate function "suwl"
<xsl:choose>
<xsl:when test="function-available('suwl:unwrapLinks')">
<xsl:copy-of select="suwl:unwrapLinks($link)"/>
</xsl:when>
<xsl:otherwise>
<xsl:copy-of select="$link"/>
</xsl:otherwise>
</xsl:choose>
-->
</xsl:template>
<!-- this stylesheet should override Norm Walsh's base stylesheets
and the LDP stylesheets to make it clear what links are local
and what links are non-local. -->
</xsl:stylesheet>

14
LDP/guide/docbook/linux-ip/xsl/catalog.xml Normal file
View File

@ -0,0 +1,14 @@
<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<nextCatalog catalog="/etc/xml/catalog" />
<public
publicId="-//OASIS//DTD DocBook XML V4.2//EN"
uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/>
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/>
<uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/>
</catalog>

34
LDP/howto/docbook/Traffic-Control-HOWTO/TEMPLATE.xml Normal file
View File

@ -0,0 +1,34 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="">
<title></title>
<para>
</para>
</section>
<!-- end of file -->

94
LDP/howto/docbook/Traffic-Control-HOWTO/Traffic-Control-HOWTO.css Normal file
View File

@ -0,0 +1,94 @@
/* Note that this file is for the XHTML output of the source doc */
/* these are the internal document links */
*:link { color: #009 ; text-decoration: none ; }
*:visited { color: #009 ; text-decoration: none ; }
*:active { color: #009 ; text-decoration: underline ; }
*:hover { color: #009 ; text-decoration: underline ; }
/* these are links to remote destinations; done in BLUE */
a.nonlocal:link { color: #00f ; text-decoration: none ; }
a.nonlocal:visited { color: #00f ; text-decoration: none ; }
a.nonlocal:hover { color: #00f ; text-decoration: underline ; }
a.nonlocal:active { color: #00f ; text-decoration: underline ; }
BODY {
color : black ;
background-color : #fff ;
}
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
/* */
/* variable list attributes */
/* */
/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
div.variablelist {
margin : 1em 5% 1em 5% ;
}
.calloutlist {
padding-left: 0.5em ;
padding-right: 0.5em ;
margin: 0em 0% 0.2em 0% ;
}
/*
.calloutlist table {
background-color : #dff ;
}
.example table {
background-color : #9cc ;
}
*/
.variablelist .term {
font-weight : bold ;
}
.variablelist .emphasis {
font-weight : bold ;
}
p.copyright {
padding-left : 1.0em ;
padding-right : 1.0em ;
margin : 0em 0% 0.2em 0% ;
font-size : 0.7em ;
font-family : Verdana, Arial, Helvetica ;
text-align : right ;
color : #808080 ;
}
.revhistory {
display : none ;
width : 100% ;
/* position : fixed ; */
/* bottom : -0px ; */
}
.revhistory table {
padding-left : 0em ;
padding-right : 0em ;
margin : 0em 0% 0em 0% ;
}
.revhistory td {
padding-left : 0.5em ;
padding-right : 0.5em ;
margin : 0em 0% 0em 0% ;
}
.revhistory tr {
padding-left : 0em ;
padding-right : 0em ;
margin : 0em 0% 0em 0% ;
}
.revhistory > * {
font-size : 0.5em ;
text-align : right ;
color : #808080 ;
}

35
LDP/howto/docbook/Traffic-Control-HOWTO/Traffic-Control-HOWTO.xml Normal file
View File

@ -0,0 +1,35 @@
<?xml version='1.0'?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % sections SYSTEM "sections.ent" >
%sections;
<!ENTITY % shorthand SYSTEM "shorthand.ent" >
%shorthand;
]>
<article lang="en">
&ch-articleinfo; <!-- article abstract and metadata -->
&ch-intro; <!-- lightweight introductory material -->
&ch-overview; <!-- some concepts, easy-going -->
&ch-elements; <!-- attempt to be discipline neutral -->
&ch-components; <!-- some Linux-specific stuff -->
&ch-software; <!-- explore some important details -->
&ch-classless-qdiscs; <!-- hit the "easy" qdiscs first -->
&ch-classful-qdiscs; <!-- introduce the classful qdiscs -->
<!-- &ch-classifiers; --> <!-- FUTURE chapter on classifiers -->
&ch-rules; <!-- some more explanatory text -->
<!-- &ch-examples; --> <!-- example city -->
&ch-scripts; <!-- htb.init, cbq.init, wondershaper -->
&ch-diagram; <!-- a general traffic control diagram -->
<!-- &ch-measuring; --> <!-- how can I tell it's working? -->
&ch-links; <!-- summary of links to other docs -->
</article>

112
LDP/howto/docbook/Traffic-Control-HOWTO/articleinfo.xml Normal file
View File

@ -0,0 +1,112 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<articleinfo>
<title>Traffic Control HOWTO</title>
<subtitle>Version &version;</subtitle>
<author>
<firstname>Martin</firstname>
<othername>A.</othername>
<surname>Brown</surname>
<affiliation>
<orgname>
<ulink url="http://www.securepipe.com/">SecurePipe, Inc.</ulink>
</orgname>
<orgdiv>Network Administration</orgdiv>
<address><email>mabrown@securepipe.com</email></address>
</affiliation>
</author>
<pubdate>&pubdate;</pubdate>
<legalnotice id="legalnotice">
<para>&#x00A9; 2003, Martin A. Brown</para>
<blockquote>
<para>
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no invariant sections, with no Front-Cover Texts,
with no Back-Cover Text. A copy of the license is located at
<ulink url="&url-gfdl;">&url-gfdl;</ulink>.
</para>
</blockquote>
</legalnotice>
<revhistory>
<revision>
<revnumber>0.5</revnumber>
<date>2002-09-01</date>
<authorinitials>MAB</authorinitials>
<revremark>HTB section mostly complete, more diagrams, LARTC pre-release</revremark>
</revision>
<revision>
<revnumber>0.4</revnumber>
<date>2002-08-30</date>
<authorinitials>MAB</authorinitials>
<revremark>added diagram</revremark>
</revision>
<revision>
<revnumber>0.3</revnumber>
<date>2002-08-29</date>
<authorinitials>MAB</authorinitials>
<revremark>substantial completion of classless, software, rules,
elements and components sections</revremark>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>2002-08-23</date>
<authorinitials>MAB</authorinitials>
<revremark>major work on overview, elements, components and
software sections</revremark>
</revision>
<revision>
<revnumber>0.1</revnumber>
<date>2002-08-15</date>
<authorinitials>MAB</authorinitials>
<revremark>initial revision (outline complete)</revremark>
</revision>
</revhistory>
<abstract>
<para>
Traffic control subsumes the sets of mechanisms and operations by
which packets are queued for transmission/reception on a network
interface. The operations include enqueueing, policing, classifying,
scheduling, shaping and dropping. This HOWTO provides an introduction
and overview of the capabilities and implementation of traffic control
under Linux.
</para>
</abstract>
</articleinfo>
<!-- end of file -->

430
LDP/howto/docbook/Traffic-Control-HOWTO/classful-qdiscs.xml Normal file
View File

@ -0,0 +1,430 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="classful-qdiscs">
<title>Classful Queuing Disciplines (&linux-qdisc;s)</title>
<para>
The flexibility and control of Linux traffic control can be unleashed
through the agency of the classful qdiscs. Remember that the classful
queuing disciplines can have filters attached to them, allowing packets to
be directed to particular classes and subqueues.
</para>
<para>
There are several common terms to describe classes directly attached to
the &root-qdisc; and terminal classes. Classess attached to the
&root-qdisc; are known as root classes, and more generically inner
classes. Any terminal class in a particular queuing discipline is known
as a leaf class by analogy to the tree structure of the classes. Besides
the use of figurative language depicting the structure as a tree, the
language of family relationships is also quite common.
</para>
<section id="qc-htb">
<title>HTB, Hierarchical Token Bucket</title>
<para>
&sch_htb; uses the concepts of tokens and buckets
along with the class-based system and &linux-filter;s to allow for
complex and granular control over traffic. With a complex
&link-htb-borrowing;, &sch_htb; can perform a variety of sophisticated
traffic control techniques. One of the easiest ways to use &sch_htb;
immediately is that of &link-htb-shaping;.
</para>
<para>
By understanding &concepts-tokens; and &concepts-buckets; or by grasping
the function of &link-sch_tbf;, &sch_htb; should be merely a logical
step. This queuing discipline allows the user to define the
characteristics of the tokens and bucket used and allows the user to
nest these buckets in an arbitrary fashion. When coupled with a
&elements-classifying; scheme, traffic can be controlled in a very
granular fashion.
</para>
<para>
</para>
<para>
Below is example output of the syntax for &sch_htb; on the command line
with the &link-tc; tool. Although the syntax for &link-tcng; is a
language of its own, the rules for &sch_htb; are the same.
</para>
<example id="ex-qc-htb-usage">
<title>&tc; usage for &sch_htb;</title>
<programlisting>
Usage: ... qdisc add ... htb [default N] [r2q N]
default minor id of class to which unclassified packets are sent {0}
r2q DRR quantums are computed as rate in Bps/r2q {10}
debug string of 16 numbers each 0-3 {0}
... class add ... htb rate R1 burst B1 [prio P] [slot S] [pslot PS]
[ceil R2] [cburst B2] [mtu MTU] [quantum Q]
rate rate allocated to this class (class can still borrow)
burst max bytes burst which can be accumulated during idle period {computed}
ceil definite upper class rate (no borrows) {rate}
cburst burst but for ceil {computed}
mtu max packet size we create rate map for {1600}
prio priority of leaf; lower are served first {0}
quantum how much bytes to serve from leaf at once {use r2q}
TC HTB version 3.3
</programlisting>
</example>
<para>
</para>
<section id="qc-htb-shaping">
<title>Shaping</title>
<para>
One of the most common applications of &sch_htb; involves shaping
(rate-limiting, capping bandwidth, throttling) transmitted traffic to
a specific rate.
</para>
<para>
All shaping occurs in leaf classes. No shaping occurs in inner or
root classes as they only exist to suggest how the
&link-htb-borrowing; should distribute available tokens.
</para>
<para>
</para>
<para>
</para>
</section>
<section id="qc-htb-borrowing">
<title>Borrowing</title>
<para>
A fundamental part of the &sch_htb; qdisc is the borrowing mechanism.
Children classes borrow tokens from their parents once they have
exceeded &link-htb-param-rate;. A child class will continue to
attempt to borrow until it reaches &link-htb-param-ceil;, at which
point it will begin to queue packets for transmission until more
tokens/ctokens are available. As there are only two primary types of
classes which can be created with &sch_htb; the following table and
diagram identify the various possible states and the behaviour of the
borrowing mechanisms.
</para>
<para>
</para>
<table id="tb-qc-htb-borrowing">
<title>&sch_htb; class states and potential actions taken</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<thead>
<row>
<entry>type of class</entry>
<entry>class state</entry>
<entry>&sch_htb; internal state</entry>
<entry>action taken</entry>
</row>
</thead>
<tbody>
<row>
<entry>leaf</entry>
<entry>&lt; &param-rate;</entry>
<entry><parameter>HTB_CAN_SEND</parameter></entry>
<entry>
Leaf class will dequeue queued bytes up
to available tokens (no more than burst packets)
</entry>
</row>
<row>
<entry>leaf</entry>
<entry>&gt; &param-rate;, &lt; &param-ceil;</entry>
<entry><parameter>HTB_MAY_BORROW</parameter></entry>
<entry>
Leaf class will attempt to borrow tokens/ctokens from
parent class. If tokens are available, they will be lent in
&param-quantum; increments and the leaf class will dequeue up
to &param-cburst; bytes
</entry>
</row>
<row>
<entry>leaf</entry>
<entry>&gt; &param-ceil;</entry>
<entry><parameter>HTB_CANT_SEND</parameter></entry>
<entry>
No packets will be dequeued. This will cause packet
delay and will increase latency to meet the desired
rate.
</entry>
</row>
<row>
<entry>inner</entry>
<entry>&lt; &param-rate;</entry>
<entry><parameter>HTB_CAN_SEND</parameter></entry>
<entry>
Inner class will lend tokens to children.
</entry>
</row>
<row>
<entry>inner</entry>
<entry>&gt; &param-rate;, &lt; &param-ceil;</entry>
<entry><parameter>HTB_MAY_BORROW</parameter></entry>
<entry>
Inner class will attempt to borrow tokens/ctokens from
parent class, lending them to competing children in
&param-quantum; increments per request.
</entry>
</row>
<row>
<entry>inner</entry>
<entry>&gt; &param-ceil;</entry>
<entry><parameter>HTB_CANT_SEND</parameter></entry>
<entry>
Inner class will not attempt to borrow from its parent
and will not lend tokens/ctokens to children classes.
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
This diagram identifies the flow of borrowed tokens and the manner in
which tokens are charged to parent classes. In order for the
borrowing model to work, each class must have an accurate count of the
number of tokens used by itself and all of its children. For this
reason, any token used in a child or leaf class is charged to each
parent class until the root class is reached.
</para>
<para>
Any child class which wishes to borrow a token will request a token
from its parent class, which if it is also over its &param-rate; will
request to borrow from its parent class until either a token is
located or the root class is reached. So the borrowing of tokens
flows toward the leaf classes and the charging of the usage of tokens
flows toward the root class.
</para>
<mediaobject id="img-qc-htb-borrow">
<imageobject>
<imagedata fileref="images/htb-borrow.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/htb-borrow.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/htb-borrow.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<para>
Note in this diagram that there are several &sch_htb; root classes.
Each of these root classes can simulate a virtual circuit.
</para>
</section>
<section id="qc-htb-params">
<title>Parameters</title>
<para>
</para>
<variablelist id="vl-qc-htb-params">
<varlistentry id="vl-qc-htb-params-default">
<term>&param-default;</term>
<listitem>
<para>
An optional parameter with every &sch_htb; &linux-qdisc; object,
the default &param-default; is 0, which cause any unclassified
traffic to be dequeued at hardware speed, completely bypassing
any of the classes attached to the &root-qdisc;.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-rate">
<term>&param-rate;</term>
<listitem>
<para>
Used to set the minimum desired speed to which to limit
transmitted traffic. This can be considered the equivalent of a
committed information rate (<acronym>CIR</acronym>), or the
guaranteed bandwidth for a given leaf class.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-ceil">
<term>&param-ceil;</term>
<listitem>
<para>
Used to set the maximum desired speed to which to limit the
transmitted traffic. The borrowing model should illustrate how
this parameter is used. This can be considered the equivalent
of <quote>burstable bandwidth</quote>.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-burst">
<term>&param-burst;</term>
<listitem>
<para>
This is the size of the &link-htb-param-rate; bucket (see
<xref linkend="o-buckets"/>). &sch_htb; will dequeue
&param-burst; bytes before awaiting the arrival of more
tokens.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-cburst">
<term>&param-cburst;</term>
<listitem>
<para>
This is the size of the &link-htb-param-ceil; bucket (see
<xref linkend="o-buckets"/>). &sch_htb; will dequeue
&param-cburst; bytes before awaiting the arrival of more
ctokens.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-quantum">
<term>&param-quantum;</term>
<listitem>
<para>
This is a key parameter used by &sch_htb; to control borrowing.
Normally, the correct &param-quantum; is calculated by
&sch_htb;, not specified by the user. Tweaking this parameter
can have tremendous effects on borrowing and shaping under
contention, because it is used both to split traffic between
children classes over &link-htb-param-rate; (but below
&link-htb-param-ceil;) and to transmit packets from these same
classes.
</para>
</listitem>
</varlistentry>
<varlistentry id="vl-qc-htb-params-r2q">
<term>&param-r2q;</term>
<listitem>
<para>
Also, usually calculated for the user, &param-r2q; is a hint to
&sch_htb; to help determine the optimal &link-htb-param-quantum;
for a particular class.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
</para>
</section>
<section id="qc-htb-rules">
<title>Rules</title>
<para>
Below are some general guidelines to using &sch_htb; culled from
&url-docum.org; and the &url-lartc-mailinglist;. These rules are
simply a recommendation for beginners to maximize the benefit of
&sch_htb; until gaining a better understanding of the practical
application of &sch_htb;.
</para>
<para>
</para>
<itemizedlist>
<listitem>
<para>
Shaping with &sch_htb; occurs only in leaf classes. See also
<xref linkend="qc-htb-shaping"/>.
</para>
</listitem>
<listitem>
<para>
Because &sch_htb; does not shape in any class except the leaf
class, the sum of the &param-rate;s of leaf classes should not
exceed the &param-ceil; of a parent class. Ideally, the sum of
the &param-rate;s of the children classes would match the
&param-rate; of the parent class, allowing the parent class to
distribute leftover bandwidth (&param-ceil; - &param-rate;) among
the children classes.
</para>
<para>
This key concept in employing &sch_htb; bears repeating. Only
leaf classes actually shape packets; packets are only delayed in
these leaf classes. The inner classes (all the way up to the root
class) exist to define how borrowing/lending occurs (see also
<xref linkend="qc-htb-borrowing"/>).
</para>
</listitem>
<listitem>
<para>
The &param-quantum; should be set at MTU or higher. &sch_htb;
will dequeue a single packet at least per service opportunity even
if &param-quantum; is too small. In such a case, it will not be
able to calculate accurately the real bandwidth consumed
<footnote>
<para>
&sch_htb; will report bandwidth usage in this scenario
incorrectly. It will calculate the bandwidth used by
&param-quantum; instead of the real dequeued packet size.
This can squeue results quickly.
</para>
</footnote>.
</para>
</listitem>
<listitem>
<para>
For maximum granularity and most instantaneously evenly
distributed bandwidth, &param-quantum; should be as low as
possible while still no less than MTU.
</para>
</listitem>
<listitem>
<para>
The &param-quantum; is only only used when a class is over
&param-rate; but below &param-ceil;.
</para>
</listitem>
<listitem>
<para>
A distinction between tokens and ctokens is only meaningful in a
leaf class, because non-leaf classes only lend tokens to child
classes.
</para>
</listitem>
<listitem>
<para>
&sch_htb; borrowing could more accurately be described as
<quote>using</quote>.
</para>
</listitem>
</itemizedlist>
<para>
</para>
</section>
</section>
<section id="qc-prio">
<title>&sch_prio;, priority scheduler</title>
<para>
The &sch_prio; classful qdisc works on a very simple precept. When it
is ready to dequeue a packet, the first class is checked for a packet.
If there's a packet, it gets dequeued. If there's no packet, then the
next class is checked, until the queuing mechanism has no more classes
to check.
</para>
<para>
This section will be completed at a later date.
</para>
</section>
<section id="qc-cbq">
<title>&sch_cbq;, Class Based Queuing</title>
<para>
CBQ is the classic implementation (also called venerable) of a traffic
control system. This section will be completed at a later date.
</para>
<para>
</para>
</section>
</section>
<!-- end of file -->

294
LDP/howto/docbook/Traffic-Control-HOWTO/classless-qdiscs.xml Normal file
View File

@ -0,0 +1,294 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="classless-qdiscs">
<title>Classless Queuing Disciplines (&linux-qdisc;s)</title>
<para>
Each of these queuing disciplines can be used as the primary qdisc on an
interface, or can be used inside a leaf class of a &classful-qdiscs;.
These are the fundamental schedulers used under Linux.
</para>
<para>
</para>
<section id="qs-fifo">
<title>FIFO, First-In First-Out (&sch_pfifo; and &sch_bfifo;)</title>
<note>
This is not the default qdisc on Linux interfaces. Be certain to see
<xref linkend="qs-pfifo_fast"/> for the full details on the default
(&sch_pfifo_fast;) qdisc.
</note>
<para>
The FIFO algorithm forms the basis for the default qdisc on all Linux
network interfaces (&link-sch_pfifo_fast;). It performs no shaping or
rearranging of packets. It simply transmits packets as soon as it can
after receiving and queuing them.
</para>
<mediaobject id="img-qs-fifo">
<imageobject>
<imagedata fileref="images/fifo-qdisc.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/fifo-qdisc.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/fifo-qdisc.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<para>
A real FIFO qdisc must, however, have a size limit to prevent it from
overflowing in case it is unable to dequeue packets as quickly as it
receives them. Linux implements two basic FIFO &linux-qdisc;s, one
based on bytes, and one on packets. Regardless of the type of FIFO
used, the size of the queue is defined by the parameter
<parameter>limit</parameter>. For a &sch_pfifo; the unit is understood
to be packets and for a &sch_bfifo; the unit is understood to be bytes.
</para>
<example id="ex-qs-fifo-limit">
<title>Specifying a FIFO <parameter>limit</parameter></title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>cat bfifo.tcc</userinput>
<computeroutput>/*
* make a FIFO on eth0 with 10kbyte queue size
*
*/
dev eth0 {
egress {
fifo (limit 10kB );
}
}</computeroutput>
<prompt>[root@leander]# </prompt><userinput>tcc &lt; bfifo.tcc</userinput>
<computeroutput># ================================ Device eth0 ================================
tc qdisc add dev eth0 handle 1:0 root dsmark indices 1 default_index 0
tc qdisc add dev eth0 handle 2:0 parent 1:0 bfifo limit 10240</computeroutput>
<prompt>[root@leander]# </prompt><userinput>cat pfifo.tcc</userinput>
<computeroutput>/*
* make a FIFO on eth0 with 30 packet queue size
*
*/
dev eth0 {
egress {
fifo (limit 30p );
}
}</computeroutput>
<prompt>[root@leander]# </prompt><userinput>tcc &lt; pfifo.tcc</userinput>
<computeroutput># ================================ Device eth0 ================================
tc qdisc add dev eth0 handle 1:0 root dsmark indices 1 default_index 0
tc qdisc add dev eth0 handle 2:0 parent 1:0 pfifo limit 30</computeroutput>
</programlisting>
</example>
</section>
<section id="qs-pfifo_fast">
<title>&sch_pfifo_fast;, the default Linux qdisc</title>
<para>
The &sch_pfifo_fast; qdisc is the default qdisc for all interfaces under
Linux. Based on a conventional &link-sch_fifo; qdisc, this qdisc also
provides some prioritization. It provides three different bands
(individual FIFOs) for separating traffic. The highest priority traffic
(interactive flows) are placed into band 0 and are always serviced
first. Similarly, band 1 is always emptied of pending packets before
band 2 is dequeued.
</para>
<mediaobject id="img-qs-pfifo_fast">
<imageobject>
<imagedata fileref="images/pfifo_fast-qdisc.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/pfifo_fast-qdisc.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/pfifo_fast-qdisc.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<para>
There is nothing configurable to the end user about the &sch_pfifo_fast;
qdisc. For exact details on the <constant>priomap</constant> and use of
the ToS bits, see the &url-lartc-howto-pfifo_fast;.
</para>
</section>
<section id="qs-sfq">
<title>&sch_sfq;, Stochastic Fair Queuing</title>
<para>
The &sch_sfq; qdisc attempts to fairly distribute opportunity to
transmit data to the network among an arbitrary number of
&concepts-flows;. It accomplishes this by using a hash function to
separate the traffic into separate (internally maintained) &sch_fifo;s
which are dequeued in a round-robin fashion. Because there is the
possibility for unfairness to manifest in the choice of hash function,
this function is altered periodically. Perturbation (the parameter
<parameter>perturb</parameter>) describes this periodically altered hash
function.
</para>
<mediaobject id="img-qs-sfq">
<imageobject>
<imagedata fileref="images/sfq-qdisc.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/sfq-qdisc.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/sfq-qdisc.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<example id="ex-qs-sfq">
<title>Creating an &sch_sfq;</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>cat sfq.tcc</userinput>
<computeroutput>/*
* make an SFQ on eth0 with a 10 second perturbation
*
*/
dev eth0 {
egress {
sfq( perturb 10s );
}
}</computeroutput>
<prompt>[root@leander]# </prompt><userinput>tcc &lt; sfq.tcc</userinput>
<computeroutput># ================================ Device eth0 ================================
tc qdisc add dev eth0 handle 1:0 root dsmark indices 1 default_index 0
tc qdisc add dev eth0 handle 2:0 parent 1:0 sfq perturb 10</computeroutput>
</programlisting>
</example>
<para>
Unfortunately, some clever software (&eg; Kazaa and eMule among others)
obliterate the benefit of this attempt at fair queuing by opening as
many TCP sessions (&concepts-flows;) as can be sustained. In many
networks, with well-behaved users, &sch_sfq; can adequately distribute
the network resources to the contending flows, but other measures may be
called for when obnoxious applications have invaded the network.
</para>
<para>
See also
<xref linkend="qs-esfq"/> for an &sch_sfq; qdisc with more exposed
parameters for the user to manipulate.
</para>
</section>
<section id="qs-esfq">
<title>&sch_esfq;, Extended Stochastic Fair Queuing</title>
<para>
Conceptually, this qdisc is no different than &sch_sfq; although it
allows the user to control more parameters than its simpler cousin.
</para>
<example id="ex-qs-esfq-usage">
<title>&sch_esfq; usage</title>
<programlisting>
Usage: ... esfq [ perturb SECS ] [ quantum BYTES ] [ depth FLOWS ]
[ divisor HASHBITS ] [ limit PKTS ] [ hash HASHTYPE]
Where:
HASHTYPE := { classic | src | dst }
</programlisting>
</example>
<para>
FIXME; need practical experience and/or attestation here.
</para>
</section>
<section id="qs-gred">
<title>GRED, Generic Random Early Drop</title>
<para>
FIXME; I have never used this. Need practical experience or
attestation.
</para>
<para>
Theory declares that a RED algorithm is useful on a backbone or core
network, but not as useful near the end-user. See the section on
&concepts-flows; to see a general discussion of the thirstiness of TCP.
</para>
</section>
<section id="qs-tbf">
<title>TBF, Token Bucket Filter</title>
<para>
This qdisc is built on &concepts-tokens; and &concepts-buckets;, which
are key concepts involved with &elements-shaping;. To limit the speed
at which packets will be dequeued from a particular interface, the
&sch_tbf; qdisc is the perfect solution. It simply slows down
transmitted traffic to the specified rate.
</para>
<para>
Packets are only transmitted if there are sufficient tokens available.
Otherwise, packets are deferred. Delaying packets in this fashion will
introduce an artificial latency into the packet's round trip time.
</para>
<mediaobject id="img-qs-tbf">
<imageobject>
<imagedata fileref="images/tbf-qdisc.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/tbf-qdisc.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/tbf-qdisc.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<example id="ex-qs-tbf">
<title>Creating a 256kbit/s &sch_tbf;</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>cat tbf.tcc</userinput>
<computeroutput>/*
* make a 256kbit/s TBF on eth0
*
*/
dev eth0 {
egress {
tbf( rate 256 kbps, burst 20 kB, limit 20 kB, mtu 1514 B );
}
}</computeroutput>
<prompt>[root@leander]# </prompt><userinput>tcc &lt; tbf.tcc</userinput>
<computeroutput># ================================ Device eth0 ================================
tc qdisc add dev eth0 handle 1:0 root dsmark indices 1 default_index 0
tc qdisc add dev eth0 handle 2:0 parent 1:0 tbf burst 20480 limit 20480 mtu 1514 rate 32000bps</computeroutput>
</programlisting>
</example>
<para>
</para>
</section>
<!--
<section id="qs-wrr">
<title>WRR, Weighted Round Robin</title>
<para>
</para>
<para>
</para>
</section>
-->
</section>
<!-- end of file -->

322
LDP/howto/docbook/Traffic-Control-HOWTO/components.xml Normal file
View File

@ -0,0 +1,322 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="components">
<title>Components of Linux Traffic Control</title>
<para>
</para>
<para>
</para>
<para>
</para>
<table id="tb-c-components-correlation">
<title>Correlation between traffic control elements and Linux
components</title>
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colwidth='1*' colname="elem"/>
<colspec colwidth='3*' colname="comp"/>
<thead>
<row>
<entry>traditional element</entry>
<entry>Linux component</entry>
</row>
</thead>
<tbody>
<row>
<entry colname="elem">&elements-shaping;</entry>
<entry colname="comp">The &linux-class; offers shaping capabilities.</entry>
</row>
<row>
<entry colname="elem">&elements-scheduling;</entry>
<entry colname="comp">A &linux-qdisc; is a scheduler. Schedulers
can be simple such as the &sch_fifo; or
complex, containing classes and other
qdiscs, such as &sch_htb;.</entry>
</row>
<row>
<entry colname="elem">&elements-classifying;</entry>
<entry colname="comp">The &linux-filter; object performs the
classification through the agency of a
&linux-classifier; object. Strictly speaking,
Linux classifiers cannot exist outside
of a filter.</entry>
</row>
<row>
<entry colname="elem">&elements-policing;</entry>
<entry colname="comp">A &linux-policer; exists in the Linux traffic
control implementation only as part of a
&linux-filter;.</entry>
</row>
<row>
<entry colname="elem">&elements-dropping;</entry>
<entry colname="comp">To &linux-drop; traffic requires a
&linux-filter; with a &linux-policer; which
uses <quote>drop</quote> as an action.</entry>
</row>
<row>
<entry colname="elem">&elements-marking;</entry>
<entry colname="comp">The &linux-dsmark; &linux-qdisc; is used for
marking.</entry>
</row>
</tbody>
</tgroup>
</table>
<section id="c-qdisc">
<title><constant>qdisc</constant></title>
<para>
Simply put, a qdisc is a scheduler
(<xref linkend="e-scheduling"/>). Every output interface needs a
scheduler of some kind, and the default scheduler is a &sch_fifo;.
Other qdiscs available under Linux will rearrange the packets entering
the scheduler's queue in accordance with that scheduler's rules.
</para>
<para>
The qdisc is the major building block on which all of Linux traffic
control is built, and is also called a queuing discipline.
</para>
<para>
The &classful-qdiscs; can contain &linux-class;es, and provide a handle
to which to attach &linux-filter;s. There is no prohibition on using a
classful qdisc without child classes, although this will usually consume
cycles and other system resources for no benefit.
</para>
<para>
The &classless-qdiscs; can contain no classes, nor is it possible to
attach filter to a classless qdisc. Because a it contains no children
of any kind, the utility &elements-classifying; is pointless.
</para>
<para>
Every interface has two qdiscs. The primary and more common qdisc
is the egress qdisc, known as the &root-qdisc;. The overwhelming
majority of documentation applies to the &root-qdisc; and its children.
Traffic transmitted on an interface traverses the egress or
&root-qdisc;.
</para>
<para>
For traffic accepted on an interface, the &ingress-qdisc; is traversed.
This qdisc has limited utility, allows no child &linux-class; to be
created, and only exists as an object onto which a &linux-filter; can be
attached. For practical purposes, the &ingress-qdisc; is merely a
convenient object onto which to attach a &linux-policer; to limit the
amount of traffic accepted into a network.
</para>
<para>
</para>
</section>
<section id="c-class">
<title><constant>class</constant></title>
<para>
Classes only exist inside a classful &linux-qdisc; (&eg;, &link-sch_htb;
and &link-sch_cbq;). Classes are immensely flexible and can always
contain either multiple children classes or a single child qdisc
<footnote>
<para>
A classful qdisc can only have children classes of its type. For
example, an HTB qdisc can only have HTB classes as children. A CBQ
qdisc cannot have HTB classes as children.
</para>
</footnote>.
There is no prohibition against a class containing a classful qdisc
itself, which facilitates tremendously complex traffic control
scenarios.
</para>
<para>
Any class can also have multiple &linux-filter;s attached to it, which
allows the selection of a child class or the use of a filter to
reclassify or drop traffic entering a particular class.
</para>
</section>
<section id="c-filter">
<title><constant>filter</constant></title>
<para>
The filter is one of the most complex elements in the Linux
traffic control system. The filter provides a convenient mechanism for
gluing together several of the key elements of traffic control. The
simplest and most obvious role of the filter is to classify
(see <xref linkend="e-classifying"/>) packets. Linux filters allow the
user to classify packets into an output queue with either several
different filters or a single filter.
</para>
<para>
Filters can be attached either to &linux-qdisc;s or to &linux-class;es,
however the enqueued packet always enters the root qdisc first.
After the filter attached to the root qdisc has been traversed,
the packet may be directed to any subclasses (which can have their own
filters) where the packet may continue its classification process.
</para>
<!-- FIXME; discussion not complete here -->
<para>
</para>
</section>
<section id="c-classifier">
<title>classifier</title>
<para>
Filter objects, which can be manipulated using &link-tc;, can use several
different classifying mechanisms, the most common of which is the
&cls_u32; classifier. The &cls_u32; classifier allows the user to
select packets based on attributes of the packet.
</para>
<para>
The classifiers are tools which can be used as part of a &linux-filter;
to identify characteristics of a packet or a packet's metadata.
</para>
</section>
<section id="c-police">
<title>policer</title>
<para>
This elemental mechanism is only used in Linux traffic control as part
of a &linux-filter;. A policer calls one action above and another
action below the specified rate. This can be used to set up a set of
cascading policers to simulate a three-color meter.
</para>
<para>
Although both &elements-policing; and &elements-shaping; are basic
elements of traffic control for limiting bandwidth usage a policer will
never delay traffic. It can only perform an action based on specified
criteria.
</para>
<!--
<example id="ex-c-police-action">
<title>Example of a policer</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>tc filter add dev ppp0 parent 1:0 protocol all prio 4 \</userinput>
<prompt>&gt; </prompt> <userinput>u32 match u32 0x0 0x0 at 0 classid 1:7 \</userinput>
<prompt>&gt; </prompt> <userinput>police index 3 rate 32000bps burst 10240 mpu 0 action drop/continue</userinput>
</programlisting>
</example>
-->
<para>
</para>
<para>
</para>
</section>
<section id="c-drop">
<title><constant>drop</constant></title>
<para>
This basic traffic control mechanism is only used in Linux traffic
control as part of a &linux-policer;. Any policer attached to
any &linux-filter; could have a &linux-drop; action.
</para>
<note>
The only place in the Linux traffic control system where a packet can be
explicitly dropped is a policer. A policer can limit packets enqueued
at a specific rate, or it can be configured to drop all traffic matching
a particular pattern
<footnote>
<para>
In this case, you'll have a &linux-filter; which uses a
&linux-classifier; to select the packets you wish to drop. Then
you'll use a &linux-policer; with a with a drop action like this
<command>police rate 1bps burst 1 action drop/drop</command>.
</para>
</footnote>.
</note>
<para>
There are, however, places within the traffic control system where a
packet may be dropped as a side effect. For example, a packet will be
dropped if the scheduler employed uses this methood to control flows as
the &link-sch_gred; does.
</para>
<para>
A shaper or scheduler which runs out of its allocated buffer space may
have to drop a packet during a particularly bursty or overloaded period.
</para>
<para>
</para>
</section>
<section id="c-handle">
<title><constant>handle</constant></title>
<para>
Every &linux-class; and classful &linux-qdisc; (see also
<xref linkend="classful-qdiscs"/>) requires a unique identifier within
the traffic control structure. Note that &classless-qdiscs; do not
require a handle. This unique identifier is known as a
handle and has two constituent members, a major number and a minor
number. These numbers can be assigned arbitrarily by the user in
accordance with the following rules
<footnote>
<para>
I do not know the range nor base of these numbers. I believe they
are u32 hexadecimal, but need to confirm this.
</para>
</footnote>.
</para>
<para>
<variablelist>
<title>Rules for numbering handles for classes and qdiscs</title>
<varlistentry>
<term><parameter>major</parameter></term>
<listitem>
<para>
This parameter is completely free of meaning to the kernel. The
user may use an arbitrary numbering scheme, however all objects in
the traffic control structure with the same parent must share a
<parameter>major</parameter> handle number. Conventional
numbering schemes start at 1 for devices attached to the
&root-qdisc;.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>minor</parameter></term>
<listitem>
<para>
This parameter unambigously identifies the object as a qdisc (if
<parameter>minor</parameter> is 0. Any other value identifies the
object as a class. All classes sharing a parent must have unique
<parameter>minor</parameter> numbers.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The special handle ffff:0 is reserved for the &ingress-qdisc;.
</para>
</section>
<!--
<section id="c-dsmark">
<title><constant>dsmark</constant></title>
<para>
</para>
<para>
</para>
</section>
-->
</section>
<!-- end of file -->

100
LDP/howto/docbook/Traffic-Control-HOWTO/diagram.xml Normal file
View File

@ -0,0 +1,100 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="diagram">
<title>Diagram</title>
<para>
</para>
<para>
</para>
<section id="d-general">
<title>General diagram</title>
<para>
Below is a general diagram of the relationships of the components of a
classful queuing discipline (&sch_htb; pictured). A larger version of
the diagram is
<ulink url="&diag-htb-class;">available</ulink>.
</para>
<para>
</para>
<example id="d-tcng-config">
<title>An example &sch_htb; &tcng; configuration</title>
<programlisting>
<![CDATA[/*
*
* possible mock up of diagram shown at
* http://linux-ip.net/traffic-control/htb-class.png
*
*/
$m_web = trTCM (
cir 512 kbps, /* commited information rate */
cbs 10 kB, /* burst for CIR */
pir 1024 kbps, /* peak information rate */
pbs 10 kB /* burst for PIR */
) ;
dev eth0 {
egress {
class ( <$web> ) if tcp_dport == PORT_HTTP && __trTCM_green( $m_web );
class ( <$bulk> ) if tcp_dport == PORT_HTTP && __trTCM_yellow( $m_web );
drop if __trTCM_red( $m_web );
class ( <$bulk> ) if tcp_dport == PORT_SSH ;
htb () { /* root qdisc */
class ( rate 1544kbps, ceil 1544kbps ) { /* root class */
$web = class ( rate 512kbps, ceil 512kbps ) { sfq ; } ;
$bulk = class ( rate 512kbps, ceil 1544kbps ) { sfq ; } ;
}
}
}
}]]>
</programlisting>
</example>
<mediaobject id="img-d-general">
<imageobject>
<imagedata fileref="images/htb-class.eps" format="EPS"/>
</imageobject>
<imageobject>
<imagedata fileref="images/htb-class.png" format="PNG"/>
</imageobject>
<imageobject>
<imagedata fileref="images/htb-class.jpg" format="JPG"/>
</imageobject>
</mediaobject>
<para>
</para>
</section>
</section>
<!-- end of file -->

165
LDP/howto/docbook/Traffic-Control-HOWTO/elements.xml Normal file
View File

@ -0,0 +1,165 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="elements">
<title>Traditional Elements of Traffic Control</title>
<para>
</para>
<section id="e-shaping">
<title>Shaping</title>
<para>
Shapers delay packets to meet a desired rate.
</para>
<para>
Shaping is the mechanism by which packets are delayed before
transmission in an output queue to meet a desired output rate. This is
one of the most common desires of users seeking bandwidth control
solutions. The act of delaying a packet as part of a traffic control
solution makes every shaping mechanism into a non-work-conserving
mechanism, meaning roughly: "Work is required in order to delay
packets."
</para>
<para>
Viewed in reverse, a non-work-conserving queuing mechanism is performing
a shaping function. A work-conserving queuing mechanism (see
&link-sch_prio;) would not be capable of delaying a packet.
</para>
<para>
Shapers attempt to limit or ration traffic to meet but not exceed a
configured rate (frequently measured in packets per second or bits/bytes
per second). As a side effect, shapers can smooth out bursty traffic
<footnote>
<para>
This smoothing effect is not always desirable, hence the HTB
parameters burst and cburst.
</para>
</footnote>.
</para>
</section>
<section id="e-scheduling">
<title>Scheduling</title>
<para>
Schedulers arrange and/or rearrange packets for output.
</para>
<para>
Scheduling is the mechanism by which packets are arranged (or
rearranged) between input and output of a particular queue. The
overwhelmingly most common scheduler is the FIFO (first-in first-out)
scheduler. From a larger perspective, any set of traffic control
mechanisms on an output queue can be regarded as a scheduler, because
packets are arranged for output.
</para>
<para>
Other generic scheduling mechanisms attempt to compensate for various
networking conditions. A fair queuing algorithm (see &link-sch_sfq;)
attempts to prevent any single client or flow from dominating the
network usage. A round-robin algorithm (see &link-sch_wrr;) gives each
flow or client a turn to dequeue packets. Other sophisticated
scheduling algorithms attempt to prevent backbone overload (see
&link-sch_gred;) or refine other scheduling mechanisms (see
&link-sch_esfq;).
</para>
</section>
<section id="e-classifying">
<title>Classifying</title>
<para>
Classifiers sort traffic into output queues.
</para>
<para>
Classifying is the mechanism by which packets are separated for
different treatment, possibly different output queues. During the
process of accepting, routing and transmitting a packet, a networking
device can classify the packet a number of different ways.
Classification can include
<link linkend="e-marking">marking</link> the packet, which usually
happens on the boundary of a network under a single administrative
control or classification can occur on each hop individually.
</para>
<para>
The Linux model (see
<xref linkend="c-filter"/>) allows for a packet to cascade across a
series of classifiers in a traffic control structure and to be
classified in conjunction with
<link linkend="e-policing">policers</link> (see also
<xref linkend="c-police"/>).
</para>
</section>
<section id="e-policing">
<title>Policing</title>
<para>
Policers measure and limit traffic in a particular queue.
</para>
<para>
Policing is a mechanism by which traffic inbound to a particular queue
(or class, in the Linux system) can be limited. Policing is most
frequently used on the network border to ensure that a peer is not
consuming more than its allocated bandwidth. A policer will accept
traffic to a certain rate, and then perform an action on traffic
exceeding this rate. A rather harsh solution is to
<link linkend="e-dropping">drop</link> the traffic, although the
traffic could be
<link linkend="e-classifying">reclassified</link> instead of being
dropped.
</para>
<para>
</para>
</section>
<section id="e-dropping">
<title>Dropping</title>
<para>
Dropping discards an entire packet, flow or classification.
</para>
<para>
Dropping a packet is a mechanism by which a packet is discarded.
</para>
<para>
</para>
</section>
<section id="e-marking">
<title>Marking</title>
<para>
Marking is a mechanism by which the packet (or packet meta-data?) is
identified.
</para>
<para>
FIXME - I need to determine whether marking is for local use only or if
the packet itself is altered (DiffServ domain?) - FIXME
</para>
<para>
<foreignphrase>N.B.</foreignphrase>, this is not
<constant>fwmark</constant>
</para>
</section>
</section>
<!-- end of file -->

34
LDP/howto/docbook/Traffic-Control-HOWTO/examples.xml Normal file
View File

@ -0,0 +1,34 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="examples">
<title>Examples</title>
<para>
</para>
</section>
<!-- end of file -->

177
LDP/howto/docbook/Traffic-Control-HOWTO/intro.xml Normal file
View File

@ -0,0 +1,177 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="intro">
<title>Introduction to Linux Traffic Control</title>
<para>
Linux offers a very rich set of tools for managing and manipulating the
transmission of packets. The larger Linux community is very familiar with
the tools available under Linux for packet mangling and firewalling
(netfilter, and before that, ipchains) as well as hundreds of network
services which can run on the operating system. Few inside the community
and fewer outside the Linux community are aware of the tremendous power of
the traffic control subsystem which has grown and matured under kernels
2.2 and 2.4.
</para>
<para>
This HOWTO purports to introduce the
<link linkend="overview">concepts of traffic control</link>,
<link linkend="elements">the traditional elements (in general)</link>,
<link linkend="components">the components of the Linux traffic control
implementation</link> and provide some
<link linkend="rules">guidelines</link>
<!-- and <link linkend="examples">examples</link> -->.
This HOWTO represents the collection, amalgamation and synthesis of the
&url-lartc-howto;, documentation from individual projects and importantly
the &url-lartc-mailinglist; over a period of study.
</para>
<para>
The impatient soul, who simply wishes to experiment right now, is
recommended to the &url-tcng-htb-howto; and &url-lartc-howto; for
immediate satisfaction.
</para>
<para>
</para>
<section id="i-assumptions">
<title>Target audience and assumptions about the reader</title>
<para>
The target audience for this HOWTO is the network administrator or savvy
home user who desires an introduction to the field of traffic control
and an overview of the tools available under Linux for implementing
traffic control.
</para>
<para>
I assume that the reader is comfortable with Unix concepts and the
command line and has a basic knowledge of IP networking. Users who wish
to implement traffic control may require the ability to patch, compile
and install a kernel or software package
<footnote>
<para>
See <xref linkend="software"/> for more details on the use or
installation of a particular traffic control mechanism, kernel or
command line utility.
</para>
</footnote>. For users with newer kernels
(2.4.20+, see also
<xref linkend="s-kernel"/>), however, the ability to install and use
software may be all that is required.
</para>
<para>
Broadly speaking, this HOWTO was written with a sophisticated user in
mind, perhaps one who has already had experience with traffic control
under Linux. I have quite deliberately assumed that the reader may have
no prior traffic control experience, however, as this niche of
documentation does not appear to be currently filled.
</para>
</section>
<section id="i-conventions">
<title>Conventions</title>
<para>
This text was written in
<ulink url="http://www.docbook.org/">DocBook</ulink>
(<ulink url="http://www.docbook.org/xml/4.2/index.html">version 4.2</ulink>)
with
<ulink url="http://vim.sourceforge.net/"><command>vim</command></ulink>.
All formatting has been applied by
<ulink url="http://xmlsoft.org/XSLT/">xsltproc</ulink> based on
<ulink url="http://docbook.sourceforge.net/projects/xsl/">DocBook
XSL</ulink> and
<ulink url="http://www.tldp.org/LDP/LDP-Author-Guide/usingldpxsl.html">LDP
XSL</ulink> stylesheets. Typeface formatting and display conventions
are similar to most printed and electronically distributed technical
documentation.
</para>
</section>
<section id="i-recommendation">
<title>Recommended approach</title>
<para>
I strongly recommend to the eager reader making a first foray into the
discipline of traffic control, to become only casually familiar with the
&link-tc; command line utility, before concentrating on &link-tcng;. The
&tcng; software package defines an entire language for describing
traffic control structures.
At first, this language may seem daunting, but mastery of these basics
will quickly provide the user with a much wider ability to employ (and
deploy) traffic control configurations than the direct use of &tc;
would afford.
</para>
<para>
Where possible, I'll try to prefer describing the behaviour of
the Linux traffic control system in an abstract manner, although in
many cases I'll need to supply the syntax of one or the other common
systems for defining these structures. I may not supply examples in
both the &tcng; language and the &tc; command line, so the wise user
will have some familiarity with both.
</para>
<para>
</para>
</section>
<section id="i-missing">
<title>Missing content, corrections and feedback</title>
<para>
There is content yet missing from this HOWTO. In particular, the
following items will be added at some point to this documentation.
</para>
<itemizedlist>
<listitem>
<para>
A description and diagram of &sch_gred;, &sch_wrr;, &sch_prio;
and &sch_cbq;.
</para>
</listitem>
<listitem>
<para>
A section of examples.
</para>
</listitem>
<listitem>
<para>
A section detailing the classifiers.
</para>
</listitem>
<listitem>
<para>
A section discussing the techniques for measuring traffic.
</para>
</listitem>
</itemizedlist>
<para>
I welcome suggestions, corrections and feedback at &email;. All errors
and omissions are strictly my fault. Although I have made every effort
to verify the factual correctness of the content presented herein, I
cannot accept any responsibility for actions taken under the influence
of this documentation.
</para>
<para>
</para>
</section>
</section>
<!-- end of file -->

151
LDP/howto/docbook/Traffic-Control-HOWTO/links.xml Normal file
View File

@ -0,0 +1,151 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="links">
<title>Annotated Traffic Control Links</title>
<para>
This section identifies a number of links to documentation
about traffic control and Linux traffic control software. Each link will
be listed with a brief description of the content at that site.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://luxik.cdi.cz/~devik/qos/htb/">HTB
site</ulink>,
&url-qdisc-htb-userguide; and
&url-qdisc-htb-theory;
(<emphasis>Martin <quote>devik</quote> Devera</emphasis>)
</para>
<para>
Hierarchical Token Bucket, &link-sch_htb;, is a classful queuing
discipline. Widely used and supported it is also fairly well
documented in the user guide and at
<ulink url="http://www.docum.org/">Stef Coene's site</ulink>
(see below).
</para>
</listitem>
<listitem>
<para>
<ulink url="http://tcng.sourceforge.net/">&tcng; (Traffic Control
Next Generation)</ulink> and
<ulink url="http://linux-ip.net/gl/tcng/">&tcng; manual</ulink>
(<emphasis>Werner Almesberger</emphasis>)
</para>
<para>
The &tcng; software includes a language and a set of tools for
creating and testing traffic control structures. In addition to
generating &tc; commands as output, it is also capable of providing
output for non-Linux applications. A key piece of the &tcng; suite
which is ignored in this documentation is the <command>tcsim</command>
traffic control simulator.
</para>
<para>
The user manual provided with the &tcng; software has been converted
to HTML with <command>latex2html</command>. The distribution comes
with the TeX documentation.
</para>
</listitem>
<listitem>
<para>
<ulink url="ftp://ftp.inr.ac.ru/ip-routing/">&iproute2;</ulink> and
<ulink url="http://linux-ip.net/gl/ip-cref/">&iproute2; manual</ulink>
(<emphasis>Alexey Kuznetsov</emphasis>)
</para>
<para>
This is a the source code for the &iproute2; suite, which includes the
essential &tc; binary. Note, that as of
iproute2-2.4.7-now-ss020116-try.tar.gz, the package did not support
&sch_htb;, so a patch available from the &url-qdisc-htb; site will be
required.
</para>
<para>
The manual documents the entire suite of tools, although the &tc;
utility is not adequately documented here. The ambitious reader is
recommended to the LARTC HOWTO after consuming this introduction.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.docum.org/">Documentation, graphs, scripts and
guidelines to traffic control under Linux</ulink>
(<emphasis>Stef Coene</emphasis>)
</para>
<para>
Stef Coene has been gathering statistics and test results, scripts and
tips for the use of QoS under Linux. There are some particularly
useful graphs and guidelines available for implementing traffic
control at Stef's site.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://lartc.org/howto/">LARTC HOWTO</ulink>
(<emphasis>bert hubert, et. al.</emphasis>)
</para>
<para>
The Linux Advanced Routing and Traffic Control HOWTO is one of the key
sources of data about the sophisticated techniques which are available
for use under Linux. The Traffic Control Introduction HOWTO should
provide the reader with enough background in the language and concepts
of traffic control. The LARTC HOWTO is the next place the reader
should look for general traffic control information.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://linux-ip.net/">Guide to IP Networking with
Linux</ulink> (<emphasis>Martin A. Brown</emphasis>)
</para>
<para>
Not directly related to traffic control, this site includes articles
and general documentation on the behaviour of the Linux IP layer.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://diffserv.sourceforge.net/">Linux DiffServ
project</ulink>
</para>
<para>
Mercilessly snipped from the main page of the DiffServ site...
</para>
<blockquote>
Differentiated Services (short: Diffserv) is an architecture for
providing different types or levels of service for network traffic.
One key characteristic of Diffserv is that flows are aggregated in
the network, so that core routers only need to distinguish a
comparably small number of aggregated flows, even if those flows
contain thousands or millions of individual flows.
</blockquote>
</listitem>
</itemizedlist>
</section>
<!-- end of file -->

46
LDP/howto/docbook/Traffic-Control-HOWTO/measuring.xml Normal file
View File

@ -0,0 +1,46 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="measuring">
<title>Measuring Bandwidth and Usage</title>
<para>
</para>
<section id="m-tc">
<title>Using "tc -s class show"</title>
<para>
</para>
</section>
<section id="m-iptraf">
<title>Using iptraf</title>
<para>
</para>
</section>
</section>
<!-- end of file -->

376
LDP/howto/docbook/Traffic-Control-HOWTO/overview.xml Normal file
View File

@ -0,0 +1,376 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="overview">
<title>Overview of Concepts</title>
<para>
This section will
<link linkend="o-what-is">introduce traffic control</link> and
<link linkend="o-why-use">examine reasons for it</link>,
identify a few
<link linkend="o-advantages">advantages</link> and
<link linkend="o-disadvantages">disadvantages</link> and
introduce key concepts used in traffic control.
</para>
<section id="o-what-is">
<title>What is it?</title>
<para>
Traffic control is the name given to the sets of queuing systems and
mechanisms by which packets are received and transmitted on a router.
This includes deciding which (and whether) packets to accept at what
rate on the input of an interface and determining which packets to
transmit in what order at what rate on the output of an interface.
</para>
<para>
In the overwhelming majority of situations, traffic control consists of
a single queue which collects entering packets and dequeues them as
quickly as the hardware (or underlying device) can accept them.
</para>
<para>
Queues exist in software on any networked system. On an outbound
network interface, a web server may be able to fill up the output queue
very quickly, meaning that the queuing mechanism will transmit as fast
as it can to the hardware, but that may be slower than the software can
supply data. This would leave a full queue between the software and the
hardware. There's nothing intrinsically wrong with this, but the
super-efficient web server may be hogging transmit bandwidth from a
slower mail server.
</para>
<para>
On the other hand, a network interface may be able to supply packets to
the operating system faster than the operating system can accept the
packets. Here again, the packets will build up in a queue. These are
two simplistic examples of the already existing queues in a networked
device.
</para>
<para>
Traffic control is the set of tools which allows the user to have
granular control over these queues and the queuing mechanisms of a
networked device. The power to rearrange traffic flows and packets with
these tools is tremendous and can be complicated, but is no substitute
for adequate bandwidth.
</para>
<para>
The term Quality of Service (QoS) is often used as a synonym for traffic
control.
</para>
</section>
<section id="o-why-use">
<title>Why use it?</title>
<para>
Packet-switched networks differ from circuit based networks in one very
important regard. A packet-switched network itself is stateless. A
circuit-based network (such as a telephone network) must hold state
within the network. IP networks are stateless and packet-switched
networks by design; in fact, this statelessness is one of the
fundamental strengths of IP.
</para>
<para>
The weakness of this statelessness is the lack of differentiation
between types of flows. In simplest terms, traffic control allows an
administrator to queue packets differently based on attributes of the
packet. It can even be used to simulate the behaviour of a
circuit-based network. This introduces statefulness into the stateless
network.
</para>
<para>
There are many practical reasons to consider traffic control, and many
scenarios in which using traffic control makes sense. Below are some
examples of common problems which can be solved or at least ameliorated
with these tools.
</para>
<para>
The list below is not an exhaustive list of the sorts of solutions
available to users of traffic control, but introduces the
types of problems that can be solved by using traffic control to
maximize the usability of a network connection.
</para>
<itemizedlist>
<title>Common traffic control solutions</title>
<listitem>
<para>
Limit total bandwidth to a known rate; &link-sch_tbf;,
&link-sch_htb; with child class(es).
</para>
</listitem>
<listitem>
<para>
Limit the bandwidth of a particular user, service or client;
&link-sch_htb; classes and &elements-classifying; with a
&linux-filter;. traffic.
</para>
</listitem>
<listitem>
<para>
Maximize TCP throughput on an asymmetric link; prioritize
transmission of ACK packets, &link-wondershaper;.
</para>
</listitem>
<listitem>
<para>
Reserve bandwidth for a particular application or user;
&link-sch_htb; with children classes and &elements-classifying;.
</para>
</listitem>
<listitem>
<para>
Prefer latency sensitive traffic; &link-sch_prio; inside an
&link-sch_htb; class.
</para>
</listitem>
<listitem>
<para>
Managed oversubscribed bandwidth; &link-sch_htb; with borrowing.
</para>
</listitem>
<listitem>
<para>
Allow equitable distribution of unreserved bandwidth; &link-sch_htb;
with borrowing.
</para>
</listitem>
<listitem>
<para>
Ensure that a particular type of traffic is dropped; &linux-policer;
attached to a &linux-filter; with a &linux-drop; action.
</para>
</listitem>
</itemizedlist>
<para>
Remember, too that sometimes, it is simply better to purchase more
bandwidth. Traffic control does not solve all problems!
</para>
<para>
</para>
</section>
<section id="o-advantages">
<title>Advantages</title>
<para>
When properly employed, traffic control should lead to more predictable
usage of network resources and less volatile contention for these
resources. The network then meets the goals of the traffic control
configuration. Bulk download traffic can be allocated a reasonable
amount of bandwidth even as higher priority interactive traffic is
simultaneously
serviced. Even low priority data transfer such as mail can
be allocated bandwidth without tremendously affecting the other classes
of traffic.
</para>
<para>
In a larger picture, if the traffic control configuration represents
policy which has been communicated to the users, then users (and,
by extension, applications) know what to expect from the network.
</para>
<para>
</para>
</section>
<section id="o-disadvantages">
<title>Disdvantages</title>
<para>
</para>
<para>
Complexity is easily one of the most significant disadvantages of using
traffic control. There are ways to become familiar with traffic control
tools which ease the learning curve about traffic control and its
mechanisms, but identifying a traffic control misconfiguration can be
quite a challenge.
</para>
<para>
Traffic control when used appropriately can lead to more equitable
distribution of network resources. It can just as easily be installed
in an inappropriate manner leading to further and more divisive
contention for resources.
</para>
<para>
The computing resources required on a router to support a traffic
control scenario need to be capable of handling the increased cost of
maintaining the traffic control structures. Fortunately, this is a
small incremental cost, but can become more significant as the
configuration grows in size and complexity.
</para>
<para>
For personal use, there's no training cost associated with the use of
traffic control, but a company may find that purchasing more bandwidth
is a simpler solution than employing traffic control. Training
employees and ensuring depth of knowledge may be more costly than
investing in more bandwidth.
</para>
<para>
Although
traffic control on packet-switched networks covers a larger conceptual
area, you can think of traffic control as a way to provide [some of] the
statefulness of a circuit-based network to a packet-switched network.
</para>
</section>
<section id="o-queues">
<title>Queues</title>
<para>
Queues form the backdrop for all of traffic control.
Practically speaking, a queue is a number of items waiting for an action
or service. In networking, a queue is the place where packets (our
units) wait to be transmitted by the hardware (the service). In the
simplest model, packets are transmitted in a first-come first-serve
basis
<footnote>
<para>
This queueing model has long been used in civilized countries to
distribute scant food or provisions equitably. William Faulkner is
reputed to have walked to the front of the line to fetch his share,
proving that the FIFO model doesn't always suit the consumer.
</para>
</footnote>.
In the discipline of computer networking (and more generally
computer science), this sort of a queue is known as a &sch_fifo;.
</para>
<para>
Without any other mechanisms, a queue doesn't offer any promise for
traffic control. There are only two interesting actions in a queue.
Anything entering a queue is enqueued into the queue. To remove an item
from a queue is to dequeue that item.
</para>
<para>
A queue becomes much more interesting when coupled with other mechanisms
which can delay, rearrange, drop and prioritize multiple queues.
</para>
<para>
From the perspective of the higher layer software, a packet is simply
enqueued for transmission, and the manner and order in which the
enqueued packets are transmitted is immaterial to the higher layer. So,
to the higher layer, the entire traffic control system may appear as a
single queue. It is only by examining the internals of this layer that
the traffic control structures become exposed and available.
</para>
</section>
<section id="o-flows">
<title>Flows</title>
<para>
A flow is a distinct connection between two hosts. Any unique set of
packets (perhaps representing a conversation) between two hosts can be
regarded as a flow. Under TCP the concept of a connection with a source
IP and port and destination IP and port represents a flow. A UDP flow
can be similarly defined.
</para>
<para>
Traffic control mechanisms frequently separate traffic into classes of
flows which can be aggregated and transmitted as an aggregated flow
(consider DiffServ). Alternate mechanisms may attempt to divide
bandwidth equally based on the individual flows.
</para>
<para>
Flows become important when attempting to divide bandwidth equally among
a set of competing flows, especially when some applications deliberately
build a large number of flows.
</para>
</section>
<section id="o-tokens">
<title>Tokens and buckets</title>
<anchor id="o-buckets" xreflabel="Tokens and buckets"/>
<para>
Two of the key underpinnings of a &elements-shaping; mechanisms are
the interrelated concepts of tokens and buckets.
</para>
<para>
In order to control the rate of dequeuing, an implementation can count
the number of packets or bytes dequeued as each item is dequeued,
although this requires complex usage of timers and measurements to limit
accurately. Instead of calculating the current usage and time, one
method, used widely in traffic control, is to generate tokens at a
desired rate, and only dequeue packets or bytes if a token is available.
</para>
<para>
Consider the analogy of an amusement park ride with a queue of people
waiting to experience the ride. Let's imagine a track on which carts
traverse a fixed track. The carts arrive at the head of the queue at a
fixed rate. In order to enjoy the ride, each person must wait for an
available cart. The cart is analogous to a token and the person is
analogous to a packet. Again, this mechanism is a rate-limiting or
&elements-shaping; mechanism.
</para>
<para>
The &link-sch_tbf; qdisc is a classical example of a shaper (the section
on &sch_tbf; includes a diagram which may help to visualize the token
and bucket concepts). The &sch_tbf; generates &param-rate; tokens and
only transmits packets when a token is available. Tokens are a generic
shaping concept.
</para>
<para>
In the case that a queue does not need tokens immediately, the tokens
can be collected until they are needed. To collect tokens indefinitely
would negate any benefit of shaping so tokens are collected until a
certain number of tokens has been reached. Now, the queue has tokens
available for a large number of packets or bytes which need to be
dequeued. These intangible tokens are stored in an intangible bucket,
and the number of tokens that can be stored depend on the size of the
bucket.
</para>
<para>
This also means that a bucket full of tokens is available at any
instant. Very predictable regular traffic can be handled by small
buckets. Larger buckets may be required for burstier traffic, unless
one of the desired goals is to reduce the burstiness of the
&concepts-flows;.
</para>
<para>
The concepts of tokens and buckets are closely interrelated and are used
in both &link-sch_tbf; (one of the &classless-qdiscs;) and
&link-sch_htb; (one of the &classful-qdiscs;).
Within the &tcng; language, the use of two- and three-color meters is
indubitably a token and bucket concept.
</para>
</section>
<section id="o-packets">
<title>Packets and frames</title>
<anchor id="o-frames"/>
<para>
The terms for data sent across network changes depending on the layer
the user is examining. This document will rather impolitely (and
somewhat incorrectly) gloss over the technical distinction between
packets and frames although they are outlined here.
</para>
<para>
The word frame is typically used to describe a layer 2 (data link) unit
of data to be forwarded to the next recipient. Ethernet interfaces, PPP
interfaces, and T1 interfaces all name their layer 2 data unit a frame.
The frame is actually the unit on which traffic control is performed.
</para>
<para>
A packet, on the other hand, is a higher layer concept, representing
layer 3 (network) units. The term packet is preferred in this
documentation, although it is slightly inaccurate.
</para>
</section>
</section>
<!-- end of file -->

208
LDP/howto/docbook/Traffic-Control-HOWTO/rules.xml Normal file
View File

@ -0,0 +1,208 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="rules">
<title>Rules, Guidelines and Approaches</title>
<para>
</para>
<section id="r-general">
<title>General Rules of Linux Traffic Control</title>
<para>
There are a few general rules which ease the study of Linux traffic
control.
Traffic control structures under Linux are the same whether the initial
configuration has been done with &link-tcng; or with &link-tc;.
</para>
<itemizedlist>
<listitem>
<para>
Any device performing a shaping function should be the bottleneck on
the link, and should be shaping slightly below the maximum available
link bandwidth. This prevents queues from forming in other routers,
affording maximum control of packet latency/deferral to the shaping
device.
</para>
</listitem>
<listitem>
<para>
A device can only shape traffic it transmits
<footnote>
<para>
In fact, the
<link linkend="s-imq">Intermediate Queuing Device
(IMQ)</link> simulates an output device onto which traffic
control structures can be attached. This clever solution allows
a networking device to shape ingress traffic in the same fashion
as egress traffic. Despite the apparent contradiction of the
rule, IMQ appears as a device to the kernel. Thus, there has
been no violation of the rule, but rather a sneaky
reinterpretation of that rule.
</para>
</footnote>. Because the traffic has already been received on an
input interface, the traffic cannot be shaped. A traditional
solution to this problem is an ingress policer.
</para>
</listitem>
<listitem>
<para>
Every interface must have a &linux-qdisc;. The default qdisc
(the &link-sch_pfifo_fast; qdisc) is used when another qdisc is not
explicitly attached to the interface.
</para>
</listitem>
<listitem>
<para>
One of the &classful-qdiscs; added to an interface with no children
classes typically only consumes CPU for no benefit.
</para>
</listitem>
<listitem>
<para>
Any newly created class contains a &link-sch_fifo;.
This qdisc can be replaced explicitly with any other qdisc. The
&sch_fifo; qdisc will be removed implicitly if a child class is
attached to this class.
</para>
</listitem>
<listitem>
<para>
Classes directly attached to the &root-qdisc; can be used to
simulate virtual circuits.
</para>
</listitem>
<listitem>
<para>
A &linux-filter; can be attached to classes or one of the
&classful-qdiscs;.
</para>
</listitem>
</itemizedlist>
<para>
</para>
<para>
</para>
<para>
</para>
<para>
</para>
</section>
<!--
<section id="r-classes">
<title>Rules for Classes</title>
<para>
</para>
</section>
-->
<section id="r-known-bandwidth">
<title>Handling a link with a known bandwidth</title>
<para>
&sch_htb; is an ideal &linux-qdisc; to use on a link with a known
bandwidth, because the innermost (root-most) class can be set to the
maximum bandwidth available on a given link. Flows can be further
subdivided into children classes, allowing either guaranteed bandwidth
to particular classes of traffic or allowing preference to specific
kinds of traffic.
</para>
<para>
</para>
<para>
</para>
</section>
<section id="r-unknown-bandwidth">
<title>Handling a link with a variable (or unknown) bandwidth</title>
<para>
In theory, the &sch_prio; scheduler is an ideal match for links with
variable bandwidth, because it is a work-conserving &linux-qdisc; (which
means that it provides no &elements-shaping;). In the case of a link
with an unknown or fluctuating bandwidth, the &sch_prio; scheduler
simply prefers to dequeue any available packet in the highest priority
band first, then falling to the lower priority queues.
</para>
<!--
FIXME:
it seems like a PRIO qdisc would always be dequeuing
packets as quickly as it got them, so is really only useful
inside a shaping class, since (in most situations), the
hardware is ready to dequeue a packet before there is a
backlog in the class. Without a shaping class around this
PRIO qdisc, I'd expect that packets would end up queuing in
an upstream device (a modem or router).
-->
<para>
</para>
<para>
</para>
</section>
<section id="r-sharing-flows">
<title>Sharing/splitting bandwidth based on flows</title>
<para>
Of the many types of contention for network bandwidth, this is one of
the easier types of contention to address in general. By using the
&sch_sfq; qdisc, traffic in a particular queue can be separated into
flows, each of which will be serviced fairly (inside that queue).
Well-behaved applications (and users) will find that using &sch_sfq; and
&sch_esfq; are sufficient for most sharing needs.
</para>
<para>
The Achilles heel of these fair queuing algorithms is a misbehaving user
or application which opens many connections simultaneously (e.g., eMule,
eDonkey, Kazaa). By creating a large number of individual flows, the
application can dominate slots in the fair queuing algorithm. Restated,
the fair queuing algorithm has no idea that a single application is
generating the majority of the flows, and cannot penalize the user.
Other methods <!-- FIXME; link here --> are called for.
</para>
<para>
</para>
</section>
<section id="r-sharing-ips">
<title>Sharing/splitting bandwidth based on IP</title>
<para>
For many administrators this is the ideal method of dividing bandwidth
amongst their users. Unfortunately, there is no easy solution, and it
becomes increasingly complex with the number of machine sharing a
network link.
</para>
<para>
To divide bandwidth equitably between <parameter>N</parameter> IP
addresses, there must be <parameter>N</parameter> classes.
</para>
<para>
</para>
</section>
</section>
<!-- end of file -->

72
LDP/howto/docbook/Traffic-Control-HOWTO/scripts.xml Normal file
View File

@ -0,0 +1,72 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="scripts">
<title>Scripts for use with QoS/Traffic Control</title>
<para>
</para>
<para>
</para>
<para>
</para>
<section id="sc-wondershaper">
<title>wondershaper</title>
<para>
More to come, see &url-wondershaper;.
</para>
</section>
<section id="sc-myshaper">
<title>ADSL Bandwidth HOWTO script (<filename>myshaper</filename>)</title>
<para>
More to come, see &url-myshaper;.
</para>
</section>
<section id="sc-htb.init">
<title><filename>htb.init</filename></title>
<para>
More to come, see &url-htb.init;.
</para>
</section>
<section id="sc-tcng.init">
<title><filename>tcng.init</filename></title>
<para>
More to come, see &url-tcng.init;.
</para>
</section>
<section id="sc-cbq.init">
<title><filename>cbq.init</filename></title>
<para>
More to come, see &url-cbq.init;.
</para>
</section>
</section>
<!-- end of file -->

47
LDP/howto/docbook/Traffic-Control-HOWTO/sections.ent Normal file
View File

@ -0,0 +1,47 @@
<!-- start of file -->
<!-- This .ent file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<!-- Each entity is a SYSTEM entity which includes another .xml file -->
<!-- -->
<!ENTITY ch-articleinfo SYSTEM "articleinfo.xml" >
<!ENTITY ch-intro SYSTEM "intro.xml" >
<!ENTITY ch-overview SYSTEM "overview.xml" >
<!ENTITY ch-elements SYSTEM "elements.xml" >
<!ENTITY ch-components SYSTEM "components.xml" >
<!ENTITY ch-software SYSTEM "software.xml" >
<!ENTITY ch-classful-qdiscs SYSTEM "classful-qdiscs.xml" >
<!ENTITY ch-classless-qdiscs SYSTEM "classless-qdiscs.xml" >
<!ENTITY ch-rules SYSTEM "rules.xml" >
<!ENTITY ch-examples SYSTEM "examples.xml" >
<!ENTITY ch-scripts SYSTEM "scripts.xml" >
<!ENTITY ch-diagram SYSTEM "diagram.xml" >
<!ENTITY ch-measuring SYSTEM "measuring.xml" >
<!ENTITY ch-links SYSTEM "links.xml" >
<!-- future chapter
<!ENTITY ch-classless-qdiscs SYSTEM "classless-qdiscs.xml" >
-->
<!-- end of file -->

278
LDP/howto/docbook/Traffic-Control-HOWTO/shorthand.ent Normal file
View File

@ -0,0 +1,278 @@
<!-- start of file -->
<!-- This .ent file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<!-- Versioning information and meta-data -->
<!-- -->
<!ENTITY versionfile SYSTEM "VERSION" >
<!ENTITY version "&versionfile;" >
<!ENTITY pubdatefile SYSTEM "PUBDATE" >
<!ENTITY pubdate "&pubdatefile;" >
<!ENTITY email "<email>mabrown@securepipe.com</email>" >
<!-- Convenient abbreviations -->
<!-- -->
<!ENTITY eg "<foreignphrase>e.g.</foreignphrase>" >
<!ENTITY ie "<foreignphrase>i.e.</foreignphrase>" >
<!-- binaries and modules; software and so forth -->
<!-- -->
<!ENTITY iproute2
'<command>iproute2</command>' >
<!ENTITY tcng
'<command>tcng</command>' >
<!ENTITY link-tcng
'<link linkend="s-tcng"><command>tcng</command></link>' >
<!ENTITY tc
'<command>tc</command>' >
<!ENTITY link-tc
'<link linkend="s-iproute2-tc"><command>tc</command></link>' >
<!ENTITY cls_u32
'<constant>u32</constant>' >
<!ENTITY link-cls_u32
'<link linkend="cf-u32"><constant>u32</constant></link>' >
<!ENTITY sch_htb
'HTB' >
<!ENTITY link-sch_htb
'<link linkend="qc-htb">HTB</link>' >
<!ENTITY sch_cbq
'CBQ' >
<!ENTITY link-sch_cbq
'<link linkend="qc-cbq">CBQ</link>' >
<!ENTITY sch_prio
'PRIO' >
<!ENTITY link-sch_prio
'<link linkend="qc-prio">PRIO</link>' >
<!ENTITY sch_fifo
'FIFO' >
<!ENTITY link-sch_fifo
'<link linkend="qs-fifo">FIFO</link>' >
<!ENTITY sch_tbf
'TBF' >
<!ENTITY link-sch_tbf
'<link linkend="qs-tbf">TBF</link>' >
<!ENTITY sch_pfifo
'<constant>pfifo</constant>' >
<!ENTITY sch_bfifo
'<constant>bfifo</constant>' >
<!ENTITY sch_pfifo_fast
'<constant>pfifo_fast</constant>' >
<!ENTITY link-sch_pfifo_fast
'<link
linkend="qs-pfifo_fast"><constant>pfifo_fast</constant></link>' >
<!ENTITY sch_wrr
'WRR' >
<!ENTITY link-sch_wrr
'WRR' >
<!--
<!ENTITY link-sch_wrr
'<link linkend="qs-wrr">WRR</link>' >
-->
<!ENTITY sch_sfq
'SFQ' >
<!ENTITY link-sch_sfq
'<link linkend="qs-sfq">SFQ</link>' >
<!ENTITY sch_esfq
'ESFQ' >
<!ENTITY link-sch_esfq
'<link linkend="qs-esfq">ESFQ</link>' >
<!ENTITY sch_gred
'GRED' >
<!ENTITY link-sch_gred
'<link linkend="qs-gred">GRED</link>' >
<!ENTITY ingress-qdisc
'<constant>ingress</constant> qdisc' >
<!ENTITY root-qdisc
'<constant>root</constant> qdisc' >
<!ENTITY param-rate
'<parameter>rate</parameter>' >
<!ENTITY param-ceil
'<parameter>ceil</parameter>' >
<!ENTITY param-burst
'<parameter>burst</parameter>' >
<!ENTITY param-cburst
'<parameter>cburst</parameter>' >
<!ENTITY param-action
'<parameter>action</parameter>' >
<!ENTITY param-default
'<parameter>default</parameter>' >
<!ENTITY param-quantum
'<parameter>quantum</parameter>' >
<!ENTITY param-r2q
'<parameter>r2q</parameter>' >
<!ENTITY link-htb-param-rate
'<link linkend="vl-qc-htb-params-rate"><parameter>rate</parameter></link>' >
<!ENTITY link-htb-param-ceil
'<link linkend="vl-qc-htb-params-ceil"><parameter>ceil</parameter></link>' >
<!ENTITY link-htb-param-quantum
'<link linkend="vl-qc-htb-params-quantum"><parameter>quantum</parameter></link>' >
<!ENTITY link-htb-borrowing
'<link linkend="qc-htb-borrowing">borrowing model</link>' >
<!ENTITY link-htb-shaping
'<link linkend="qc-htb-borrowing">shaping</link>' >
<!-- Elements of Traffic Control -->
<!-- -->
<!ENTITY elements-classifying
'<link linkend="e-classifying">classifying</link>' >
<!ENTITY elements-shaping
'<link linkend="e-shaping">shaping</link>' >
<!ENTITY elements-scheduling
'<link linkend="e-scheduling">scheduling</link>' >
<!ENTITY elements-policing
'<link linkend="e-policing">policing</link>' >
<!ENTITY elements-dropping
'<link linkend="e-dropping">dropping</link>' >
<!ENTITY elements-marking
'<link linkend="e-marking">marking</link>' >
<!-- Some key concepts -->
<!-- -->
<!ENTITY concepts-flows
'<link linkend="o-flows">flows</link>' >
<!ENTITY concepts-tokens
'<link linkend="o-tokens">tokens</link>' >
<!ENTITY concepts-buckets
'<link linkend="o-buckets">buckets</link>' >
<!ENTITY concepts-queues
'<link linkend="o-queues">queues</link>' >
<!-- Linux components of Traffic Control -->
<!-- -->
<!ENTITY linux-qdisc
'<link linkend="c-qdisc"><constant>qdisc</constant></link>' >
<!ENTITY linux-class
'<link linkend="c-class"><constant>class</constant></link>' >
<!ENTITY linux-filter
'<link linkend="c-filter"><constant>filter</constant></link>' >
<!ENTITY linux-policer
'<link linkend="c-police"><constant>policer</constant></link>'>
<!ENTITY linux-drop
'<link linkend="c-drop"><constant>drop</constant></link>' >
<!ENTITY linux-classifier
'<link linkend="c-classifier"><constant>classifier</constant></link>' >
<!ENTITY linux-handle
'<link linkend="c-handle"><constant>handle</constant></link>' >
<!ENTITY linux-dsmark '<constant>dsmark</constant>' >
<!--
<!ENTITY linux-dsmark
'<link linkend="c-dsmark"><constant>dsmark</constant></link>' >
-->
<!ENTITY classful-qdiscs
'<link linkend="classful-qdiscs">classful qdiscs</link>' >
<!ENTITY classless-qdiscs
'<link linkend="classless-qdiscs">classless qdiscs</link>' >
<!-- Various commonly used URLs in Traffic Control -->
<!-- -->
<!ENTITY wondershaper
'wondershaper' >
<!ENTITY link-wondershaper
'<link linkend="sc-wondershaper">wondershaper</link>' >
<!-- Various commonly used URLs in Traffic Control -->
<!-- -->
<!ENTITY url-gfdl
"http://www.gnu.org/licenses/fdl.html" >
<!ENTITY url-docum.org
'<ulink url="http://docum.org/">http://docum.org/</ulink>' >
<!ENTITY url-lartc-howto
'<ulink url="http://lartc.org/howto/">LARTC HOWTO</ulink>' >
<!ENTITY url-lartc-howto-pfifo_fast
'<ulink
url="http://lartc.org/howto/lartc.qdisc.classless.html">pfifo-fast
section of the LARTC HOWTO</ulink>' >
<!ENTITY url-lartc-mailinglist
'<ulink
url="http://mailman.ds9a.nl/mailman/listinfo/lartc/">LARTC
mailing list</ulink>' >
<!ENTITY url-kernel-howto
'<ulink url="http://tldp.org/HOWTO/Kernel-HOWTO/">Kernel
HOWTO</ulink>' >
<!ENTITY url-iproute2-docs
'<ulink url="http://linux-ip.net/gl/ip-cref/">iproute2
documentation</ulink>' >
<!ENTITY url-tcng-docs
'<ulink url="http://linux-ip.net/gl/tcng/">tcng
documentation</ulink>' >
<!ENTITY url-linux-ip.net
'<ulink url="http://linux-ip.net/">linux-ip.net</ulink>' >
<!ENTITY url-tcng-htb-howto
'<ulink url="http://tldp.org/HOWTO/Traffic-Control-tcng-HTB-HOWTO/">
Traffic Control using tcng and HTB HOWTO</ulink>' >
<!ENTITY url-qdisc-esfq
'<ulink url="http://www.ssi.bg/~alex/esfq/">ESFQ</ulink>' >
<!ENTITY url-qdisc-wrr
'<ulink url="http://wipl-wrr.sourceforge.net/">WRR</ulink>' >
<!ENTITY url-qdisc-htb
'<ulink url="http://luxik.cdi.cz/~devik/qos/htb/">HTB</ulink>'>
<!ENTITY url-imq
'<ulink url="http://trash.net/~kaber/imq/">IMQ</ulink>' >
<!ENTITY url-cbq.init
'<ulink url="http://sourceforge.net/projects/cbqinit/"><filename>cbq.init</filename></ulink>' >
<!ENTITY url-htb.init
'<ulink url="http://sourceforge.net/projects/htbinit/"><filename>htb.init</filename></ulink>' >
<!ENTITY url-tcng.init
'<ulink url="http://linux-ip.net/code/tcng/tcng.init"><filename>tcng.init</filename></ulink>' >
<!ENTITY url-wondershaper
'<ulink url="http://lartc.org/wondershaper/">wondershaper</ulink>' >
<!ENTITY url-myshaper
'<ulink url="http://www.tldp.org/HOWTO/ADSL-Bandwidth-Management-HOWTO/implementation.html">myshaper</ulink>' >
<!ENTITY url-qdisc-htb-userguide
'<ulink url="http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm">HTB
user guide</ulink>'>
<!ENTITY url-qdisc-htb-theory
'<ulink url="http://luxik.cdi.cz/~devik/qos/htb/manual/theory.htm">HTB
theory</ulink>'>
<!ENTITY diag-htb-class
'http://linux-ip.net/traffic-control/htb-class.png' >
<!-- end of file -->

430
LDP/howto/docbook/Traffic-Control-HOWTO/software.xml Normal file
View File

@ -0,0 +1,430 @@
<!-- start of file -->
<!-- This .xml file is part of the Traffic-Control-HOWTO document -->
<!-- $Id$ -->
<!--
The article was authored by Martin A. Brown <mabrown@securepipe.com>
for the linux community, and has been released under the GNU Free
Documentation License (GFDL) through The Linux Documentation
Project (TLDP).
This HOWTO is likely available at the following address:
http://tldp.org/HOWTO/Traffic-Control-HOWTO/
-->
<!-- conventions used in this documentation....
- each section is a separate file
-->
<section id="software">
<title>Software and Tools</title>
<para>
</para>
<section id="s-kernel">
<title>Kernel requirements</title>
<para>
Many distributions provide kernels with modular or monolithic support
for traffic control (Quality of Service). Custom kernels may not
already provide support (modular or not) for the required features. If
not, this is a very brief listing of the required kernel options.
</para>
<para>
The user who has little or no experience compiling a kernel is
recommended to &url-kernel-howto;. Experienced kernel compilers should
be able to determine which of the below options apply to the desired
configuration, after reading a bit more about traffic control and
planning.
</para>
<example id="ex-s-kernel-options">
<title>Kernel compilation options
<footnote>
<para>
The options listed in this example are taken from a 2.4.20 kernel
source tree. The exact options may differ slightly from kernel
release to kernel release depending on patches and new schedulers
and classifiers.
</para>
</footnote>
</title>
<programlisting>
#
# QoS and/or fair queueing
#
CONFIG_NET_SCHED=y
CONFIG_NET_SCH_CBQ=m
CONFIG_NET_SCH_HTB=m
CONFIG_NET_SCH_CSZ=m
CONFIG_NET_SCH_PRIO=m
CONFIG_NET_SCH_RED=m
CONFIG_NET_SCH_SFQ=m
CONFIG_NET_SCH_TEQL=m
CONFIG_NET_SCH_TBF=m
CONFIG_NET_SCH_GRED=m
CONFIG_NET_SCH_DSMARK=m
CONFIG_NET_SCH_INGRESS=m
CONFIG_NET_QOS=y
CONFIG_NET_ESTIMATOR=y
CONFIG_NET_CLS=y
CONFIG_NET_CLS_TCINDEX=m
CONFIG_NET_CLS_ROUTE4=m
CONFIG_NET_CLS_ROUTE=y
CONFIG_NET_CLS_FW=m
CONFIG_NET_CLS_U32=m
CONFIG_NET_CLS_RSVP=m
CONFIG_NET_CLS_RSVP6=m
CONFIG_NET_CLS_POLICE=y
</programlisting>
</example>
<para>
A kernel compiled with the above set of options will provide modular
support for almost everything discussed in this documentation. The user
may need to <command>modprobe
<replaceable>module</replaceable></command> before using a given
feature. Again, the confused user is recommended to the
&url-kernel-howto;, as this document cannot adequately address questions
about the use of the Linux kernel.
</para>
</section>
<section id="s-iproute2">
<title>&iproute2; tools (&tc;)</title>
<para>
&iproute2; is a suite of command line utilities which
manipulate kernel structures for IP networking
configuration on a machine. For technical documentation on these tools,
see the &url-iproute2-docs; and for a more expository discussion, the
documentation at &url-linux-ip.net;. Of the tools in the &iproute2;
package, the binary &tc; is the only one used for traffic control. This
HOWTO will ignore the other tools in the suite.
</para>
<anchor id="s-iproute2-tc"/>
<para>
Because it interacts with the kernel to direct the creation, deletion
and modification of traffic control structures, the &tc; binary needs to
be compiled with support for all of the &linux-qdisc;s you wish to use.
In particular, the &sch_htb; qdisc is not supported yet in the upstream
&iproute2; package. See
<xref linkend="qc-htb"/> for more information.
</para>
<para>
The &tc; tool performs all of the configuration of the kernel structures
required to support traffic control. As a result of its many uses, the
command syntax can be described (at best) as arcane. The utility takes
as its first non-option argument one of three Linux traffic control
components, &linux-qdisc;, &linux-class; or &linux-filter;.
</para>
<example id="ex-s-iproute2-tc">
<title>&tc; command usage</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>tc</userinput>
<computeroutput>Usage: tc [ OPTIONS ] OBJECT { COMMAND | help }
where OBJECT := { qdisc | class | filter }
OPTIONS := { -s[tatistics] | -d[etails] | -r[aw] }</computeroutput>
</programlisting>
</example>
<para>
Each object accepts further and different options, and will be
incompletely described and documented below. The hints in the examples
below are designed to introduce the vagaries of &tc; command line
syntax. For more examples, consult the &url-lartc-howto;. For even
better understanding, consult the kernel and &iproute2; code.
</para>
<example id="ex-s-iproute2-tc-qdisc">
<title>&tc; &linux-qdisc;</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>tc qdisc add \</userinput> <co id="ex-s-itcq-tc" linkends="ex-s-itcq-tc-text"/>
<prompt>&gt; </prompt><userinput> dev eth0 \</userinput> <co id="ex-s-itcq-dev" linkends="ex-s-itcq-dev-text"/>
<prompt>&gt; </prompt><userinput> root \</userinput> <co id="ex-s-itcq-root" linkends="ex-s-itcq-root-text"/>
<prompt>&gt; </prompt><userinput> handle 1:0 \</userinput> <co id="ex-s-itcq-handle" linkends="ex-s-itcq-handle-text"/>
<prompt>&gt; </prompt><userinput> htb</userinput> <co id="ex-s-itcq-qdisc" linkends="ex-s-itcq-qdisc-text"/>
</programlisting>
<calloutlist>
<callout
arearefs="ex-s-itcq-tc"
id="ex-s-itcq-tc-text">
<para>
Add a queuing discipline. The verb could also be
<constant>del</constant>.
</para>
</callout>
<callout
arearefs="ex-s-itcq-dev"
id="ex-s-itcq-dev-text">
<para>
Specify the device onto which we are attaching the new queuing
discipline.
</para>
</callout>
<callout
arearefs="ex-s-itcq-root"
id="ex-s-itcq-root-text">
<para>
This means <quote>egress</quote> to &tc;. The word
<constant>root</constant> must be used, however. Another
qdisc with limited functionality, the &ingress-qdisc; can be
attached to the same device.
</para>
</callout>
<callout
arearefs="ex-s-itcq-handle"
id="ex-s-itcq-handle-text">
<para>
The &linux-handle; is a user-specified number of the form
<replaceable>major</replaceable>:<replaceable>minor</replaceable>.
The minor number for any queueing discipline handle must always be
zero (0).
</para>
</callout>
<callout
arearefs="ex-s-itcq-qdisc"
id="ex-s-itcq-qdisc-text">
<para>
This is the queuing discipline to attach, &sch_htb; in this
example. Queuing discipline specific parameters will follow this.
</para>
</callout>
</calloutlist>
</example>
<para>
Above was the simplest use of the &tc; utility for adding a queuing
discipline to a device. Here's an example of the use of &tc; to add a
class to an existing parent class.
</para>
<example id="ex-s-iproute2-tc-class">
<title>&tc; &linux-class;</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>tc class add \</userinput> <co id="ex-s-itcc-tc" linkends="ex-s-itcc-tc-text"/>
<prompt>&gt; </prompt><userinput> dev eth0 \</userinput> <co id="ex-s-itcc-dev" linkends="ex-s-itcc-dev-text"/>
<prompt>&gt; </prompt><userinput> parent 1:1 \</userinput> <co id="ex-s-itcc-parent" linkends="ex-s-itcc-parent-text"/>
<prompt>&gt; </prompt><userinput> classid 1:6 \</userinput> <co id="ex-s-itcc-classid" linkends="ex-s-itcc-classid-text"/>
<prompt>&gt; </prompt><userinput> htb \</userinput> <co id="ex-s-itcc-classtype" linkends="ex-s-itcc-classtype-text"/>
<prompt>&gt; </prompt><userinput> rate 256kbit \</userinput> <co id="ex-s-itcc-htb-rate" linkends="ex-s-itcc-htb-only-text"/>
<prompt>&gt; </prompt><userinput> ceil 512kbit</userinput> <co id="ex-s-itcc-htb-ceil" linkends="ex-s-itcc-htb-only-text"/>
</programlisting>
<calloutlist>
<callout
arearefs="ex-s-itcc-tc"
id="ex-s-itcc-tc-text">
<para>
Add a class. The verb could also be <constant>del</constant>.
</para>
</callout>
<callout
arearefs="ex-s-itcc-dev"
id="ex-s-itcc-dev-text">
<para>
Specify the device onto which we are attaching the new class.
</para>
</callout>
<callout
arearefs="ex-s-itcc-parent"
id="ex-s-itcc-parent-text">
<para>
Specify the parent &linux-handle; to which we are attaching the new class.
</para>
</callout>
<callout
arearefs="ex-s-itcc-classid"
id="ex-s-itcc-classid-text">
<para>
This is a unique &linux-handle;
(<replaceable>major</replaceable>:<replaceable>minor</replaceable>)
identifying this class. The minor number must be any non-zero (0)
number.
</para>
</callout>
<callout
arearefs="ex-s-itcc-classtype"
id="ex-s-itcc-classtype-text">
<para>
Both of the &classful-qdiscs; require that any children classes be
classes of the same type as the parent. Thus an &sch_htb; qdisc
will contain HTB classes.
</para>
</callout>
<callout
arearefs="ex-s-itcc-htb-rate ex-s-itcc-htb-ceil"
id="ex-s-itcc-htb-only-text">
<para>
This is a class specific parameter. Consult
<xref linkend="qc-htb"/> for more detail on this parameter.
</para>
</callout>
</calloutlist>
</example>
<para>
</para>
<example id="ex-s-iproute2-tc-filter">
<title>&tc; &linux-filter;</title>
<programlisting>
<prompt>[root@leander]# </prompt><userinput>tc filter add \</userinput> <co id="ex-s-itcf-tc" linkends="ex-s-itcf-tc-text"/>
<prompt>&gt; </prompt><userinput> dev eth0 \</userinput> <co id="ex-s-itcf-dev" linkends="ex-s-itcf-dev-text"/>
<prompt>&gt; </prompt><userinput> parent 1:0 \</userinput> <co id="ex-s-itcf-parent" linkends="ex-s-itcf-parent-text"/>
<prompt>&gt; </prompt><userinput> protocol ip \</userinput> <co id="ex-s-itcf-protocol" linkends="ex-s-itcf-protocol-text"/>
<prompt>&gt; </prompt><userinput> prio 5 \</userinput> <co id="ex-s-itcf-prio" linkends="ex-s-itcf-prio-text"/>
<prompt>&gt; </prompt><userinput> u32 \</userinput> <co id="ex-s-itcf-classifier" linkends="ex-s-itcf-classifier-text"/>
<prompt>&gt; </prompt><userinput> match ip port 22 0xffff \</userinput> <co id="ex-s-itcf-match-port" linkends="ex-s-itcf-match-text"/>
<prompt>&gt; </prompt><userinput> match ip tos 0x10 0xff \</userinput> <co id="ex-s-itcf-match-tos" linkends="ex-s-itcf-match-text"/>
<prompt>&gt; </prompt><userinput> flowid 1:6 \</userinput> <co id="ex-s-itcf-flowid" linkends="ex-s-itcf-flowid-text"/>
<prompt>&gt; </prompt><userinput> police \</userinput> <co id="ex-s-itcf-police" linkends="ex-s-itcf-police-text"/>
<prompt>&gt; </prompt><userinput> rate 32000bps \</userinput> <co id="ex-s-itcf-prate" linkends="ex-s-itcf-prate-text"/>
<prompt>&gt; </prompt><userinput> burst 10240 \</userinput> <co id="ex-s-itcf-burst" linkends="ex-s-itcf-burst-text"/>
<prompt>&gt; </prompt><userinput> mpu 0 \</userinput> <co id="ex-s-itcf-mpu" linkends="ex-s-itcf-mpu-text"/>
<prompt>&gt; </prompt><userinput> action drop/continue</userinput> <co id="ex-s-itcf-action" linkends="ex-s-itcf-action-text"/>
</programlisting>
<calloutlist>
<callout
arearefs="ex-s-itcf-tc"
id="ex-s-itcf-tc-text">
<para>
Add a filter. The verb could also be <constant>del</constant>.
</para>
</callout>
<callout
arearefs="ex-s-itcf-dev"
id="ex-s-itcf-dev-text">
<para>
Specify the device onto which we are attaching the new filter.
</para>
</callout>
<callout
arearefs="ex-s-itcf-parent"
id="ex-s-itcf-parent-text">
<para>
Specify the parent handle to which we are attaching the new
filter.
</para>
</callout>
<callout
arearefs="ex-s-itcf-protocol"
id="ex-s-itcf-protocol-text">
<para>
This parameter is required. It's use should be obvious, although
I don't know more.
</para>
</callout>
<callout
arearefs="ex-s-itcf-prio"
id="ex-s-itcf-prio-text">
<para>
The <parameter>prio</parameter> parameter allows a given filter to
be preferred above another. The <parameter>pref</parameter> is a
synonym.
</para>
</callout>
<callout
arearefs="ex-s-itcf-classifier"
id="ex-s-itcf-classifier-text">
<para>
This is a &linux-classifier;.
</para>
</callout>
<callout
arearefs="ex-s-itcf-match-port ex-s-itcf-match-tos"
id="ex-s-itcf-match-text">
<para>
These are parameters to the classifier. In this case, packets
with a type of service flag (indicating interactive usage) and
matching port 22 will be selected by this statement.
</para>
</callout>
<callout
arearefs="ex-s-itcf-flowid"
id="ex-s-itcf-flowid-text">
<para>
The <parameter>flowid</parameter> specifies the &linux-handle; of
the target class (or qdisc) to which a matching filter should send
its selected packets.
</para>
</callout>
<callout
arearefs="ex-s-itcf-police"
id="ex-s-itcf-police-text">
<para>
This is the &linux-policer;.
</para>
</callout>
<callout
arearefs="ex-s-itcf-prate"
id="ex-s-itcf-prate-text">
<para>
The policer will perform one action above this rate, and another
action below (see
<xref linkend="ex-s-itcf-action-text"/>).
</para>
</callout>
<callout
arearefs="ex-s-itcf-burst"
id="ex-s-itcf-burst-text">
<para>
The &param-burst; is an exact analog to &param-burst; in
&link-sch_htb; (the burst concept is a &concepts-buckets; concept).
</para>
</callout>
<callout
arearefs="ex-s-itcf-mpu"
id="ex-s-itcf-mpu-text">
<para>
The minimum policed unit.
</para>
</callout>
<callout xreflabel="action parameter"
arearefs="ex-s-itcf-action"
id="ex-s-itcf-action-text">
<para>
The &param-action; indicates what should be done if
the &param-rate; based on the attributes of the policer. The
first word specifies the action to take if the policer has been
exceeded. The second word specifies action to take otherwise.
</para>
</callout>
</calloutlist>
</example>
<para>
As evidenced above, the &tc; command line utility has an arcane and
complex syntax, even for simple operations such as these examples show.
It should come as no surprised to the reader that there exists an easier
way to configure Linux traffic control. See the next section,
<xref linkend="s-tcng"/>.
</para>
</section>
<section id="s-tcng">
<title>&tcng;, Traffic Control Next Generation</title>
<para>
FIXME; sing the praises of tcng. See also &url-tcng-htb-howto; and
&url-tcng-docs;.
</para>
<para>
Traffic control next generation (hereafter, &tcng;) provides all of the
power of traffic control under Linux with twenty percent of the
headache.
</para>
<para>
</para>
</section>
<section id="s-imq">
<title>IMQ, Intermediate Queuing device</title>
<para>
</para>
<para>
FIXME; must discuss IMQ. See also Patrick McHardy's website on
&url-imq;.
</para>
<para>
</para>
</section>
</section>
<!-- end of file -->