1 .TH TC 8 "16 December 2001" "iproute2" "Linux"
3 tc \- show / manipulate traffic control settings
7 .B qdisc [ add | change | replace | link | delete ] dev
15 [ qdisc specific parameters ]
20 .B class [ add | change | replace | delete ] dev
26 [ qdisc specific parameters ]
31 .B filter [ add | change | replace | delete ] dev
39 [ filtertype specific parameters ]
64 \fB[ -force ] -b\fR[\fIatch\fR] \fB[ filename ] \fR|
65 \fB[ \fB-n\fR[\fIetns\fR] name \fB] \fR}
69 \fB\-s\fR[\fItatistics\fR] |
70 \fB\-d\fR[\fIetails\fR] |
72 \fB\-p\fR[\fIretty\fR] |
77 is used to configure Traffic Control in the Linux kernel. Traffic Control consists
82 When traffic is shaped, its rate of transmission is under control. Shaping may
83 be more than lowering the available bandwidth - it is also used to smooth out
84 bursts in traffic for better network behaviour. Shaping occurs on egress.
88 By scheduling the transmission of packets it is possible to improve interactivity
89 for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering
90 is also called prioritizing, and happens only on egress.
94 Whereas shaping deals with transmission of traffic, policing pertains to traffic
95 arriving. Policing thus occurs on ingress.
99 Traffic exceeding a set bandwidth may also be dropped forthwith, both on
100 ingress and on egress.
103 Processing of traffic is controlled by three kinds of objects: qdiscs,
108 is short for 'queueing discipline' and it is elementary to
109 understanding traffic control. Whenever the kernel needs to send a
110 packet to an interface, it is
112 to the qdisc configured for that interface. Immediately afterwards, the kernel
113 tries to get as many packets as possible from the qdisc, for giving them
114 to the network adaptor driver.
116 A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure
117 First In, First Out queue. It does however store traffic when the network interface
118 can't handle it momentarily.
121 Some qdiscs can contain classes, which contain further qdiscs - traffic may
122 then be enqueued in any of the inner qdiscs, which are within the
124 When the kernel tries to dequeue a packet from such a
126 it can come from any of the classes. A qdisc may for example prioritize
127 certain kinds of traffic by trying to dequeue from certain classes
133 is used by a classful qdisc to determine in which class a packet will
134 be enqueued. Whenever traffic arrives at a class with subclasses, it needs
135 to be classified. Various methods may be employed to do so, one of these
136 are the filters. All filters attached to the class are called, until one of
137 them returns with a verdict. If no verdict was made, other criteria may be
138 available. This differs per qdisc.
140 It is important to notice that filters reside
142 qdiscs - they are not masters of what happens.
145 The classless qdiscs are:
148 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
152 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
153 queue which honors Type of Service flags, as well as the priority that may be
154 assigned to a packet.
157 Random Early Detection simulates physical congestion by randomly dropping
158 packets when nearing configured bandwidth allocation. Well suited to very
159 large bandwidth applications.
162 Stochastic Fairness Queueing reorders queued traffic so each 'session'
163 gets to send a packet in turn.
166 The Token Bucket Filter is suited for slowing traffic down to a precisely
167 configured rate. Scales well to large bandwidths.
168 .SH CONFIGURING CLASSLESS QDISCS
169 In the absence of classful qdiscs, classless qdiscs can only be attached at
170 the root of a device. Full syntax:
175 QDISC QDISC-PARAMETERS
185 qdisc is the automatic default in the absence of a configured qdisc.
188 The classful qdiscs are:
191 Class Based Queueing implements a rich linksharing hierarchy of classes.
192 It contains shaping elements as well as prioritizing capabilities. Shaping is
193 performed using link idle time calculations based on average packet size and
194 underlying link bandwidth. The latter may be ill-defined for some interfaces.
197 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
198 classes with an emphasis on conforming to existing practices. HTB facilitates
199 guaranteeing bandwidth to classes, while also allowing specification of upper
200 limits to inter-class sharing. It contains shaping elements, based on TBF and
201 can prioritize classes.
204 The PRIO qdisc is a non-shaping container for a configurable number of
205 classes which are dequeued in order. This allows for easy prioritization
206 of traffic, where lower classes are only able to send if higher ones have
207 no packets available. To facilitate configuration, Type Of Service bits are
209 .SH THEORY OF OPERATION
210 Classes form a tree, where each class has a single parent.
211 A class may have multiple children. Some qdiscs allow for runtime addition
212 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
215 Qdiscs which allow dynamic addition of classes can have zero or more
216 subclasses to which traffic may be enqueued.
218 Furthermore, each class contains a
222 behaviour, although another qdisc can be attached in place. This qdisc may again
223 contain classes, but each class can have only one leaf qdisc.
225 When a packet enters a classful qdisc it can be
227 to one of the classes within. Three criteria are available, although not all
228 qdiscs will use all three:
231 If tc filters are attached to a class, they are consulted first
232 for relevant instructions. Filters can match on all fields of a packet header,
233 as well as on the firewall mark applied by ipchains or iptables.
236 Some qdiscs have built in rules for classifying packets based on the TOS field.
239 Userspace programs can encode a class-id in the 'skb->priority' field using
240 the SO_PRIORITY option.
242 Each node within the tree can have its own filters but higher level filters
243 may also point directly to lower classes.
245 If classification did not succeed, packets are enqueued to the leaf qdisc
246 attached to that class. Check qdisc specific manpages for details, however.
249 All qdiscs, classes and filters have IDs, which can either be specified
250 or be automatically assigned.
252 IDs consist of a major number and a minor number, separated by a colon.
253 Both major and minor number are limited to 16 bits. There are two special
254 values: root is signified by major and minor of all ones, and unspecified
259 A qdisc, which potentially can have children,
260 gets assigned a major number, called a 'handle', leaving the minor
261 number namespace available for classes. The handle is expressed as '10:'.
262 It is customary to explicitly assign a handle to qdiscs expected to have
267 Classes residing under a qdisc share their qdisc major number, but each have
268 a separate minor number called a 'classid' that has no relation to their
269 parent classes, only to their parent qdisc. The same naming custom as for
274 Filters have a three part ID, which is only needed when using a hashed
278 The following parameters are widely used in TC. For other parameters,
279 see the man pages for individual qdiscs.
284 These parameters accept a floating point number, possibly followed by
285 a unit (both SI and IEC units supported).
319 To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with
320 IEC prefix (ki-, mi-, gi- and ti-) respectively.
323 TC store rates as a 32-bit unsigned integer in bps internally,
324 so we can specify a max rate of 4294967295 bps.
329 Length of time. Can be specified as a floating point number
330 followed by an optional unit:
339 us, usec, usecs or a bare number
343 TC defined its own time unit (equal to microsecond) and stores
344 time values as 32-bit unsigned integer, thus we can specify a max time value
350 Amounts of data. Can be specified as a floating point number
351 followed by an optional unit:
376 TC stores sizes internally as 32-bit unsigned integer in byte,
377 so we can specify a max size of 4294967295 bytes.
382 Other values without a unit.
383 These parameters are interpreted as decimal by default, but you can
384 indicate TC to interpret them as octal and hexadecimal by adding a '0'
385 or '0x' prefix respectively.
388 The following commands are available for qdiscs, classes and filter:
391 Add a qdisc, class or filter to a node. For all entities, a
393 must be passed, either by passing its ID or by attaching directly to the root of a device.
394 When creating a qdisc or a filter, it can be named with the
396 parameter. A class is named with the
402 A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
403 are automatically deleted, as well as any filters attached to them.
407 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
408 that the handle cannot be changed and neither can the parent. In other words,
415 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
420 Only available for qdiscs and performs a replace where the node
426 .BR "\-b", " \-b filename", " \-batch", " \-batch filename"
427 read commands from provided file or standard input and invoke them.
428 First failure will cause termination of tc.
432 don't terminate tc on errors in batch mode.
433 If there were any errors during execution of the commands, the application return code will be non zero.
436 .BR "\-n" , " \-net" , " \-netns " <NETNS>
439 to the specified network namespace
441 Actually it just simplifies executing of:
446 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
452 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
456 The show command has additional formatting options:
459 .BR "\-s" , " \-stats", " \-statistics"
460 output more statistics about packet usage.
463 .BR "\-d", " \-details"
464 output more detailed information about rates and cell sizes.
468 output raw hex values for handles.
471 .BR "\-p", " \-pretty"
472 decode filter offset and mask values to equivalent filter commands based on TCP/IP.
476 print rates in IEC units (ie. 1K = 1024).
480 was written by Alexey N. Kuznetsov and added in Linux 2.2.
494 .BR tc-pfifo_fast (8),
501 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
504 Manpage maintained by bert hubert (ahu@ds9a.nl)