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.
147 The available filters are:
150 Filter packets based on an ematch expression. See
155 Filter packets using (e)BPF, see
160 Filter packets based on the control group of their process. See
165 Flow-based classifiers, filtering packets based on their flow (identified by selectable keys). See
166 .BR tc-flow "(8) and"
171 Filter based on fwmark. Directly maps fwmark value to traffic class. See
175 Filter packets based on routing table. See
180 Match Resource Reservation Protocol (RSVP) packets.
183 Filter packets based on traffic control index. See
187 Generic filtering on arbitrary packet data, assisted by syntax to abstract common operations. See
192 Traffic control filter that matches every packet. See
197 The classless qdiscs are:
200 CHOKe (CHOose and Keep for responsive flows, CHOose and Kill for unresponsive
201 flows) is a classless qdisc designed to both identify and penalize flows that
202 monopolize the queue. CHOKe is a variation of RED, and the configuration is
206 CoDel (pronounced "coddle") is an adaptive "no-knobs" active queue management
207 algorithm (AQM) scheme that was developed to address the shortcomings of
208 RED and its variants.
211 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
215 Fair Queue Scheduler realises TCP pacing and scales to millions of concurrent
219 Fair Queuing Controlled Delay is queuing discipline that combines Fair
220 Queuing with the CoDel AQM scheme. FQ_Codel uses a stochastic model to classify
221 incoming packets into different flows and is used to provide a fair share of the
222 bandwidth to all the flows using the queue. Each such flow is managed by the
223 CoDel queuing discipline. Reordering within a flow is avoided since Codel
224 internally uses a FIFO queue.
227 Generalized Random Early Detection combines multiple RED queues in order to
228 achieve multiple drop priorities. This is required to realize Assured
229 Forwarding (RFC 2597).
232 Heavy-Hitter Filter differentiates between small flows and the opposite,
233 heavy-hitters. The goal is to catch the heavy-hitters and move them to a
234 separate queue with less priority so that bulk traffic does not affect the
235 latency of critical traffic.
238 This is a special qdisc as it applies to incoming traffic on an interface, allowing for it to be filtered and policed.
241 The Multiqueue Priority Qdisc is a simple queuing discipline that allows
242 mapping traffic flows to hardware queue ranges using priorities and a
243 configurable priority to traffic class mapping. A traffic class in this context
244 is a set of contiguous qdisc classes which map 1:1 to a set of hardware exposed
248 Multiqueue is a qdisc optimized for devices with multiple Tx queues. It has
249 been added for hardware that wishes to avoid head-of-line blocking. It will
250 cycle though the bands and verify that the hardware queue associated with the
251 band is not stopped prior to dequeuing a packet.
254 Network Emulator is an enhancement of the Linux traffic control facilities that
255 allow to add delay, packet loss, duplication and more other characteristics to
256 packets outgoing from a selected network interface.
259 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
260 queue which honors Type of Service flags, as well as the priority that may be
261 assigned to a packet.
264 Proportional Integral controller-Enhanced (PIE) is a control theoretic active
265 queue management scheme. It is based on the proportional integral controller but
266 aims to control delay.
269 Random Early Detection simulates physical congestion by randomly dropping
270 packets when nearing configured bandwidth allocation. Well suited to very
271 large bandwidth applications.
274 Round-Robin qdisc with support for multiqueue network devices. Removed from
275 Linux since kernel version 2.6.27.
278 Stochastic Fair Blue is a classless qdisc to manage congestion based on
279 packet loss and link utilization history while trying to prevent
280 non-responsive flows (i.e. flows that do not react to congestion marking
281 or dropped packets) from impacting performance of responsive flows.
282 Unlike RED, where the marking probability has to be configured, BLUE
283 tries to determine the ideal marking probability automatically.
286 Stochastic Fairness Queueing reorders queued traffic so each 'session'
287 gets to send a packet in turn.
290 The Token Bucket Filter is suited for slowing traffic down to a precisely
291 configured rate. Scales well to large bandwidths.
292 .SH CONFIGURING CLASSLESS QDISCS
293 In the absence of classful qdiscs, classless qdiscs can only be attached at
294 the root of a device. Full syntax:
299 QDISC QDISC-PARAMETERS
309 qdisc is the automatic default in the absence of a configured qdisc.
312 The classful qdiscs are:
315 Map flows to virtual circuits of an underlying asynchronous transfer mode
319 Class Based Queueing implements a rich linksharing hierarchy of classes.
320 It contains shaping elements as well as prioritizing capabilities. Shaping is
321 performed using link idle time calculations based on average packet size and
322 underlying link bandwidth. The latter may be ill-defined for some interfaces.
325 The Deficit Round Robin Scheduler is a more flexible replacement for Stochastic
326 Fairness Queuing. Unlike SFQ, there are no built-in queues \-\- you need to add
327 classes and then set up filters to classify packets accordingly. This can be
328 useful e.g. for using RED qdiscs with different settings for particular
329 traffic. There is no default class \-\- if a packet cannot be classified, it is
333 Classify packets based on TOS field, change TOS field of packets based on
337 Hierarchical Fair Service Curve guarantees precise bandwidth and delay allocation for leaf classes and allocates excess bandwidth fairly. Unlike HTB, it makes use of packet dropping to achieve low delays which interactive sessions benefit from.
340 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
341 classes with an emphasis on conforming to existing practices. HTB facilitates
342 guaranteeing bandwidth to classes, while also allowing specification of upper
343 limits to inter-class sharing. It contains shaping elements, based on TBF and
344 can prioritize classes.
347 The PRIO qdisc is a non-shaping container for a configurable number of
348 classes which are dequeued in order. This allows for easy prioritization
349 of traffic, where lower classes are only able to send if higher ones have
350 no packets available. To facilitate configuration, Type Of Service bits are
354 Quick Fair Queueing is an O(1) scheduler that provides near-optimal guarantees,
355 and is the first to achieve that goal with a constant cost also with respect to
356 the number of groups and the packet length. The QFQ algorithm has no loops, and
357 uses very simple instructions and data structures that lend themselves very
358 well to a hardware implementation.
359 .SH THEORY OF OPERATION
360 Classes form a tree, where each class has a single parent.
361 A class may have multiple children. Some qdiscs allow for runtime addition
362 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
365 Qdiscs which allow dynamic addition of classes can have zero or more
366 subclasses to which traffic may be enqueued.
368 Furthermore, each class contains a
372 behaviour, although another qdisc can be attached in place. This qdisc may again
373 contain classes, but each class can have only one leaf qdisc.
375 When a packet enters a classful qdisc it can be
377 to one of the classes within. Three criteria are available, although not all
378 qdiscs will use all three:
381 If tc filters are attached to a class, they are consulted first
382 for relevant instructions. Filters can match on all fields of a packet header,
383 as well as on the firewall mark applied by ipchains or iptables.
386 Some qdiscs have built in rules for classifying packets based on the TOS field.
389 Userspace programs can encode a class-id in the 'skb->priority' field using
390 the SO_PRIORITY option.
392 Each node within the tree can have its own filters but higher level filters
393 may also point directly to lower classes.
395 If classification did not succeed, packets are enqueued to the leaf qdisc
396 attached to that class. Check qdisc specific manpages for details, however.
399 All qdiscs, classes and filters have IDs, which can either be specified
400 or be automatically assigned.
403 .BR major " number and a " minor
404 number, separated by a colon -
405 .BR major ":" minor "."
407 .BR major " and " minor
408 are hexadecimal numbers and are limited to 16 bits. There are two special
409 values: root is signified by
410 .BR major " and " minor
411 of all ones, and unspecified is all zeros.
415 A qdisc, which potentially can have children, gets assigned a
417 number, called a 'handle', leaving the
419 number namespace available for classes. The handle is expressed as '10:'.
420 It is customary to explicitly assign a handle to qdiscs expected to have children.
424 Classes residing under a qdisc share their qdisc
426 number, but each have a separate
428 number called a 'classid' that has no relation to their
429 parent classes, only to their parent qdisc. The same naming custom as for
434 Filters have a three part ID, which is only needed when using a hashed
438 The following parameters are widely used in TC. For other parameters,
439 see the man pages for individual qdiscs.
444 These parameters accept a floating point number, possibly followed by
445 a unit (both SI and IEC units supported).
479 To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with
480 IEC prefix (ki-, mi-, gi- and ti-) respectively.
483 TC store rates as a 32-bit unsigned integer in bps internally,
484 so we can specify a max rate of 4294967295 bps.
489 Length of time. Can be specified as a floating point number
490 followed by an optional unit:
499 us, usec, usecs or a bare number
503 TC defined its own time unit (equal to microsecond) and stores
504 time values as 32-bit unsigned integer, thus we can specify a max time value
510 Amounts of data. Can be specified as a floating point number
511 followed by an optional unit:
536 TC stores sizes internally as 32-bit unsigned integer in byte,
537 so we can specify a max size of 4294967295 bytes.
542 Other values without a unit.
543 These parameters are interpreted as decimal by default, but you can
544 indicate TC to interpret them as octal and hexadecimal by adding a '0'
545 or '0x' prefix respectively.
548 The following commands are available for qdiscs, classes and filter:
551 Add a qdisc, class or filter to a node. For all entities, a
553 must be passed, either by passing its ID or by attaching directly to the root of a device.
554 When creating a qdisc or a filter, it can be named with the
556 parameter. A class is named with the
562 A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
563 are automatically deleted, as well as any filters attached to them.
567 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
568 that the handle cannot be changed and neither can the parent. In other words,
575 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
580 Only available for qdiscs and performs a replace where the node
586 .BR "\-b", " \-b filename", " \-batch", " \-batch filename"
587 read commands from provided file or standard input and invoke them.
588 First failure will cause termination of tc.
592 don't terminate tc on errors in batch mode.
593 If there were any errors during execution of the commands, the application return code will be non zero.
596 .BR "\-n" , " \-net" , " \-netns " <NETNS>
599 to the specified network namespace
601 Actually it just simplifies executing of:
606 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
612 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
616 .BR "\-cf" , " \-conf " <FILENAME>
617 specifies path to the config file. This option is used in conjunction with other options (e.g.
621 The show command has additional formatting options:
624 .BR "\-s" , " \-stats", " \-statistics"
625 output more statistics about packet usage.
628 .BR "\-d", " \-details"
629 output more detailed information about rates and cell sizes.
633 output raw hex values for handles.
636 .BR "\-p", " \-pretty"
637 decode filter offset and mask values to equivalent filter commands based on TCP/IP.
641 print rates in IEC units (ie. 1K = 1024).
644 .BR "\-g", " \-graph"
645 shows classes as ASCII graph. Prints generic stats info under each class if
647 option was specified. Classes can be filtered only by
652 .BR "\-nm" , " \-name"
653 resolve class name from
654 .B /etc/iproute2/tc_cls
655 file or from file specified by
657 option. This file is just a mapping of
665 1:40 voip # Here is another comment
681 was specified without
684 .B /etc/iproute2/tc_cls
685 file does not exist, which makes it possible to pass
694 tc -g class show dev eth0
696 Shows classes as ASCII graph on eth0 interface.
699 tc -g -s class show dev eth0
701 Shows classes as ASCII graph with stats info under each class.
705 was written by Alexey N. Kuznetsov and added in Linux 2.2.
726 .BR tc-pfifo_fast (8),
736 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
739 Manpage maintained by bert hubert (ahu@ds9a.nl)
projects / mirror_iproute2.git / blob