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] |
74 \fB\-g\fR[\fIraph\fR] }
78 is used to configure Traffic Control in the Linux kernel. Traffic Control consists
83 When traffic is shaped, its rate of transmission is under control. Shaping may
84 be more than lowering the available bandwidth - it is also used to smooth out
85 bursts in traffic for better network behaviour. Shaping occurs on egress.
89 By scheduling the transmission of packets it is possible to improve interactivity
90 for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering
91 is also called prioritizing, and happens only on egress.
95 Whereas shaping deals with transmission of traffic, policing pertains to traffic
96 arriving. Policing thus occurs on ingress.
100 Traffic exceeding a set bandwidth may also be dropped forthwith, both on
101 ingress and on egress.
104 Processing of traffic is controlled by three kinds of objects: qdiscs,
109 is short for 'queueing discipline' and it is elementary to
110 understanding traffic control. Whenever the kernel needs to send a
111 packet to an interface, it is
113 to the qdisc configured for that interface. Immediately afterwards, the kernel
114 tries to get as many packets as possible from the qdisc, for giving them
115 to the network adaptor driver.
117 A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure
118 First In, First Out queue. It does however store traffic when the network interface
119 can't handle it momentarily.
122 Some qdiscs can contain classes, which contain further qdiscs - traffic may
123 then be enqueued in any of the inner qdiscs, which are within the
125 When the kernel tries to dequeue a packet from such a
127 it can come from any of the classes. A qdisc may for example prioritize
128 certain kinds of traffic by trying to dequeue from certain classes
134 is used by a classful qdisc to determine in which class a packet will
135 be enqueued. Whenever traffic arrives at a class with subclasses, it needs
136 to be classified. Various methods may be employed to do so, one of these
137 are the filters. All filters attached to the class are called, until one of
138 them returns with a verdict. If no verdict was made, other criteria may be
139 available. This differs per qdisc.
141 It is important to notice that filters reside
143 qdiscs - they are not masters of what happens.
146 The classless qdiscs are:
149 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
153 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
154 queue which honors Type of Service flags, as well as the priority that may be
155 assigned to a packet.
158 Random Early Detection simulates physical congestion by randomly dropping
159 packets when nearing configured bandwidth allocation. Well suited to very
160 large bandwidth applications.
163 Stochastic Fairness Queueing reorders queued traffic so each 'session'
164 gets to send a packet in turn.
167 The Token Bucket Filter is suited for slowing traffic down to a precisely
168 configured rate. Scales well to large bandwidths.
169 .SH CONFIGURING CLASSLESS QDISCS
170 In the absence of classful qdiscs, classless qdiscs can only be attached at
171 the root of a device. Full syntax:
176 QDISC QDISC-PARAMETERS
186 qdisc is the automatic default in the absence of a configured qdisc.
189 The classful qdiscs are:
192 Class Based Queueing implements a rich linksharing hierarchy of classes.
193 It contains shaping elements as well as prioritizing capabilities. Shaping is
194 performed using link idle time calculations based on average packet size and
195 underlying link bandwidth. The latter may be ill-defined for some interfaces.
198 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
199 classes with an emphasis on conforming to existing practices. HTB facilitates
200 guaranteeing bandwidth to classes, while also allowing specification of upper
201 limits to inter-class sharing. It contains shaping elements, based on TBF and
202 can prioritize classes.
205 The PRIO qdisc is a non-shaping container for a configurable number of
206 classes which are dequeued in order. This allows for easy prioritization
207 of traffic, where lower classes are only able to send if higher ones have
208 no packets available. To facilitate configuration, Type Of Service bits are
210 .SH THEORY OF OPERATION
211 Classes form a tree, where each class has a single parent.
212 A class may have multiple children. Some qdiscs allow for runtime addition
213 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
216 Qdiscs which allow dynamic addition of classes can have zero or more
217 subclasses to which traffic may be enqueued.
219 Furthermore, each class contains a
223 behaviour, although another qdisc can be attached in place. This qdisc may again
224 contain classes, but each class can have only one leaf qdisc.
226 When a packet enters a classful qdisc it can be
228 to one of the classes within. Three criteria are available, although not all
229 qdiscs will use all three:
232 If tc filters are attached to a class, they are consulted first
233 for relevant instructions. Filters can match on all fields of a packet header,
234 as well as on the firewall mark applied by ipchains or iptables.
237 Some qdiscs have built in rules for classifying packets based on the TOS field.
240 Userspace programs can encode a class-id in the 'skb->priority' field using
241 the SO_PRIORITY option.
243 Each node within the tree can have its own filters but higher level filters
244 may also point directly to lower classes.
246 If classification did not succeed, packets are enqueued to the leaf qdisc
247 attached to that class. Check qdisc specific manpages for details, however.
250 All qdiscs, classes and filters have IDs, which can either be specified
251 or be automatically assigned.
253 IDs consist of a major number and a minor number, separated by a colon.
254 Both major and minor number are limited to 16 bits. There are two special
255 values: root is signified by major and minor of all ones, and unspecified
260 A qdisc, which potentially can have children,
261 gets assigned a major number, called a 'handle', leaving the minor
262 number namespace available for classes. The handle is expressed as '10:'.
263 It is customary to explicitly assign a handle to qdiscs expected to have
268 Classes residing under a qdisc share their qdisc major number, but each have
269 a separate minor number called a 'classid' that has no relation to their
270 parent classes, only to their parent qdisc. The same naming custom as for
275 Filters have a three part ID, which is only needed when using a hashed
279 The following parameters are widely used in TC. For other parameters,
280 see the man pages for individual qdiscs.
285 These parameters accept a floating point number, possibly followed by
286 a unit (both SI and IEC units supported).
320 To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with
321 IEC prefix (ki-, mi-, gi- and ti-) respectively.
324 TC store rates as a 32-bit unsigned integer in bps internally,
325 so we can specify a max rate of 4294967295 bps.
330 Length of time. Can be specified as a floating point number
331 followed by an optional unit:
340 us, usec, usecs or a bare number
344 TC defined its own time unit (equal to microsecond) and stores
345 time values as 32-bit unsigned integer, thus we can specify a max time value
351 Amounts of data. Can be specified as a floating point number
352 followed by an optional unit:
377 TC stores sizes internally as 32-bit unsigned integer in byte,
378 so we can specify a max size of 4294967295 bytes.
383 Other values without a unit.
384 These parameters are interpreted as decimal by default, but you can
385 indicate TC to interpret them as octal and hexadecimal by adding a '0'
386 or '0x' prefix respectively.
389 The following commands are available for qdiscs, classes and filter:
392 Add a qdisc, class or filter to a node. For all entities, a
394 must be passed, either by passing its ID or by attaching directly to the root of a device.
395 When creating a qdisc or a filter, it can be named with the
397 parameter. A class is named with the
403 A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
404 are automatically deleted, as well as any filters attached to them.
408 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
409 that the handle cannot be changed and neither can the parent. In other words,
416 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
421 Only available for qdiscs and performs a replace where the node
427 .BR "\-b", " \-b filename", " \-batch", " \-batch filename"
428 read commands from provided file or standard input and invoke them.
429 First failure will cause termination of tc.
433 don't terminate tc on errors in batch mode.
434 If there were any errors during execution of the commands, the application return code will be non zero.
437 .BR "\-n" , " \-net" , " \-netns " <NETNS>
440 to the specified network namespace
442 Actually it just simplifies executing of:
447 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
453 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
457 The show command has additional formatting options:
460 .BR "\-s" , " \-stats", " \-statistics"
461 output more statistics about packet usage.
464 .BR "\-d", " \-details"
465 output more detailed information about rates and cell sizes.
469 output raw hex values for handles.
472 .BR "\-p", " \-pretty"
473 decode filter offset and mask values to equivalent filter commands based on TCP/IP.
477 print rates in IEC units (ie. 1K = 1024).
480 .BR "\-g", " \-graph"
481 shows classes as ASCII graph. Prints generic stats info under each class if
483 option was specified. Classes can be filtered only by
489 tc -g class show dev eth0
491 Shows classes as ASCII graph on eth0 interface.
494 tc -g -s class show dev eth0
496 Shows classes as ASCII graph with stats info under each class.
500 was written by Alexey N. Kuznetsov and added in Linux 2.2.
514 .BR tc-pfifo_fast (8),
521 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
524 Manpage maintained by bert hubert (ahu@ds9a.nl)