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
18 \fIBLOCK_INDEX\fR ] qdisc
19 [ qdisc specific parameters ]
24 .B class [ add | change | replace | delete ] dev
29 \fIclass-id\fR ] qdisc
30 [ qdisc specific parameters ]
35 .B filter [ add | change | replace | delete | get ] dev
39 .B | root ] [ handle \fIfilter-id\fR ]
43 \fIpriority\fR filtertype
44 [ filtertype specific parameters ]
50 .B filter [ add | change | replace | delete | get ] block
52 .B [ handle \fIfilter-id\fR ]
56 \fIpriority\fR filtertype
57 [ filtertype specific parameters ]
63 .B chain [ add | delete | get ] dev
67 .B | root ]\fR filtertype
68 [ filtertype specific parameters ]
72 .B chain [ add | delete | get ] block
73 \fIBLOCK_INDEX\fR filtertype
74 [ filtertype specific parameters ]
80 .B qdisc { show | list } [ dev
82 .B ] [ root | ingress | handle
100 .RI "[ " OPTIONS " ]"
105 .RI "[ " OPTIONS " ]"
110 .RI "[ " OPTIONS " ]"
116 .RI "[ " OPTIONS " ]"
124 \fB[ -force ] -b\fR[\fIatch\fR] \fB[ filename ] \fR|
125 \fB[ \fB-n\fR[\fIetns\fR] name \fB] \fR|
126 \fB[ \fB-N\fR[\fIumeric\fR] \fB] \fR|
127 \fB[ \fB-nm \fR| \fB-nam\fR[\fIes\fR] \fB] \fR|
128 \fB[ \fR{ \fB-cf \fR| \fB-c\fR[\fIonf\fR] \fR} \fB[ filename ] \fB] \fR
129 \fB[ -t\fR[imestamp\fR] \fB\] \fR| \fB[ -t\fR[short\fR] \fR| \fB[
130 -o\fR[neline\fR] \fB]\fR }
134 \fB\-s\fR[\fItatistics\fR] |
135 \fB\-d\fR[\fIetails\fR] |
136 \fB\-r\fR[\fIaw\fR] |
137 \fB\-i\fR[\fIec\fR] |
138 \fB\-g\fR[\fIraph\fR] |
139 \fB\-j\fR[\fIjson\fR] |
140 \fB\-p\fR[\fIretty\fR] |
141 \fB\-col\fR[\fIor\fR] }
145 is used to configure Traffic Control in the Linux kernel. Traffic Control consists
150 When traffic is shaped, its rate of transmission is under control. Shaping may
151 be more than lowering the available bandwidth - it is also used to smooth out
152 bursts in traffic for better network behaviour. Shaping occurs on egress.
156 By scheduling the transmission of packets it is possible to improve interactivity
157 for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering
158 is also called prioritizing, and happens only on egress.
162 Whereas shaping deals with transmission of traffic, policing pertains to traffic
163 arriving. Policing thus occurs on ingress.
167 Traffic exceeding a set bandwidth may also be dropped forthwith, both on
168 ingress and on egress.
171 Processing of traffic is controlled by three kinds of objects: qdiscs,
176 is short for 'queueing discipline' and it is elementary to
177 understanding traffic control. Whenever the kernel needs to send a
178 packet to an interface, it is
180 to the qdisc configured for that interface. Immediately afterwards, the kernel
181 tries to get as many packets as possible from the qdisc, for giving them
182 to the network adaptor driver.
184 A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure
185 First In, First Out queue. It does however store traffic when the network interface
186 can't handle it momentarily.
189 Some qdiscs can contain classes, which contain further qdiscs - traffic may
190 then be enqueued in any of the inner qdiscs, which are within the
192 When the kernel tries to dequeue a packet from such a
194 it can come from any of the classes. A qdisc may for example prioritize
195 certain kinds of traffic by trying to dequeue from certain classes
201 is used by a classful qdisc to determine in which class a packet will
202 be enqueued. Whenever traffic arrives at a class with subclasses, it needs
203 to be classified. Various methods may be employed to do so, one of these
204 are the filters. All filters attached to the class are called, until one of
205 them returns with a verdict. If no verdict was made, other criteria may be
206 available. This differs per qdisc.
208 It is important to notice that filters reside
210 qdiscs - they are not masters of what happens.
212 The available filters are:
215 Filter packets based on an ematch expression. See
220 Filter packets using (e)BPF, see
225 Filter packets based on the control group of their process. See
230 Flow-based classifiers, filtering packets based on their flow (identified by selectable keys). See
231 .BR tc-flow "(8) and"
236 Filter based on fwmark. Directly maps fwmark value to traffic class. See
240 Filter packets based on routing table. See
245 Match Resource Reservation Protocol (RSVP) packets.
248 Filter packets based on traffic control index. See
252 Generic filtering on arbitrary packet data, assisted by syntax to abstract common operations. See
257 Traffic control filter that matches every packet. See
262 Qdiscs may invoke user-configured actions when certain interesting events
263 take place in the qdisc. Each qevent can either be unused, or can have a
264 block attached to it. To this block are then attached filters using the "tc
265 block BLOCK_IDX" syntax. The block is executed when the qevent associated
266 with the attachment point takes place. For example, packet could be
267 dropped, or delayed, etc., depending on the qdisc and the qevent in
273 tc qdisc add dev eth0 root handle 1: red limit 500K avpkt 1K \\
274 qevent early_drop block 10
277 tc filter add block 10 matchall action mirred egress mirror dev eth1
281 The classless qdiscs are:
284 CHOKe (CHOose and Keep for responsive flows, CHOose and Kill for unresponsive
285 flows) is a classless qdisc designed to both identify and penalize flows that
286 monopolize the queue. CHOKe is a variation of RED, and the configuration is
290 CoDel (pronounced "coddle") is an adaptive "no-knobs" active queue management
291 algorithm (AQM) scheme that was developed to address the shortcomings of
292 RED and its variants.
295 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
299 Fair Queue Scheduler realises TCP pacing and scales to millions of concurrent
303 Fair Queuing Controlled Delay is queuing discipline that combines Fair
304 Queuing with the CoDel AQM scheme. FQ_Codel uses a stochastic model to classify
305 incoming packets into different flows and is used to provide a fair share of the
306 bandwidth to all the flows using the queue. Each such flow is managed by the
307 CoDel queuing discipline. Reordering within a flow is avoided since Codel
308 internally uses a FIFO queue.
311 FQ-PIE (Flow Queuing with Proportional Integral controller Enhanced) is a
312 queuing discipline that combines Flow Queuing with the PIE AQM scheme. FQ-PIE
313 uses a Jenkins hash function to classify incoming packets into different flows
314 and is used to provide a fair share of the bandwidth to all the flows using the
315 qdisc. Each such flow is managed by the PIE algorithm.
318 Generalized Random Early Detection combines multiple RED queues in order to
319 achieve multiple drop priorities. This is required to realize Assured
320 Forwarding (RFC 2597).
323 Heavy-Hitter Filter differentiates between small flows and the opposite,
324 heavy-hitters. The goal is to catch the heavy-hitters and move them to a
325 separate queue with less priority so that bulk traffic does not affect the
326 latency of critical traffic.
329 This is a special qdisc as it applies to incoming traffic on an interface, allowing for it to be filtered and policed.
332 The Multiqueue Priority Qdisc is a simple queuing discipline that allows
333 mapping traffic flows to hardware queue ranges using priorities and a
334 configurable priority to traffic class mapping. A traffic class in this context
335 is a set of contiguous qdisc classes which map 1:1 to a set of hardware exposed
339 Multiqueue is a qdisc optimized for devices with multiple Tx queues. It has
340 been added for hardware that wishes to avoid head-of-line blocking. It will
341 cycle though the bands and verify that the hardware queue associated with the
342 band is not stopped prior to dequeuing a packet.
345 Network Emulator is an enhancement of the Linux traffic control facilities that
346 allow to add delay, packet loss, duplication and more other characteristics to
347 packets outgoing from a selected network interface.
350 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
351 queue which honors Type of Service flags, as well as the priority that may be
352 assigned to a packet.
355 Proportional Integral controller-Enhanced (PIE) is a control theoretic active
356 queue management scheme. It is based on the proportional integral controller but
357 aims to control delay.
360 Random Early Detection simulates physical congestion by randomly dropping
361 packets when nearing configured bandwidth allocation. Well suited to very
362 large bandwidth applications.
365 Round-Robin qdisc with support for multiqueue network devices. Removed from
366 Linux since kernel version 2.6.27.
369 Stochastic Fair Blue is a classless qdisc to manage congestion based on
370 packet loss and link utilization history while trying to prevent
371 non-responsive flows (i.e. flows that do not react to congestion marking
372 or dropped packets) from impacting performance of responsive flows.
373 Unlike RED, where the marking probability has to be configured, BLUE
374 tries to determine the ideal marking probability automatically.
377 Stochastic Fairness Queueing reorders queued traffic so each 'session'
378 gets to send a packet in turn.
381 The Token Bucket Filter is suited for slowing traffic down to a precisely
382 configured rate. Scales well to large bandwidths.
383 .SH CONFIGURING CLASSLESS QDISCS
384 In the absence of classful qdiscs, classless qdiscs can only be attached at
385 the root of a device. Full syntax:
390 QDISC QDISC-PARAMETERS
400 qdisc is the automatic default in the absence of a configured qdisc.
403 The classful qdiscs are:
406 Map flows to virtual circuits of an underlying asynchronous transfer mode
410 Class Based Queueing implements a rich linksharing hierarchy of classes.
411 It contains shaping elements as well as prioritizing capabilities. Shaping is
412 performed using link idle time calculations based on average packet size and
413 underlying link bandwidth. The latter may be ill-defined for some interfaces.
416 The Deficit Round Robin Scheduler is a more flexible replacement for Stochastic
417 Fairness Queuing. Unlike SFQ, there are no built-in queues \-\- you need to add
418 classes and then set up filters to classify packets accordingly. This can be
419 useful e.g. for using RED qdiscs with different settings for particular
420 traffic. There is no default class \-\- if a packet cannot be classified, it is
424 Classify packets based on TOS field, change TOS field of packets based on
428 The ETS qdisc is a queuing discipline that merges functionality of PRIO and DRR
429 qdiscs in one scheduler. ETS makes it easy to configure a set of strict and
430 bandwidth-sharing bands to implement the transmission selection described in
434 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.
437 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
438 classes with an emphasis on conforming to existing practices. HTB facilitates
439 guaranteeing bandwidth to classes, while also allowing specification of upper
440 limits to inter-class sharing. It contains shaping elements, based on TBF and
441 can prioritize classes.
444 The PRIO qdisc is a non-shaping container for a configurable number of
445 classes which are dequeued in order. This allows for easy prioritization
446 of traffic, where lower classes are only able to send if higher ones have
447 no packets available. To facilitate configuration, Type Of Service bits are
451 Quick Fair Queueing is an O(1) scheduler that provides near-optimal guarantees,
452 and is the first to achieve that goal with a constant cost also with respect to
453 the number of groups and the packet length. The QFQ algorithm has no loops, and
454 uses very simple instructions and data structures that lend themselves very
455 well to a hardware implementation.
456 .SH THEORY OF OPERATION
457 Classes form a tree, where each class has a single parent.
458 A class may have multiple children. Some qdiscs allow for runtime addition
459 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
462 Qdiscs which allow dynamic addition of classes can have zero or more
463 subclasses to which traffic may be enqueued.
465 Furthermore, each class contains a
469 behaviour, although another qdisc can be attached in place. This qdisc may again
470 contain classes, but each class can have only one leaf qdisc.
472 When a packet enters a classful qdisc it can be
474 to one of the classes within. Three criteria are available, although not all
475 qdiscs will use all three:
478 If tc filters are attached to a class, they are consulted first
479 for relevant instructions. Filters can match on all fields of a packet header,
480 as well as on the firewall mark applied by iptables.
483 Some qdiscs have built in rules for classifying packets based on the TOS field.
486 Userspace programs can encode a \fIclass-id\fR in the 'skb->priority' field using
487 the SO_PRIORITY option.
489 Each node within the tree can have its own filters but higher level filters
490 may also point directly to lower classes.
492 If classification did not succeed, packets are enqueued to the leaf qdisc
493 attached to that class. Check qdisc specific manpages for details, however.
496 All qdiscs, classes and filters have IDs, which can either be specified
497 or be automatically assigned.
500 .BR major " number and a " minor
501 number, separated by a colon -
502 .BR major ":" minor "."
504 .BR major " and " minor
505 are hexadecimal numbers and are limited to 16 bits. There are two special
506 values: root is signified by
507 .BR major " and " minor
508 of all ones, and unspecified is all zeros.
512 A qdisc, which potentially can have children, gets assigned a
514 number, called a 'handle', leaving the
516 number namespace available for classes. The handle is expressed as '10:'.
517 It is customary to explicitly assign a handle to qdiscs expected to have children.
521 Classes residing under a qdisc share their qdisc
523 number, but each have a separate
525 number called a 'classid' that has no relation to their
526 parent classes, only to their parent qdisc. The same naming custom as for
531 Filters have a three part ID, which is only needed when using a hashed
535 The following parameters are widely used in TC. For other parameters,
536 see the man pages for individual qdiscs.
541 These parameters accept a floating point number, possibly followed by
542 either a unit (both SI and IEC units supported), or a float followed by a '%'
543 character to specify the rate as a percentage of the device's speed
544 (e.g. 5%, 99.5%). Warning: specifying the rate as a percentage means a fraction
545 of the current speed; if the speed changes, the value will not be recalculated.
579 To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with
580 IEC prefix (ki-, mi-, gi- and ti-) respectively.
583 TC store rates as a 32-bit unsigned integer in bps internally,
584 so we can specify a max rate of 4294967295 bps.
589 Length of time. Can be specified as a floating point number
590 followed by an optional unit:
599 us, usec, usecs or a bare number
603 TC defined its own time unit (equal to microsecond) and stores
604 time values as 32-bit unsigned integer, thus we can specify a max time value
610 Amounts of data. Can be specified as a floating point number
611 followed by an optional unit:
636 TC stores sizes internally as 32-bit unsigned integer in byte,
637 so we can specify a max size of 4294967295 bytes.
642 Other values without a unit.
643 These parameters are interpreted as decimal by default, but you can
644 indicate TC to interpret them as octal and hexadecimal by adding a '0'
645 or '0x' prefix respectively.
648 The following commands are available for qdiscs, classes and filter:
651 Add a qdisc, class or filter to a node. For all entities, a
653 must be passed, either by passing its ID or by attaching directly to the root of a device.
654 When creating a qdisc or a filter, it can be named with the
656 parameter. A class is named with the
662 A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
663 are automatically deleted, as well as any filters attached to them.
667 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
668 that the handle cannot be changed and neither can the parent. In other words,
675 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
680 Displays a single filter given the interface \fIDEV\fR, \fIqdisc-id\fR,
681 \fIpriority\fR, \fIprotocol\fR and \fIfilter-id\fR.
685 Displays all filters attached to the given interface. A valid parent ID must be passed.
689 Only available for qdiscs and performs a replace where the node
693 The\fB\ tc\fR\ utility can monitor events generated by the kernel such as
694 adding/deleting qdiscs, filters or actions, or modifying existing ones.
696 The following command is available for\fB\ monitor\fR\ :
699 If the file option is given, the \fBtc\fR does not listen to kernel events, but opens
700 the given file and dumps its contents. The file has to be in binary
701 format and contain netlink messages.
706 .BR "\-b", " \-b filename", " \-batch", " \-batch filename"
707 read commands from provided file or standard input and invoke them.
708 First failure will cause termination of tc.
712 don't terminate tc on errors in batch mode.
713 If there were any errors during execution of the commands, the application return code will be non zero.
716 .BR "\-o" , " \-oneline"
717 output each record on a single line, replacing line feeds
720 character. This is convenient when you want to count records
728 .BR "\-n" , " \-net" , " \-netns " <NETNS>
731 to the specified network namespace
733 Actually it just simplifies executing of:
738 .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | "
744 .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
748 .BR "\-N" , " \-Numeric"
749 Print the number of protocol, scope, dsfield, etc directly instead of
750 converting it to human readable name.
753 .BR "\-cf" , " \-conf " <FILENAME>
754 specifies path to the config file. This option is used in conjunction with other options (e.g.
758 .BR "\-t", " \-timestamp"
759 When\fB\ tc monitor\fR\ runs, print timestamp before the event message in format:
760 Timestamp: <Day> <Month> <DD> <hh:mm:ss> <YYYY> <usecs> usec
763 .BR "\-ts", " \-tshort"
764 When\fB\ tc monitor\fR\ runs, prints short timestamp before the event message in format:
765 [<YYYY>-<MM>-<DD>T<hh:mm:ss>.<ms>]
768 The show command has additional formatting options:
771 .BR "\-s" , " \-stats", " \-statistics"
772 output more statistics about packet usage.
775 .BR "\-d", " \-details"
776 output more detailed information about rates and cell sizes.
780 output raw hex values for handles.
783 .BR "\-p", " \-pretty"
784 for u32 filter, decode offset and mask values to equivalent filter commands based on TCP/IP.
785 In JSON output, add whitespace to improve readability.
789 print rates in IEC units (ie. 1K = 1024).
792 .BR "\-g", " \-graph"
793 shows classes as ASCII graph. Prints generic stats info under each class if
795 option was specified. Classes can be filtered only by
800 .BR \-c [ color ][ = { always | auto | never }
801 Configure color output. If parameter is omitted or
803 color output is enabled regardless of stdout state. If parameter is
805 stdout is checked to be a terminal before enabling color output. If parameter is
807 color output is disabled. If specified multiple times, the last one takes
808 precedence. This flag is ignored if
814 Display results in JSON format.
817 .BR "\-nm" , " \-name"
818 resolve class name from
819 .B /etc/iproute2/tc_cls
820 file or from file specified by
822 option. This file is just a mapping of
830 1:40 voip # Here is another comment
846 was specified without
849 .B /etc/iproute2/tc_cls
850 file does not exist, which makes it possible to pass
859 tc -g class show dev eth0
861 Shows classes as ASCII graph on eth0 interface.
864 tc -g -s class show dev eth0
866 Shows classes as ASCII graph with stats info under each class.
871 was written by Alexey N. Kuznetsov and added in Linux 2.2.
895 .BR tc-pfifo_fast (8),
906 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
909 Manpage maintained by bert hubert (ahu@ds9a.nl)
projects / mirror_iproute2.git / blob