1TC(8)                                Linux                               TC(8)
2
3
4

NAME

6       tc - show / manipulate traffic control settings
7

SYNOPSIS

9       tc [ OPTIONS ] qdisc [ add | change | replace | link | delete ] dev DEV
10       [ parent qdisc-id  |  root  ]  [  handle  qdisc-id  ]  [  ingress_block
11       BLOCK_INDEX  ]  [  egress_block  BLOCK_INDEX  ]  qdisc [ qdisc specific
12       parameters ]
13
14       tc [ OPTIONS ] class [ add | change | replace | delete ] dev DEV parent
15       qdisc-id [ classid class-id ] qdisc [ qdisc specific parameters ]
16
17       tc [ OPTIONS ] filter [ add | change | replace | delete | get ] dev DEV
18       [ parent qdisc-id | root ] [ handle filter-id ] protocol protocol  prio
19       priority filtertype [ filtertype specific parameters ] flowid flow-id
20
21       tc  [  OPTIONS ] filter [ add | change | replace | delete | get ] block
22       BLOCK_INDEX [ handle filter-id ] protocol protocol prio  priority  fil‐
23       tertype [ filtertype specific parameters ] flowid flow-id
24
25       tc [ OPTIONS ] chain [ add | delete | get ] dev DEV [ parent qdisc-id |
26       root ] filtertype [ filtertype specific parameters ]
27
28       tc [ OPTIONS ] chain [ add | delete | get ] block  BLOCK_INDEX  filter‐
29       type [ filtertype specific parameters ]
30
31
32       tc [ OPTIONS ] [ FORMAT ] qdisc show [ dev DEV ]
33
34       tc [ OPTIONS ] [ FORMAT ] class show dev DEV
35
36       tc [ OPTIONS ] filter show dev DEV
37
38       tc [ OPTIONS ] filter show block BLOCK_INDEX
39
40       tc [ OPTIONS ] chain show dev DEV
41
42       tc [ OPTIONS ] chain show block BLOCK_INDEX
43
44
45       tc [ OPTIONS ] monitor [ file FILENAME ]
46
47
48        OPTIONS  := { [ -force ] -b[atch] [ filename ] | [ -n[etns] name ] | [
49       -N[umeric] ] | [ -nm | -nam[es] ] | [ { -cf | -c[onf] } [ filename ]  ]
50       [ -t[imestamp] ] | [ -t[short] | [ -o[neline] ] }
51
52        FORMAT  := { -s[tatistics] | -d[etails] | -r[aw] | -i[ec] | -g[raph] |
53       -j[json] | -p[retty] | -col[or] }
54
55

DESCRIPTION

57       Tc is used to configure Traffic Control in the  Linux  kernel.  Traffic
58       Control consists of the following:
59
60
61       SHAPING
62              When  traffic  is shaped, its rate of transmission is under con‐
63              trol. Shaping may be more than lowering the available  bandwidth
64              -  it  is  also  used to smooth out bursts in traffic for better
65              network behaviour. Shaping occurs on egress.
66
67
68       SCHEDULING
69              By scheduling the transmission of  packets  it  is  possible  to
70              improve  interactivity  for  traffic  that  needs it while still
71              guaranteeing bandwidth to bulk  transfers.  Reordering  is  also
72              called prioritizing, and happens only on egress.
73
74
75       POLICING
76              Whereas  shaping  deals  with  transmission of traffic, policing
77              pertains to traffic arriving. Policing thus occurs on ingress.
78
79
80       DROPPING
81              Traffic exceeding a set bandwidth may also be dropped forthwith,
82              both on ingress and on egress.
83
84
85       Processing  of traffic is controlled by three kinds of objects: qdiscs,
86       classes and filters.
87
88

QDISCS

90       qdisc is short for 'queueing discipline' and it is elementary to under‐
91       standing traffic control. Whenever the kernel needs to send a packet to
92       an interface, it is enqueued to the qdisc configured  for  that  inter‐
93       face.  Immediately  afterwards, the kernel tries to get as many packets
94       as possible from the qdisc, for giving  them  to  the  network  adaptor
95       driver.
96
97       A  simple QDISC is the 'pfifo' one, which does no processing at all and
98       is a pure First In, First Out queue. It does however store traffic when
99       the network interface can't handle it momentarily.
100
101

CLASSES

103       Some qdiscs can contain classes, which contain further qdiscs - traffic
104       may then be enqueued in any of the inner qdiscs, which are  within  the
105       classes.   When the kernel tries to dequeue a packet from such a class‐
106       ful qdisc it can come from any of the classes. A qdisc may for  example
107       prioritize  certain  kinds of traffic by trying to dequeue from certain
108       classes before others.
109
110

FILTERS

112       A filter is used by a classful qdisc to  determine  in  which  class  a
113       packet  will be enqueued. Whenever traffic arrives at a class with sub‐
114       classes, it needs to be classified. Various methods may be employed  to
115       do  so, one of these are the filters. All filters attached to the class
116       are called, until one of them returns with a verdict. If no verdict was
117       made, other criteria may be available. This differs per qdisc.
118
119       It  is important to notice that filters reside within qdiscs - they are
120       not masters of what happens.
121
122       The available filters are:
123
124       basic  Filter packets based on an ematch expression.  See  tc-ematch(8)
125              for details.
126
127       bpf    Filter packets using (e)BPF, see tc-bpf(8) for details.
128
129       cgroup Filter  packets based on the control group of their process. See
130              tc-cgroup(8) for details.
131
132       flow, flower
133              Flow-based classifiers, filtering packets based  on  their  flow
134              (identified by selectable keys). See tc-flow(8) and tc-flower(8)
135              for details.
136
137       fw     Filter based on fwmark. Directly maps fwmark  value  to  traffic
138              class. See tc-fw(8).
139
140       route  Filter  packets  based  on  routing  table.  See tc-route(8) for
141              details.
142
143       rsvp   Match Resource Reservation Protocol (RSVP) packets.
144
145       tcindex
146              Filter packets based on  traffic  control  index.  See  tc-tcin‐
147              dex(8).
148
149       u32    Generic  filtering  on arbitrary packet data, assisted by syntax
150              to abstract common operations. See tc-u32(8) for details.
151
152       matchall
153              Traffic control  filter  that  matches  every  packet.  See  tc-
154              matchall(8) for details.
155
156

CLASSLESS QDISCS

158       The classless qdiscs are:
159
160       choke  CHOKe (CHOose and Keep for responsive flows, CHOose and Kill for
161              unresponsive flows) is a classless qdisc designed to both  iden‐
162              tify  and  penalize  flows that monopolize the queue. CHOKe is a
163              variation of RED, and the configuration is similar to RED.
164
165       codel  CoDel (pronounced "coddle") is  an  adaptive  "no-knobs"  active
166              queue  management  algorithm  (AQM) scheme that was developed to
167              address the shortcomings of RED and its variants.
168
169       [p|b]fifo
170              Simplest usable qdisc, pure First In, First Out behaviour.  Lim‐
171              ited in packets or in bytes.
172
173       fq     Fair  Queue Scheduler realises TCP pacing and scales to millions
174              of concurrent flows per qdisc.
175
176       fq_codel
177              Fair Queuing Controlled Delay is queuing  discipline  that  com‐
178              bines  Fair  Queuing  with the CoDel AQM scheme. FQ_Codel uses a
179              stochastic model to classify  incoming  packets  into  different
180              flows  and  is  used to provide a fair share of the bandwidth to
181              all the flows using the queue. Each such flow is managed by  the
182              CoDel  queuing  discipline.  Reordering within a flow is avoided
183              since Codel internally uses a FIFO queue.
184
185       gred   Generalized Random Early Detection combines multiple RED  queues
186              in  order  to achieve multiple drop priorities. This is required
187              to realize Assured Forwarding (RFC 2597).
188
189       hhf    Heavy-Hitter Filter differentiates between small flows  and  the
190              opposite,  heavy-hitters. The goal is to catch the heavy-hitters
191              and move them to a separate queue with  less  priority  so  that
192              bulk traffic does not affect the latency of critical traffic.
193
194       ingress
195              This  is a special qdisc as it applies to incoming traffic on an
196              interface, allowing for it to be filtered and policed.
197
198       mqprio The Multiqueue Priority Qdisc is  a  simple  queuing  discipline
199              that allows mapping traffic flows to hardware queue ranges using
200              priorities and a configurable priority to traffic class mapping.
201              A  traffic  class  in  this context is a set of contiguous qdisc
202              classes which map 1:1 to a set of hardware exposed queues.
203
204       multiq Multiqueue is a qdisc optimized for  devices  with  multiple  Tx
205              queues.  It  has  been  added  for hardware that wishes to avoid
206              head-of-line blocking.  It will cycle though the bands and  ver‐
207              ify  that  the  hardware  queue  associated with the band is not
208              stopped prior to dequeuing a packet.
209
210       netem  Network Emulator is an enhancement of the Linux traffic  control
211              facilities that allow to add delay, packet loss, duplication and
212              more other characteristics to packets outgoing from  a  selected
213              network interface.
214
215       pfifo_fast
216              Standard  qdisc  for 'Advanced Router' enabled kernels. Consists
217              of a three-band queue which honors Type  of  Service  flags,  as
218              well as the priority that may be assigned to a packet.
219
220       pie    Proportional  Integral  controller-Enhanced  (PIE)  is a control
221              theoretic active queue management scheme. It  is  based  on  the
222              proportional integral controller but aims to control delay.
223
224       red    Random Early Detection simulates physical congestion by randomly
225              dropping packets when nearing configured  bandwidth  allocation.
226              Well suited to very large bandwidth applications.
227
228       rr     Round-Robin  qdisc  with support for multiqueue network devices.
229              Removed from Linux since kernel version 2.6.27.
230
231       sfb    Stochastic Fair Blue is a classless qdisc to  manage  congestion
232              based  on  packet loss and link utilization history while trying
233              to prevent non-responsive flows (i.e. flows that do not react to
234              congestion  marking  or  dropped packets) from impacting perfor‐
235              mance of responsive flows.  Unlike RED, where the marking proba‐
236              bility  has  to be configured, BLUE tries to determine the ideal
237              marking probability automatically.
238
239       sfq    Stochastic Fairness Queueing reorders  queued  traffic  so  each
240              'session' gets to send a packet in turn.
241
242       tbf    The  Token Bucket Filter is suited for slowing traffic down to a
243              precisely configured rate. Scales well to large bandwidths.
244

CONFIGURING CLASSLESS QDISCS

246       In the absence  of  classful  qdiscs,  classless  qdiscs  can  only  be
247       attached at the root of a device. Full syntax:
248
249       tc qdisc add dev DEV root QDISC QDISC-PARAMETERS
250
251       To remove, issue
252
253       tc qdisc del dev DEV root
254
255       The  pfifo_fast qdisc is the automatic default in the absence of a con‐
256       figured qdisc.
257
258

CLASSFUL QDISCS

260       The classful qdiscs are:
261
262       ATM    Map flows to virtual  circuits  of  an  underlying  asynchronous
263              transfer mode device.
264
265       CBQ    Class  Based Queueing implements a rich linksharing hierarchy of
266              classes.  It contains shaping elements as well  as  prioritizing
267              capabilities. Shaping is performed using link idle time calcula‐
268              tions based on average packet size  and  underlying  link  band‐
269              width. The latter may be ill-defined for some interfaces.
270
271       DRR    The Deficit Round Robin Scheduler is a more flexible replacement
272              for Stochastic Fairness Queuing. Unlike SFQ, there are no built-
273              in  queues -- you need to add classes and then set up filters to
274              classify packets accordingly.  This can be useful e.g. for using
275              RED qdiscs with different settings for particular traffic. There
276              is no default class -- if a packet cannot be classified,  it  is
277              dropped.
278
279       DSMARK Classify packets based on TOS field, change TOS field of packets
280              based on classification.
281
282       HFSC   Hierarchical Fair Service Curve guarantees precise bandwidth and
283              delay allocation for leaf classes and allocates excess bandwidth
284              fairly. Unlike HTB, it makes use of packet dropping  to  achieve
285              low delays which interactive sessions benefit from.
286
287       HTB    The Hierarchy Token Bucket implements a rich linksharing hierar‐
288              chy of classes with an emphasis on conforming to existing  prac‐
289              tices.  HTB facilitates guaranteeing bandwidth to classes, while
290              also allowing specification of upper limits to inter-class shar‐
291              ing.  It contains shaping elements, based on TBF and can priori‐
292              tize classes.
293
294       PRIO   The PRIO qdisc is a non-shaping  container  for  a  configurable
295              number  of  classes which are dequeued in order. This allows for
296              easy prioritization of traffic, where  lower  classes  are  only
297              able to send if higher ones have no packets available. To facil‐
298              itate  configuration,  Type  Of  Service  bits  are  honored  by
299              default.
300
301       QFQ    Quick  Fair  Queueing  is  an O(1) scheduler that provides near-
302              optimal guarantees, and is the first to achieve that goal with a
303              constant  cost also with respect to the number of groups and the
304              packet length. The QFQ algorithm has no  loops,  and  uses  very
305              simple  instructions  and  data  structures that lend themselves
306              very well to a hardware implementation.
307

THEORY OF OPERATION

309       Classes form a tree, where each class has a single parent.  A class may
310       have  multiple  children.  Some  qdiscs  allow  for runtime addition of
311       classes (CBQ, HTB) while others (PRIO) are created with a static number
312       of children.
313
314       Qdiscs  which  allow  dynamic addition of classes can have zero or more
315       subclasses to which traffic may be enqueued.
316
317       Furthermore, each class contains a leaf  qdisc  which  by  default  has
318       pfifo  behaviour, although another qdisc can be attached in place. This
319       qdisc may again contain classes, but each class can have only one  leaf
320       qdisc.
321
322       When  a  packet  enters a classful qdisc it can be classified to one of
323       the classes within. Three criteria  are  available,  although  not  all
324       qdiscs will use all three:
325
326       tc filters
327              If  tc filters are attached to a class, they are consulted first
328              for relevant instructions. Filters can match on all fields of  a
329              packet  header,  as  well  as  on  the  firewall mark applied by
330              ipchains or iptables.
331
332       Type of Service
333              Some qdiscs have built in rules for classifying packets based on
334              the TOS field.
335
336       skb->priority
337              Userspace  programs can encode a class-id in the 'skb->priority'
338              field using the SO_PRIORITY option.
339
340       Each node within the tree can have its own  filters  but  higher  level
341       filters may also point directly to lower classes.
342
343       If  classification  did  not  succeed, packets are enqueued to the leaf
344       qdisc attached  to  that  class.  Check  qdisc  specific  manpages  for
345       details, however.
346
347

NAMING

349       All qdiscs, classes and filters have IDs, which can either be specified
350       or be automatically assigned.
351
352       IDs consist of a major number and a minor number, separated by a  colon
353       -  major:minor.   Both  major and minor are hexadecimal numbers and are
354       limited to 16 bits. There are two special values: root is signified  by
355       major and minor of all ones, and unspecified is all zeros.
356
357
358       QDISCS A  qdisc,  which  potentially can have children, gets assigned a
359              major number, called a 'handle', leaving the minor number names‐
360              pace  available  for  classes. The handle is expressed as '10:'.
361              It is customary to explicitly assign a handle to qdiscs expected
362              to have children.
363
364
365       CLASSES
366              Classes  residing  under a qdisc share their qdisc major number,
367              but each have a separate minor number called  a  'classid'  that
368              has  no  relation  to their parent classes, only to their parent
369              qdisc. The same naming custom as for qdiscs applies.
370
371
372       FILTERS
373              Filters have a three part ID, which is only needed when using  a
374              hashed filter hierarchy.
375
376

PARAMETERS

378       The  following  parameters are widely used in TC. For other parameters,
379       see the man pages for individual qdiscs.
380
381
382       RATES  Bandwidths or rates.  These parameters accept a  floating  point
383              number,  possibly  followed  by  either  a unit (both SI and IEC
384              units supported), or a float followed  by  a  '%'  character  to
385              specify the rate as a percentage of the device's speed (e.g. 5%,
386              99.5%). Warning: specifying the rate as  a  percentage  means  a
387              fraction  of  the current speed; if the speed changes, the value
388              will not be recalculated.
389
390              bit or a bare number
391                     Bits per second
392
393              kbit   Kilobits per second
394
395              mbit   Megabits per second
396
397              gbit   Gigabits per second
398
399              tbit   Terabits per second
400
401              bps    Bytes per second
402
403              kbps   Kilobytes per second
404
405              mbps   Megabytes per second
406
407              gbps   Gigabytes per second
408
409              tbps   Terabytes per second
410
411
412              To specify in IEC units, replace the SI prefix (k-, m-, g-,  t-)
413              with IEC prefix (ki-, mi-, gi- and ti-) respectively.
414
415
416              TC  store  rates as a 32-bit unsigned integer in bps internally,
417              so we can specify a max rate of 4294967295 bps.
418
419
420       TIMES  Length of time. Can be specified as a floating point number fol‐
421              lowed by an optional unit:
422
423              s, sec or secs
424                     Whole seconds
425
426              ms, msec or msecs
427                     Milliseconds
428
429              us, usec, usecs or a bare number
430                     Microseconds.
431
432
433              TC  defined  its own time unit (equal to microsecond) and stores
434              time values as 32-bit unsigned integer, thus we  can  specify  a
435              max time value of 4294967295 usecs.
436
437
438       SIZES  Amounts  of  data.  Can  be specified as a floating point number
439              followed by an optional unit:
440
441              b or a bare number
442                     Bytes.
443
444              kbit   Kilobits
445
446              kb or k
447                     Kilobytes
448
449              mbit   Megabits
450
451              mb or m
452                     Megabytes
453
454              gbit   Gigabits
455
456              gb or g
457                     Gigabytes
458
459
460              TC stores sizes internally as 32-bit unsigned integer  in  byte,
461              so we can specify a max size of 4294967295 bytes.
462
463
464       VALUES Other  values  without a unit.  These parameters are interpreted
465              as decimal by default, but you can indicate TC to interpret them
466              as  octal and hexadecimal by adding a '0' or '0x' prefix respec‐
467              tively.
468
469

