]>
Commit | Line | Data |
---|---|---|
985794ad SH |
1 | .TH TC 8 "16 December 2001" "iproute2" "Linux" |
2 | .SH NAME | |
3 | tc \- show / manipulate traffic control settings | |
4 | .SH SYNOPSIS | |
67e1d73b VK |
5 | .B tc |
6 | .RI "[ " OPTIONS " ]" | |
7 | .B qdisc [ add | change | replace | link | delete ] dev | |
7c34520b BIG |
8 | DEV |
9 | .B | |
10 | [ parent | |
11 | qdisc-id | |
12 | .B | root ] | |
13 | .B [ handle | |
985794ad SH |
14 | qdisc-id ] qdisc |
15 | [ qdisc specific parameters ] | |
16 | .P | |
17 | ||
67e1d73b VK |
18 | .B tc |
19 | .RI "[ " OPTIONS " ]" | |
20 | .B class [ add | change | replace | delete ] dev | |
985794ad | 21 | DEV |
7c34520b BIG |
22 | .B parent |
23 | qdisc-id | |
24 | .B [ classid | |
985794ad SH |
25 | class-id ] qdisc |
26 | [ qdisc specific parameters ] | |
27 | .P | |
28 | ||
67e1d73b VK |
29 | .B tc |
30 | .RI "[ " OPTIONS " ]" | |
31 | .B filter [ add | change | replace | delete ] dev | |
985794ad | 32 | DEV |
d89fbf32 | 33 | .B [ parent |
985794ad SH |
34 | qdisc-id |
35 | .B | root ] protocol | |
36 | protocol | |
37 | .B prio | |
38 | priority filtertype | |
39 | [ filtertype specific parameters ] | |
40 | .B flowid | |
41 | flow-id | |
42 | ||
44dcfe82 | 43 | .B tc |
67e1d73b | 44 | .RI "[ " OPTIONS " ]" |
44dcfe82 | 45 | .RI "[ " FORMAT " ]" |
7c34520b BIG |
46 | .B qdisc show [ dev |
47 | DEV | |
d89fbf32 | 48 | .B ] |
985794ad | 49 | .P |
7c34520b | 50 | .B tc |
67e1d73b | 51 | .RI "[ " OPTIONS " ]" |
44dcfe82 | 52 | .RI "[ " FORMAT " ]" |
7c34520b BIG |
53 | .B class show dev |
54 | DEV | |
985794ad | 55 | .P |
67e1d73b VK |
56 | .B tc |
57 | .RI "[ " OPTIONS " ]" | |
58 | .B filter show dev | |
7c34520b | 59 | DEV |
985794ad | 60 | |
ce93fffe | 61 | .P |
67e1d73b VK |
62 | .ti 8 |
63 | .IR OPTIONS " := {" | |
64 | \fB[ -force ] -b\fR[\fIatch\fR] \fB[ filename ] \fR| | |
65 | \fB[ \fB-n\fR[\fIetns\fR] name \fB] \fR} | |
ce93fffe | 66 | |
7c34520b | 67 | .ti 8 |
44dcfe82 SH |
68 | .IR FORMAT " := {" |
69 | \fB\-s\fR[\fItatistics\fR] | | |
70 | \fB\-d\fR[\fIetails\fR] | | |
71 | \fB\-r\fR[\fIaw\fR] | | |
72 | \fB\-p\fR[\fIretty\fR] | | |
d9d1d1fa VK |
73 | \fB\-i\fR[\fIec\fR] | |
74 | \fB\-g\fR[\fIraph\fR] } | |
44dcfe82 | 75 | |
985794ad SH |
76 | .SH DESCRIPTION |
77 | .B Tc | |
7c34520b | 78 | is used to configure Traffic Control in the Linux kernel. Traffic Control consists |
985794ad SH |
79 | of the following: |
80 | ||
7c34520b | 81 | .TP |
985794ad | 82 | SHAPING |
7c34520b BIG |
83 | When traffic is shaped, its rate of transmission is under control. Shaping may |
84 | be more than lowering the available bandwidth - it is also used to smooth out | |
985794ad SH |
85 | bursts in traffic for better network behaviour. Shaping occurs on egress. |
86 | ||
7c34520b | 87 | .TP |
985794ad SH |
88 | SCHEDULING |
89 | By scheduling the transmission of packets it is possible to improve interactivity | |
90 | for traffic that needs it while still guaranteeing bandwidth to bulk transfers. Reordering | |
91 | is also called prioritizing, and happens only on egress. | |
92 | ||
93 | .TP | |
94 | POLICING | |
49572501 | 95 | Whereas shaping deals with transmission of traffic, policing pertains to traffic |
985794ad SH |
96 | arriving. Policing thus occurs on ingress. |
97 | ||
98 | .TP | |
99 | DROPPING | |
7c34520b | 100 | Traffic exceeding a set bandwidth may also be dropped forthwith, both on |
985794ad SH |
101 | ingress and on egress. |
102 | ||
103 | .P | |
7c34520b BIG |
104 | Processing of traffic is controlled by three kinds of objects: qdiscs, |
105 | classes and filters. | |
985794ad SH |
106 | |
107 | .SH QDISCS | |
7c34520b BIG |
108 | .B qdisc |
109 | is short for 'queueing discipline' and it is elementary to | |
110 | understanding traffic control. Whenever the kernel needs to send a | |
111 | packet to an interface, it is | |
985794ad SH |
112 | .B enqueued |
113 | to the qdisc configured for that interface. Immediately afterwards, the kernel | |
114 | tries to get as many packets as possible from the qdisc, for giving them | |
115 | to the network adaptor driver. | |
116 | ||
7c34520b | 117 | A simple QDISC is the 'pfifo' one, which does no processing at all and is a pure |
985794ad SH |
118 | First In, First Out queue. It does however store traffic when the network interface |
119 | can't handle it momentarily. | |
120 | ||
121 | .SH CLASSES | |
7c34520b | 122 | Some qdiscs can contain classes, which contain further qdiscs - traffic may |
985794ad SH |
123 | then be enqueued in any of the inner qdiscs, which are within the |
124 | .B classes. | |
7c34520b | 125 | When the kernel tries to dequeue a packet from such a |
985794ad | 126 | .B classful qdisc |
7c34520b | 127 | it can come from any of the classes. A qdisc may for example prioritize |
985794ad SH |
128 | certain kinds of traffic by trying to dequeue from certain classes |
129 | before others. | |
130 | ||
131 | .SH FILTERS | |
132 | A | |
133 | .B filter | |
134 | is used by a classful qdisc to determine in which class a packet will | |
135 | be enqueued. Whenever traffic arrives at a class with subclasses, it needs | |
136 | to be classified. Various methods may be employed to do so, one of these | |
7c34520b BIG |
137 | are the filters. All filters attached to the class are called, until one of |
138 | them returns with a verdict. If no verdict was made, other criteria may be | |
985794ad SH |
139 | available. This differs per qdisc. |
140 | ||
7c34520b | 141 | It is important to notice that filters reside |
985794ad SH |
142 | .B within |
143 | qdiscs - they are not masters of what happens. | |
144 | ||
145 | .SH CLASSLESS QDISCS | |
146 | The classless qdiscs are: | |
7c34520b | 147 | .TP |
985794ad | 148 | [p|b]fifo |
7c34520b | 149 | Simplest usable qdisc, pure First In, First Out behaviour. Limited in |
985794ad SH |
150 | packets or in bytes. |
151 | .TP | |
152 | pfifo_fast | |
153 | Standard qdisc for 'Advanced Router' enabled kernels. Consists of a three-band | |
7c34520b | 154 | queue which honors Type of Service flags, as well as the priority that may be |
985794ad SH |
155 | assigned to a packet. |
156 | .TP | |
157 | red | |
158 | Random Early Detection simulates physical congestion by randomly dropping | |
159 | packets when nearing configured bandwidth allocation. Well suited to very | |
160 | large bandwidth applications. | |
7c34520b | 161 | .TP |
985794ad SH |
162 | sfq |
163 | Stochastic Fairness Queueing reorders queued traffic so each 'session' | |
164 | gets to send a packet in turn. | |
165 | .TP | |
166 | tbf | |
167 | The Token Bucket Filter is suited for slowing traffic down to a precisely | |
7c34520b | 168 | configured rate. Scales well to large bandwidths. |
985794ad | 169 | .SH CONFIGURING CLASSLESS QDISCS |
7c34520b | 170 | In the absence of classful qdiscs, classless qdiscs can only be attached at |
985794ad SH |
171 | the root of a device. Full syntax: |
172 | .P | |
7c34520b BIG |
173 | .B tc qdisc add dev |
174 | DEV | |
175 | .B root | |
985794ad SH |
176 | QDISC QDISC-PARAMETERS |
177 | ||
178 | To remove, issue | |
179 | .P | |
180 | .B tc qdisc del dev | |
181 | DEV | |
182 | .B root | |
183 | ||
7c34520b | 184 | The |
985794ad SH |
185 | .B pfifo_fast |
186 | qdisc is the automatic default in the absence of a configured qdisc. | |
187 | ||
188 | .SH CLASSFUL QDISCS | |
189 | The classful qdiscs are: | |
190 | .TP | |
191 | CBQ | |
7c34520b | 192 | Class Based Queueing implements a rich linksharing hierarchy of classes. |
985794ad SH |
193 | It contains shaping elements as well as prioritizing capabilities. Shaping is |
194 | performed using link idle time calculations based on average packet size and | |
195 | underlying link bandwidth. The latter may be ill-defined for some interfaces. | |
196 | .TP | |
197 | HTB | |
7c34520b | 198 | The Hierarchy Token Bucket implements a rich linksharing hierarchy of |
985794ad SH |
199 | classes with an emphasis on conforming to existing practices. HTB facilitates |
200 | guaranteeing bandwidth to classes, while also allowing specification of upper | |
201 | limits to inter-class sharing. It contains shaping elements, based on TBF and | |
7c34520b BIG |
202 | can prioritize classes. |
203 | .TP | |
985794ad | 204 | PRIO |
7c34520b BIG |
205 | The PRIO qdisc is a non-shaping container for a configurable number of |
206 | classes which are dequeued in order. This allows for easy prioritization | |
207 | of traffic, where lower classes are only able to send if higher ones have | |
208 | no packets available. To facilitate configuration, Type Of Service bits are | |
985794ad SH |
209 | honored by default. |
210 | .SH THEORY OF OPERATION | |
7c34520b | 211 | Classes form a tree, where each class has a single parent. |
985794ad | 212 | A class may have multiple children. Some qdiscs allow for runtime addition |
7c34520b | 213 | of classes (CBQ, HTB) while others (PRIO) are created with a static number of |
985794ad SH |
214 | children. |
215 | ||
7c34520b BIG |
216 | Qdiscs which allow dynamic addition of classes can have zero or more |
217 | subclasses to which traffic may be enqueued. | |
985794ad SH |
218 | |
219 | Furthermore, each class contains a | |
220 | .B leaf qdisc | |
7c34520b BIG |
221 | which by default has |
222 | .B pfifo | |
49572501 | 223 | behaviour, although another qdisc can be attached in place. This qdisc may again |
7c34520b | 224 | contain classes, but each class can have only one leaf qdisc. |
985794ad | 225 | |
7c34520b | 226 | When a packet enters a classful qdisc it can be |
985794ad | 227 | .B classified |
7c34520b | 228 | to one of the classes within. Three criteria are available, although not all |
985794ad | 229 | qdiscs will use all three: |
7c34520b | 230 | .TP |
985794ad | 231 | tc filters |
7c34520b BIG |
232 | If tc filters are attached to a class, they are consulted first |
233 | for relevant instructions. Filters can match on all fields of a packet header, | |
234 | as well as on the firewall mark applied by ipchains or iptables. | |
985794ad SH |
235 | .TP |
236 | Type of Service | |
237 | Some qdiscs have built in rules for classifying packets based on the TOS field. | |
238 | .TP | |
239 | skb->priority | |
7c34520b | 240 | Userspace programs can encode a class-id in the 'skb->priority' field using |
985794ad SH |
241 | the SO_PRIORITY option. |
242 | .P | |
243 | Each node within the tree can have its own filters but higher level filters | |
244 | may also point directly to lower classes. | |
245 | ||
7c34520b | 246 | If classification did not succeed, packets are enqueued to the leaf qdisc |
985794ad SH |
247 | attached to that class. Check qdisc specific manpages for details, however. |
248 | ||
249 | .SH NAMING | |
250 | All qdiscs, classes and filters have IDs, which can either be specified | |
7c34520b | 251 | or be automatically assigned. |
985794ad | 252 | |
49572501 | 253 | IDs consist of a major number and a minor number, separated by a colon. |
d89fbf32 SH |
254 | Both major and minor number are limited to 16 bits. There are two special |
255 | values: root is signified by major and minor of all ones, and unspecified | |
256 | is all zeros. | |
985794ad | 257 | |
7c34520b | 258 | .TP |
985794ad | 259 | QDISCS |
7c34520b BIG |
260 | A qdisc, which potentially can have children, |
261 | gets assigned a major number, called a 'handle', leaving the minor | |
262 | number namespace available for classes. The handle is expressed as '10:'. | |
263 | It is customary to explicitly assign a handle to qdiscs expected to have | |
985794ad SH |
264 | children. |
265 | ||
7c34520b | 266 | .TP |
985794ad SH |
267 | CLASSES |
268 | Classes residing under a qdisc share their qdisc major number, but each have | |
7c34520b BIG |
269 | a separate minor number called a 'classid' that has no relation to their |
270 | parent classes, only to their parent qdisc. The same naming custom as for | |
985794ad SH |
271 | qdiscs applies. |
272 | ||
7c34520b | 273 | .TP |
985794ad SH |
274 | FILTERS |
275 | Filters have a three part ID, which is only needed when using a hashed | |
59a3ffb0 | 276 | filter hierarchy. |
8325daf7 LW |
277 | |
278 | .SH PARAMETERS | |
279 | The following parameters are widely used in TC. For other parameters, | |
280 | see the man pages for individual qdiscs. | |
281 | ||
6cef544b | 282 | .TP |
8325daf7 LW |
283 | RATES |
284 | Bandwidths or rates. | |
285 | These parameters accept a floating point number, possibly followed by | |
286 | a unit (both SI and IEC units supported). | |
287 | .RS | |
985794ad | 288 | .TP |
8325daf7 LW |
289 | bit or a bare number |
290 | Bits per second | |
985794ad SH |
291 | .TP |
292 | kbit | |
293 | Kilobits per second | |
294 | .TP | |
295 | mbit | |
296 | Megabits per second | |
297 | .TP | |
8325daf7 LW |
298 | gbit |
299 | Gigabits per second | |
985794ad | 300 | .TP |
8325daf7 LW |
301 | tbit |
302 | Terabits per second | |
985794ad | 303 | .TP |
8325daf7 LW |
304 | bps |
305 | Bytes per second | |
985794ad | 306 | .TP |
8325daf7 LW |
307 | kbps |
308 | Kilobytes per second | |
985794ad | 309 | .TP |
8325daf7 LW |
310 | mbps |
311 | Megabytes per second | |
985794ad | 312 | .TP |
8325daf7 LW |
313 | gbps |
314 | Gigabytes per second | |
315 | .TP | |
316 | tbps | |
317 | Terabytes per second | |
318 | ||
319 | .P | |
320 | To specify in IEC units, replace the SI prefix (k-, m-, g-, t-) with | |
321 | IEC prefix (ki-, mi-, gi- and ti-) respectively. | |
322 | ||
985794ad | 323 | .P |
8325daf7 LW |
324 | TC store rates as a 32-bit unsigned integer in bps internally, |
325 | so we can specify a max rate of 4294967295 bps. | |
326 | .RE | |
327 | ||
328 | .TP | |
329 | TIMES | |
330 | Length of time. Can be specified as a floating point number | |
331 | followed by an optional unit: | |
332 | .RS | |
985794ad SH |
333 | .TP |
334 | s, sec or secs | |
335 | Whole seconds | |
336 | .TP | |
337 | ms, msec or msecs | |
338 | Milliseconds | |
339 | .TP | |
340 | us, usec, usecs or a bare number | |
341 | Microseconds. | |
342 | ||
8325daf7 LW |
343 | .P |
344 | TC defined its own time unit (equal to microsecond) and stores | |
345 | time values as 32-bit unsigned integer, thus we can specify a max time value | |
346 | of 4294967295 usecs. | |
347 | .RE | |
348 | ||
349 | .TP | |
350 | SIZES | |
351 | Amounts of data. Can be specified as a floating point number | |
352 | followed by an optional unit: | |
353 | .RS | |
354 | .TP | |
355 | b or a bare number | |
356 | Bytes. | |
357 | .TP | |
358 | kbit | |
359 | Kilobits | |
360 | .TP | |
361 | kb or k | |
362 | Kilobytes | |
363 | .TP | |
364 | mbit | |
365 | Megabits | |
366 | .TP | |
367 | mb or m | |
368 | Megabytes | |
369 | .TP | |
370 | gbit | |
371 | Gigabits | |
372 | .TP | |
373 | gb or g | |
374 | Gigabytes | |
375 | ||
376 | .P | |
377 | TC stores sizes internally as 32-bit unsigned integer in byte, | |
378 | so we can specify a max size of 4294967295 bytes. | |
379 | .RE | |
380 | ||
381 | .TP | |
382 | VALUES | |
383 | Other values without a unit. | |
384 | These parameters are interpreted as decimal by default, but you can | |
385 | indicate TC to interpret them as octal and hexadecimal by adding a '0' | |
386 | or '0x' prefix respectively. | |
387 | ||
985794ad SH |
388 | .SH TC COMMANDS |
389 | The following commands are available for qdiscs, classes and filter: | |
390 | .TP | |
391 | add | |
7c34520b | 392 | Add a qdisc, class or filter to a node. For all entities, a |
985794ad | 393 | .B parent |
7c34520b | 394 | must be passed, either by passing its ID or by attaching directly to the root of a device. |
985794ad SH |
395 | When creating a qdisc or a filter, it can be named with the |
396 | .B handle | |
397 | parameter. A class is named with the | |
398 | .B classid | |
399 | parameter. | |
400 | ||
401 | .TP | |
3cde191f LW |
402 | delete |
403 | A qdisc can be deleted by specifying its handle, which may also be 'root'. All subclasses and their leaf qdiscs | |
985794ad SH |
404 | are automatically deleted, as well as any filters attached to them. |
405 | ||
406 | .TP | |
407 | change | |
408 | Some entities can be modified 'in place'. Shares the syntax of 'add', with the exception | |
7c34520b | 409 | that the handle cannot be changed and neither can the parent. In other words, |
985794ad | 410 | .B |
7c34520b | 411 | change |
985794ad SH |
412 | cannot move a node. |
413 | ||
414 | .TP | |
415 | replace | |
416 | Performs a nearly atomic remove/add on an existing node id. If the node does not exist yet | |
417 | it is created. | |
418 | ||
419 | .TP | |
420 | link | |
7c34520b | 421 | Only available for qdiscs and performs a replace where the node |
985794ad SH |
422 | must exist already. |
423 | ||
67e1d73b VK |
424 | .SH OPTIONS |
425 | ||
426 | .TP | |
427 | .BR "\-b", " \-b filename", " \-batch", " \-batch filename" | |
428 | read commands from provided file or standard input and invoke them. | |
429 | First failure will cause termination of tc. | |
430 | ||
431 | .TP | |
432 | .BR "\-force" | |
433 | don't terminate tc on errors in batch mode. | |
434 | If there were any errors during execution of the commands, the application return code will be non zero. | |
435 | ||
436 | .TP | |
437 | .BR "\-n" , " \-net" , " \-netns " <NETNS> | |
438 | switches | |
439 | .B tc | |
440 | to the specified network namespace | |
441 | .IR NETNS . | |
442 | Actually it just simplifies executing of: | |
443 | ||
444 | .B ip netns exec | |
445 | .IR NETNS | |
446 | .B tc | |
447 | .RI "[ " OPTIONS " ] " OBJECT " { " COMMAND " | " | |
448 | .BR help " }" | |
449 | ||
450 | to | |
451 | ||
452 | .B tc | |
453 | .RI "-n[etns] " NETNS " [ " OPTIONS " ] " OBJECT " { " COMMAND " | " | |
454 | .BR help " }" | |
455 | ||
44dcfe82 SH |
456 | .SH FORMAT |
457 | The show command has additional formatting options: | |
458 | ||
459 | .TP | |
460 | .BR "\-s" , " \-stats", " \-statistics" | |
461 | output more statistics about packet usage. | |
462 | ||
463 | .TP | |
464 | .BR "\-d", " \-details" | |
465 | output more detailed information about rates and cell sizes. | |
466 | ||
467 | .TP | |
468 | .BR "\-r", " \-raw" | |
469 | output raw hex values for handles. | |
470 | ||
471 | .TP | |
472 | .BR "\-p", " \-pretty" | |
473 | decode filter offset and mask values to equivalent filter commands based on TCP/IP. | |
474 | ||
475 | .TP | |
476 | .BR "\-iec" | |
477 | print rates in IEC units (ie. 1K = 1024). | |
478 | ||
d9d1d1fa VK |
479 | .TP |
480 | .BR "\-g", " \-graph" | |
481 | shows classes as ASCII graph. Prints generic stats info under each class if | |
482 | .BR "-s" | |
483 | option was specified. Classes can be filtered only by | |
484 | .BR "dev" | |
485 | option. | |
486 | ||
487 | .SH "EXAMPLES" | |
488 | .PP | |
489 | tc -g class show dev eth0 | |
490 | .RS 4 | |
491 | Shows classes as ASCII graph on eth0 interface. | |
492 | .RE | |
493 | .PP | |
494 | tc -g -s class show dev eth0 | |
495 | .RS 4 | |
496 | Shows classes as ASCII graph with stats info under each class. | |
497 | ||
985794ad SH |
498 | .SH HISTORY |
499 | .B tc | |
500 | was written by Alexey N. Kuznetsov and added in Linux 2.2. | |
501 | .SH SEE ALSO | |
05f1801c | 502 | .BR tc-bfifo (8), |
985794ad | 503 | .BR tc-cbq (8), |
b1978178 | 504 | .BR tc-choke (8), |
e1b59459 | 505 | .BR tc-codel (8), |
5080db33 | 506 | .BR tc-drr (8), |
c487348a | 507 | .BR tc-ematch (8), |
05f1801c | 508 | .BR tc-fq_codel (8), |
41f60041 | 509 | .BR tc-hfsc (7), |
05f1801c VS |
510 | .BR tc-hfsc (8), |
511 | .BR tc-htb (8), | |
39935c93 | 512 | .BR tc-mqprio (8), |
985794ad | 513 | .BR tc-pfifo (8), |
985794ad | 514 | .BR tc-pfifo_fast (8), |
05f1801c VS |
515 | .BR tc-red (8), |
516 | .BR tc-sfb (8), | |
517 | .BR tc-sfq (8), | |
41f60041 | 518 | .BR tc-stab (8), |
05f1801c | 519 | .BR tc-tbf (8), |
fd3877fe AW |
520 | .br |
521 | .RB "User documentation at " http://lartc.org/ ", but please direct bugreports and patches to: " <netdev@vger.kernel.org> | |
985794ad SH |
522 | |
523 | .SH AUTHOR | |
524 | Manpage maintained by bert hubert (ahu@ds9a.nl) | |
525 |