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|
66 \fB[ \fB-nm \fR| \fB-nam\fR[\fIes\fR] \fB] \fR|
67 \fB[ \fR{ \fB-cf \fR| \fB-c\fR[\fIonf\fR] \fR} \fB[ filename ] \fB] \fR}
71 \fB\-s\fR[\fItatistics\fR] |
72 \fB\-d\fR[\fIetails\fR] |
74 \fB\-p\fR[\fIretty\fR] |
76 \fB\-g\fR[\fIraph\fR] }
80 is used to configure Traffic Control in the Linux kernel. Traffic Control consists
85 When traffic is shaped, its rate of transmission is under control. Shaping may
86 be more than lowering the available bandwidth - it is also used to smooth out
87 bursts in traffic for better network behaviour. Shaping occurs on egress.
91 By scheduling the transmission of packets it is possible to improve interactivity
92 for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering
93 is also called prioritizing, and happens only on egress.
97 Whereas shaping deals with transmission of traffic, policing pertains to traffic
98 arriving. Policing thus occurs on ingress.
102 Traffic exceeding a set bandwidth may also be dropped forthwith, both on
103 ingress and on egress.
106 Processing of traffic is controlled by three kinds of objects: qdiscs,
111 is short for 'queueing discipline' and it is elementary to
112 understanding traffic control. Whenever the kernel needs to send a
113 packet to an interface, it is
115 to the qdisc configured for that interface. Immediately afterwards, the kernel
116 tries to get as many packets as possible from the qdisc, for giving them
117 to the network adaptor driver.
119 A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure
120 First In, First Out queue. It does however store traffic when the network interface
121 can't handle it momentarily.
124 Some qdiscs can contain classes, which contain further qdiscs - traffic may
125 then be enqueued in any of the inner qdiscs, which are within the
127 When the kernel tries to dequeue a packet from such a
129 it can come from any of the classes. A qdisc may for example prioritize
130 certain kinds of traffic by trying to dequeue from certain classes
136 is used by a classful qdisc to determine in which class a packet will
137 be enqueued. Whenever traffic arrives at a class with subclasses, it needs
138 to be classified. Various methods may be employed to do so, one of these
139 are the filters. All filters attached to the class are called, until one of
140 them returns with a verdict. If no verdict was made, other criteria may be
141 available. This differs per qdisc.
143 It is important to notice that filters reside
145 qdiscs - they are not masters of what happens.
148 The classless qdiscs are:
151 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
155 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
156 queue which honors Type of Service flags, as well as the priority that may be
157 assigned to a packet.
160 Random Early Detection simulates physical congestion by randomly dropping
161 packets when nearing configured bandwidth allocation. Well suited to very
162 large bandwidth applications.
165 Stochastic Fairness Queueing reorders queued traffic so each 'session'
166 gets to send a packet in turn.
169 The Token Bucket Filter is suited for slowing traffic down to a precisely
170 configured rate. Scales well to large bandwidths.
171 .SH CONFIGURING CLASSLESS QDISCS
172 In the absence of classful qdiscs, classless qdiscs can only be attached at
173 the root of a device. Full syntax:
178 QDISC QDISC-PARAMETERS
188 qdisc is the automatic default in the absence of a configured qdisc.
191 The classful qdiscs are:
194 Class Based Queueing implements a rich linksharing hierarchy of classes.
195 It contains shaping elements as well as prioritizing capabilities. Shaping is
196 performed using link idle time calculations based on average packet size and
197 underlying link bandwidth. The latter may be ill-defined for some interfaces.
200 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
201 classes with an emphasis on conforming to existing practices. HTB facilitates
202 guaranteeing bandwidth to classes, while also allowing specification of upper
203 limits to inter-class sharing. It contains shaping elements, based on TBF and
204 can prioritize classes.
207 The PRIO qdisc is a non-shaping container for a configurable number of
208 classes which are dequeued in order. This allows for easy prioritization
209 of traffic, where lower classes are only able to send if higher ones have
210 no packets available. To facilitate configuration, Type Of Service bits are
212 .SH THEORY OF OPERATION
213 Classes form a tree, where each class has a single parent.
214 A class may have multiple children. Some qdiscs allow for runtime addition
215 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
218 Qdiscs which allow dynamic addition of classes can have zero or more
219 subclasses to which traffic may be enqueued.
221 Furthermore, each class contains a
225 behaviour, although another qdisc can be attached in place. This qdisc may again
226 contain classes, but each class can have only one leaf qdisc.
228 When a packet enters a classful qdisc it can be
230 to one of the classes within. Three criteria are available, although not all
231 qdiscs will use all three:
234 If tc filters are attached to a class, they are consulted first
235 for relevant instructions. Filters can match on all fields of a packet header,
236 as well as on the firewall mark applied by ipchains or iptables.
239 Some qdiscs have built in rules for classifying packets based on the TOS field.
242 Userspace programs can encode a class-id in the 'skb->priority' field using
243 the SO_PRIORITY option.
245 Each node within the tree can have its own filters but higher level filters
246 may also point directly to lower classes.
248 If classification did not succeed, packets are enqueued to the leaf qdisc
249 attached to that class. Check qdisc specific manpages for details, however.
252 All qdiscs, classes and filters have IDs, which can either be specified
253 or be automatically assigned.
256 .BR major " number and a " minor
257 number, separated by a colon -
258 .BR major ":" minor "."
260 .BR major " and " minor
261 are hexadecimal numbers and are limited to 16 bits. There are two special
262 values: root is signified by
263 .BR major " and " minor
264 of all ones, and unspecified is all zeros.
268 A qdisc, which potentially can have children, gets assigned a
270 number, called a 'handle', leaving the
272 number namespace available for classes. The handle is expressed as '10:'.
273 It is customary to explicitly assign a handle to qdiscs expected to have children.
277 Classes residing under a qdisc share their qdisc
279 number, but each have a separate
281 number called a 'classid' that has no relation to their
282 parent classes, only to their parent qdisc. The same naming custom as for
287 Filters have a three part ID, which is only needed when using a hashed
291 The following parameters are widely used in TC. For other parameters,
292 see the man pages for individual qdiscs.
297 These parameters accept a floating point number, possibly followed by
298 a unit (both SI and IEC units supported).
332 To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with
333 IEC prefix (ki-, mi-, gi- and ti-) respectively.
336 TC store rates as a 32-bit unsigned integer in bps internally,
337 so we can specify a max rate of 4294967295 bps.
342 Length of time. Can be specified as a floating point number
343 followed by an optional unit:
352 us, usec, usecs or a bare number
356 TC defined its own time unit (equal to microsecond) and stores
357 time values as 32-bit unsigned integer, thus we can specify a max time value
363 Amounts of data. Can be specified as a floating point number
364 followed by an optional unit:
389 TC stores sizes internally as 32-bit unsigned integer in byte,
390 so we can specify a max size of 4294967295 bytes.
395 Other values without a unit.
396 These parameters are interpreted as decimal by default, but you can
397 indicate TC to interpret them as octal and hexadecimal by adding a '0'
398 or '0x' prefix respectively.
401 The following commands are available for qdiscs, classes and filter:
404 Add a qdisc, class or filter to a node. For all entities, a
406 must be passed, either by passing its ID or by attaching directly to the root of a device.
407 When creating a qdisc or a filter, it can be named with the
409 parameter. A class is named with the
415 A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
416 are automatically deleted, as well as any filters attached to them.
420 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
421 that the handle cannot be changed and neither can the parent. In other words,
428 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
433 Only available for qdiscs and performs a replace where the node
439 .BR "\-b", " \-b filename", " \-batch", " \-batch filename"
440 read commands from provided file or standard input and invoke them.
441 First failure will cause termination of tc.
445 don't terminate tc on errors in batch mode.
446 If there were any errors during execution of the commands, the application return code will be non zero.
449 .BR "\-n" , " \-net" , " \-netns " <NETNS>
452 to the specified network namespace
454 Actually it just simplifies executing of:
459 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
465 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
469 .BR "\-cf" , " \-conf " <FILENAME>
470 specifies path to the config file. This option is used in conjuction with other options (e.g.
474 The show command has additional formatting options:
477 .BR "\-s" , " \-stats", " \-statistics"
478 output more statistics about packet usage.
481 .BR "\-d", " \-details"
482 output more detailed information about rates and cell sizes.
486 output raw hex values for handles.
489 .BR "\-p", " \-pretty"
490 decode filter offset and mask values to equivalent filter commands based on TCP/IP.
494 print rates in IEC units (ie. 1K = 1024).
497 .BR "\-g", " \-graph"
498 shows classes as ASCII graph. Prints generic stats info under each class if
500 option was specified. Classes can be filtered only by
505 .BR "\-nm" , " \-name"
506 resolve class name from
507 .B /etc/iproute2/tc_cls
508 file or from file specified by
510 option. This file is just a mapping of
518 1:40 voip # Here is another comment
534 was specified without
537 .B /etc/iproute2/tc_cls
538 file does not exist, which makes it possible to pass
547 tc -g class show dev eth0
549 Shows classes as ASCII graph on eth0 interface.
552 tc -g -s class show dev eth0
554 Shows classes as ASCII graph with stats info under each class.
558 was written by Alexey N. Kuznetsov and added in Linux 2.2.
572 .BR tc-pfifo_fast (8),
579 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
582 Manpage maintained by bert hubert (ahu@ds9a.nl)