TC COMMANDS

471       The following commands are available for qdiscs, classes and filter:
472
473       add    Add a qdisc, class or filter to a node. For all entities, a par‐
474              ent  must  be  passed,  either by passing its ID or by attaching
475              directly to the root of a device.  When creating a  qdisc  or  a
476              filter,  it  can  be named with the handle parameter. A class is
477              named with the classid parameter.
478
479
480       delete A qdisc can be deleted by specifying its handle, which may  also
481              be  'root'.  All  subclasses and their leaf qdiscs are automati‐
482              cally deleted, as well as any filters attached to them.
483
484
485       change Some entities can be modified 'in place'. Shares the  syntax  of
486              'add',  with the exception that the handle cannot be changed and
487              neither can the parent. In other words,  change  cannot  move  a
488              node.
489
490
491       replace
492              Performs  a  nearly atomic remove/add on an existing node id. If
493              the node does not exist yet it is created.
494
495
496       get    Displays a single filter given the interface DEV, qdisc-id, pri‐
497              ority, protocol and filter-id.
498
499
500       show   Displays  all  filters  attached to the given interface. A valid
501              parent ID must be passed.
502
503
504       link   Only available for qdiscs and performs a replace where the  node
505              must exist already.
506
507

MONITOR

509       The tc utility  can  monitor  events  generated  by  the kernel such as
510       adding/deleting qdiscs, filters or actions, or modifying existing ones.
511
512       The following command is available for monitor :
513
514       file   If the file option is given, the tc does not  listen  to  kernel
515              events,  but  opens  the  given file and dumps its contents. The
516              file has to be in binary format and contain netlink messages.
517
518

