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 [-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.
 206 .TP
 207 Type of Service
 208 Some qdiscs have built in rules for classifying packets based on the TOS field.
 209 .TP
 210 skb->priority
 211 Userspace programs can encode a class-id in the 'skb->priority' field using
 212 the SO_PRIORITY option.
 213 .P
 214 Each node within the tree can have its own filters but higher level filters
 215 may also point directly to lower classes.
 216
 217 If classification did not succeed, packets are enqueued to the leaf qdisc
 218 attached to that class. Check qdisc specific manpages for details, however.
 219
 220 .SH NAMING
 221 All qdiscs, classes and filters have IDs, which can either be specified
 222 or be automatically assigned.
 223
 224 IDs consist of a major number and a minor number, separated by a colon.
 225
 226 .TP
 227 QDISCS
 228 A qdisc, which potentially can have children,
 229 gets assigned a major number, called a 'handle', leaving the minor
 230 number namespace available for classes. The handle is expressed as '10:'.
 231 It is customary to explicitly assign a handle to qdiscs expected to have
 232 children.
 233
 234 .TP
 235 CLASSES
 236 Classes residing under a qdisc share their qdisc major number, but each have
 237 a separate minor number called a 'classid' that has no relation to their
 238 parent classes, only to their parent qdisc. The same naming custom as for
 239 qdiscs applies.
 240
 241 .TP
 242 FILTERS
 243 Filters have a three part ID, which is only needed when using a hashed
 244 filter hierarchy.
 245 .SH UNITS
 246 All parameters accept a floating point number, possibly followed by a unit.
 247 .P
 248 Bandwidths or rates can be specified in:
 249 .TP
 250 kbps
 251 Kilobytes per second
 252 .TP
 253 mbps
 254 Megabytes per second
 255 .TP
 256 kbit
 257 Kilobits per second
 258 .TP
 259 mbit
 260 Megabits per second
 261 .TP
 262 bps or a bare number
 263 Bytes per second
 264 .P
 265 Amounts of data can be specified in:
 266 .TP
 267 kb or k
 268 Kilobytes
 269 .TP
 270 mb or m
 271 Megabytes
 272 .TP
 273 mbit
 274 Megabits
 275 .TP
 276 kbit
 277 Kilobits
 278 .TP
 279 b or a bare number
 280 Bytes.
 281 .P
 282 Lengths of time can be specified in:
 283 .TP
 284 s, sec or secs
 285 Whole seconds
 286 .TP
 287 ms, msec or msecs
 288 Milliseconds
 289 .TP
 290 us, usec, usecs or a bare number
 291 Microseconds.
 292
 293 .SH TC COMMANDS
 294 The following commands are available for qdiscs, classes and filter:
 295 .TP
 296 add
 297 Add a qdisc, class or filter to a node. For all entities, a
 298 .B parent
 299 must be passed, either by passing its ID or by attaching directly to the root of a device.
 300 When creating a qdisc or a filter, it can be named with the
 301 .B handle
 302 parameter. A class is named with the
 303 .B classid
 304 parameter.
 305
 306 .TP
 307 remove
 308 A qdisc can be removed by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs
 309 are automatically deleted, as well as any filters attached to them.
 310
 311 .TP
 312 change
 313 Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception
 314 that the handle cannot be changed and neither can the parent. In other words,
 315 .B
 316 change
 317 cannot move a node.
 318
 319 .TP
 320 replace
 321 Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet
 322 it is created.
 323
 324 .TP
 325 link
 326 Only available for qdiscs and performs a replace where the node
 327 must exist already.
 328
 329
 330 .SH HISTORY
 331 .B tc
 332 was written by Alexey N. Kuznetsov and added in Linux 2.2.
 333 .SH SEE ALSO
 334 .BR tc-cbq (8),
 335 .BR tc-htb (8),
 336 .BR tc-sfq (8),
 337 .BR tc-red (8),
 338 .BR tc-tbf (8),
 339 .BR tc-pfifo (8),
 340 .BR tc-bfifo (8),
 341 .BR tc-pfifo_fast (8),
 342 .br
 343 .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org>
 344
 345 .SH AUTHOR
 346 Manpage maintained by bert hubert (ahu@ds9a.nl)
 347