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