OPTIONS

520       -b, -b filename, -batch, -batch filename
521              read commands from provided file or standard  input  and  invoke
522              them.  First failure will cause termination of tc.
523
524
525       -force don't  terminate  tc on errors in batch mode.  If there were any
526              errors during execution of the commands, the application  return
527              code will be non zero.
528
529
530       -o, -oneline
531              output  each  record on a single line, replacing line feeds with
532              the '\' character. This is convenient when  you  want  to  count
533              records with wc(1) or to grep(1) the output.
534
535
536       -n, -net, -netns <NETNS>
537              switches  tc to the specified network namespace NETNS.  Actually
538              it just simplifies executing of:
539
540              ip netns exec NETNS tc [ OPTIONS ] OBJECT { COMMAND | help }
541
542              to
543
544              tc -n[etns] NETNS [ OPTIONS ] OBJECT { COMMAND | help }
545
546
547       -N, -Numeric
548              Print the number  of  protocol,  scope,  dsfield,  etc  directly
549              instead of converting it to human readable name.
550
551
552       -cf, -conf <FILENAME>
553              specifies  path  to the config file. This option is used in con‐
554              junction with other options (e.g.  -nm).
555
556
557       -t, -timestamp
558              When tc monitor runs, print timestamp before the  event  message
559              in format:
560                 Timestamp: <Day> <Month> <DD> <hh:mm:ss> <YYYY> <usecs> usec
561
562
563       -ts, -tshort
564              When tc  monitor runs,  prints  short timestamp before the event
565              message in format:
566                 [<YYYY>-<MM>-<DD>T<hh:mm:ss>.<ms>]
567
568

