tc.8

   1 .TH TC 8 "16 December 2001" "iproute2" "Linux"
   2 .SH NAME
   3 tc \- show / manipulate traffic control settings
   4 .SH SYNOPSIS
   5 .B tc qdisc [ add | change | replace | link ] dev
   6 DEV
   7 .B
   8 [ parent
   9 qdisc-id
  10 .B | root ]
  11 .B [ handle
  12 qdisc-id ] qdisc
  13 [ qdisc specific parameters ]
  14 .P
  15
  16 .B tc class [ add | change | replace ] dev
  17 DEV
  18 .B parent
  19 qdisc-id
  20 .B [ classid
  21 class-id ] qdisc
  22 [ qdisc specific parameters ]
  23 .P
  24
  25 .B tc filter [ add | change | replace ] dev
  26 DEV
  27 .B  [ parent
  28 qdisc-id
  29 .B | root ] protocol
  30 protocol
  31 .B prio
  32 priority filtertype
  33 [ filtertype specific parameters ]
  34 .B flowid
  35 flow-id
  36
  37 .B tc [-s | -d ] qdisc show [ dev
  38 DEV
  39 .B  ]
  40 .P
  41 .B tc [-s | -d ] class show dev
  42 DEV
  43 .P
  44 .B tc filter show dev
  45 DEV
  46
  47 .SH DESCRIPTION
  48 .B Tc
  49 is used to configure Traffic Control in the Linux kernel. Traffic Control consists
  50 of the following:
  51
  52 .TP
  53 SHAPING
  54 When traffic is shaped, its rate of transmission is under control. Shaping may
  55 be more than lowering the available bandwidth - it is also used to smooth out
  56 bursts in traffic for better network behaviour. Shaping occurs on egress.
  57
  58 .TP
  59 SCHEDULING
  60 By scheduling the transmission of packets it is possible to improve interactivity
  61 for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering
  62 is also called prioritizing, and happens only on egress.
  63
  64 .TP
  65 POLICING
  66 Where shaping deals with transmission of traffic, policing pertains to traffic
  67 arriving. Policing thus occurs on ingress.
  68
  69 .TP
  70 DROPPING
  71 Traffic exceeding a set bandwidth may also be dropped forthwith, both on
  72 ingress and on egress.
  73
  74 .P
  75 Processing of traffic is controlled by three kinds of objects: qdiscs,
  76 classes and filters.
  77
  78 .SH QDISCS
  79 .B qdisc
  80 is short for 'queueing discipline' and it is elementary to
  81 understanding traffic control. Whenever the kernel needs to send a
  82 packet to an interface, it is
  83 .B enqueued
  84 to the qdisc configured for that interface. Immediately afterwards, the kernel
  85 tries to get as many packets as possible from the qdisc, for giving them
  86 to the network adaptor driver.
  87
  88 A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure
  89 First In, First Out queue. It does however store traffic when the network interface
  90 can't handle it momentarily.
  91
  92 .SH CLASSES
  93 Some qdiscs can contain classes, which contain further qdiscs - traffic may
  94 then be enqueued in any of the inner qdiscs, which are within the
  95 .B classes.
  96 When the kernel tries to dequeue a packet from such a
  97 .B classful qdisc
  98 it can come from any of the classes. A qdisc may for example prioritize
  99 certain kinds of traffic by trying to dequeue from certain classes
 100 before others.
 101
 102 .SH FILTERS
 103 A
 104 .B filter
 105 is used by a classful qdisc to determine in which class a packet will
 106 be enqueued. Whenever traffic arrives at a class with subclasses, it needs
 107 to be classified. Various methods may be employed to do so, one of these
 108 are the filters. All filters attached to the class are called, until one of
 109 them returns with a verdict. If no verdict was made, other criteria may be
 110 available. This differs per qdisc.
 111
 112 It is important to notice that filters reside
 113 .B within
 114 qdiscs - they are not masters of what happens.
 115
 116 .SH CLASSLESS QDISCS
 117 The classless qdiscs are:
 118 .TP
 119 [p|b]fifo
 120 Simplest usable qdisc, pure First In, First Out behaviour. Limited in
 121 packets or in bytes.
 122 .TP
 123 pfifo_fast
 124 Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band
 125 queue which honors Type of Service flags, as well as the priority that may be
 126 assigned to a packet.
 127 .TP
 128 red
 129 Random Early Detection simulates physical congestion by randomly dropping
 130 packets when nearing configured bandwidth allocation. Well suited to very
 131 large bandwidth applications.
 132 .TP
 133 sfq
 134 Stochastic Fairness Queueing reorders queued traffic so each 'session'
 135 gets to send a packet in turn.
 136 .TP
 137 tbf
 138 The Token Bucket Filter is suited for slowing traffic down to a precisely
 139 configured rate. Scales well to large bandwidths.
 140 .SH CONFIGURING CLASSLESS QDISCS
 141 In the absence of classful qdiscs, classless qdiscs can only be attached at
 142 the root of a device. Full syntax:
 143 .P
 144 .B tc qdisc add dev
 145 DEV
 146 .B root
 147 QDISC QDISC-PARAMETERS
 148
 149 To remove, issue
 150 .P
 151 .B tc qdisc del dev
 152 DEV
 153 .B root
 154
 155 The
 156 .B pfifo_fast
 157 qdisc is the automatic default in the absence of a configured qdisc.
 158
 159 .SH CLASSFUL QDISCS
 160 The classful qdiscs are:
 161 .TP
 162 CBQ
 163 Class Based Queueing implements a rich linksharing hierarchy of classes.
 164 It contains shaping elements as well as prioritizing capabilities. Shaping is
 165 performed using link idle time calculations based on average packet size and
 166 underlying link bandwidth. The latter may be ill-defined for some interfaces.
 167 .TP
 168 HTB
 169 The Hierarchy Token Bucket implements a rich linksharing hierarchy of
 170 classes with an emphasis on conforming to existing practices. HTB facilitates
 171 guaranteeing bandwidth to classes, while also allowing specification of upper
 172 limits to inter-class sharing. It contains shaping elements, based on TBF and
 173 can prioritize classes.
 174 .TP
 175 PRIO
 176 The PRIO qdisc is a non-shaping container for a configurable number of
 177 classes which are dequeued in order. This allows for easy prioritization
 178 of traffic, where lower classes are only able to send if higher ones have
 179 no packets available. To facilitate configuration, Type Of Service bits are
 180 honored by default.
 181 .SH THEORY OF OPERATION
 182 Classes form a tree, where each class has a single parent.
 183 A class may have multiple children. Some qdiscs allow for runtime addition
 184 of classes (CBQ, HTB) while others (PRIO) are created with a static number of
 185 children.
 186
 187 Qdiscs which allow dynamic addition of classes can have zero or more
 188 subclasses to which traffic may be enqueued.
 189
 190 Furthermore, each class contains a
 191 .B leaf qdisc
 192 which by default has
 193 .B pfifo
 194 behaviour though another qdisc can be attached in place. This qdisc may again
 195 contain classes, but each class can have only one leaf qdisc.
 196
 197 When a packet enters a classful qdisc it can be
 198 .B classified
 199 to one of the classes within. Three criteria are available, although not all
 200 qdiscs will use all three:
 201 .TP
 202 tc filters
 203 If tc filters are attached to a class, they are consulted first
 204 for relevant instructions. Filters can match on all fields of a packet header,
 205 as well as on the firewall mark applied by ipchains or iptables. See
 206 .BR tc-filters (8).
 207 .TP
 208 Type of Service
 209 Some qdiscs have built in rules for classifying packets based on the TOS field.
 210 .TP
 211 skb->priority
 212 Userspace programs can encode a class-id in the 'skb->priority' field using
 213 the SO_PRIORITY option.
 214 .P
 215 Each node within the tree can have its own filters but higher level filters
 216 may also point directly to lower classes.
 217
 218 If classification did not succeed, packets are enqueued to the leaf qdisc
 219 attached to that class. Check qdisc specific manpages for details, however.
 220
 221 .SH NAMING
 222 All qdiscs, classes and filters have IDs, which can either be specified
 223 or be automatically assigned.
 224
 225 IDs consist of a major number and a minor number, separated by a colon.
 226
 227 .TP
 228 QDISCS
 229 A qdisc, which potentially can have children,
 230 gets assigned a major number, called a 'handle', leaving the minor
 231 number namespace available for classes. The handle is expressed as '10:'.
 232 It is customary to explicitly assign a handle to qdiscs expected to have
 233 children.
 234
 235 .TP
 236 CLASSES
 237 Classes residing under a qdisc share their qdisc major number, but each have
 238 a separate minor number called a 'classid' that has no relation to their
 239 parent classes, only to their parent qdisc. The same naming custom as for
 240 qdiscs applies.
 241
 242 .TP
 243 FILTERS
 244 Filters have a three part ID, which is only needed when using a hashed
 245 filter hierarchy, for which see
 246 .BR tc-filters (8).
 247 .SH UNITS
 248 All parameters accept a floating point number, possibly followed by a unit.
 249 .P
 250 Bandwidths or rates can be specified in:
 251 .TP
 252 kbps
 253 Kilobytes per second
 254 .TP
 255 mbps
 256 Megabytes per second
 257 .TP
 258 kbit
 259 Kilobits per second
 260 .TP
 261 mbit
 262 Megabits per second
 263 .TP
 264 bps or a bare number
 265 Bytes per second
 266 .P
 267 Amounts of data can be specified in:
 268 .TP
 269 kb or k
 270 Kilobytes
 271 .TP
 272 mb or m
 273 Megabytes
 274 .TP
 275 mbit
 276 Megabits
 277 .TP
 278 kbit
 279 Kilobits
 280 .TP
 281 b or a bare number
 282 Bytes.
 283 .P
 284 Lengths of time can be specified in:
 285 .TP
 286 s, sec or secs
 287 Whole seconds
 288 .TP
 289 ms, msec or msecs
 290 Milliseconds
 291 .TP
 292 us, usec, usecs or a bare number
 293 Microseconds.
 294
 295 .SH TC COMMANDS
 296 The following commands are available for qdiscs, classes and filter:
 297 .TP
 298 add
 299 Add a qdisc, class or filter to a node. For all entities, a
 300 .B parent
 301 must be passed, either by passing its ID or by attaching directly to the root of a device.
 302 When creating a qdisc or a filter, it can be named with the
 303 .B handle
 304 parameter. A class is named with the
 305 .B classid
 306 parameter.
 307
 308 .TP
 309 remove
 310 A qdisc can be removed by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
 311 are automatically deleted, as well as any filters attached to them.
 312
 313 .TP
 314 change
 315 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
 316 that the handle cannot be changed and neither can the parent. In other words,
 317 .B
 318 change
 319 cannot move a node.
 320
 321 .TP
 322 replace
 323 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
 324 it is created.
 325
 326 .TP
 327 link
 328 Only available for qdiscs and performs a replace where the node
 329 must exist already.
 330
 331
 332 .SH HISTORY
 333 .B tc
 334 was written by Alexey N. Kuznetsov and added in Linux 2.2.
 335 .SH SEE ALSO
 336 .BR tc-cbq (8),
 337 .BR tc-htb (8),
 338 .BR tc-sfq (8),
 339 .BR tc-red (8),
 340 .BR tc-tbf (8),
 341 .BR tc-pfifo (8),
 342 .BR tc-bfifo (8),
 343 .BR tc-pfifo_fast (8),
 344 .BR tc-filters (8)
 345
 346 .SH AUTHOR
 347 Manpage maintained by bert hubert (ahu@ds9a.nl)
 348