FORMAT

570       The show command has additional formatting options:
571
572
573       -s, -stats, -statistics
574              output more statistics about packet usage.
575
576
577       -d, -details
578              output more detailed information about rates and cell sizes.
579
580
581       -r, -raw
582              output raw hex values for handles.
583
584
585       -p, -pretty
586              for u32 filter, decode offset and mask values to equivalent fil‐
587              ter commands based on TCP/IP.  In JSON output, add whitespace to
588              improve readability.
589
590
591       -iec   print rates in IEC units (ie. 1K = 1024).
592
593
594       -g, -graph
595              shows classes as ASCII graph. Prints generic  stats  info  under
596              each  class  if -s option was specified. Classes can be filtered
597              only by dev option.
598
599
600       -c[color][={always|auto|never}
601              Configure color output. If parameter is omitted or always, color
602              output  is  enabled  regardless of stdout state. If parameter is
603              auto, stdout is checked to be a terminal before  enabling  color
604              output.  If  parameter  is  never,  color output is disabled. If
605              specified multiple times, the last one  takes  precedence.  This
606              flag is ignored if -json is also given.
607
608
609       -j, -json
610              Display results in JSON format.
611
612
613       -nm, -name
614              resolve  class  name from /etc/iproute2/tc_cls file or from file
615              specified by -cf option. This file is just a mapping of  classid
616              to class name:
617
618                 # Here is comment
619                 1:40   voip # Here is another comment
620                 1:50   web
621                 1:60   ftp
622                 1:2    home
623
624              tc  will  not  fail  if -nm was specified without -cf option but
625              /etc/iproute2/tc_cls file does not exist, which makes it  possi‐
626              ble to pass -nm option for creating tc alias.
627
628

EXAMPLES

630       tc -g class show dev eth0
631           Shows classes as ASCII graph on eth0 interface.
632
633       tc -g -s class show dev eth0
634           Shows classes as ASCII graph with stats info under each class.
635
636

HISTORY

638       tc was written by Alexey N. Kuznetsov and added in Linux 2.2.
639

SEE ALSO

641       tc-basic(8),   tc-bfifo(8),   tc-bpf(8),   tc-cake(8),  tc-cbq(8),  tc-
642       cgroup(8),  tc-choke(8),  tc-codel(8),  tc-drr(8),  tc-ematch(8),   tc-
643       flow(8),  tc-flower(8), tc-fq(8), tc-fq_codel(8), tc-fw(8), tc-hfsc(7),
644       tc-hfsc(8), tc-htb(8), tc-mqprio(8), tc-pfifo(8), tc-pfifo_fast(8), tc-
645       pie(8),  tc-red(8),  tc-route(8), tc-sfb(8), tc-sfq(8), tc-stab(8), tc-
646       tbf(8), tc-tcindex(8), tc-u32(8),
647       User documentation at http://lartc.org/, but please  direct  bugreports
648       and patches to: <netdev@vger.kernel.org>
649
650

AUTHOR

652       Manpage maintained by bert hubert (ahu@ds9a.nl)
653
654
655
656iproute2                       16 December 2001                          TC(8)
Impressum