Add man pages for ip and tc-prio
[lartc.git] / manpages / tc-prio.8
blobe942e62ed3bb8659e67198d9fce64fe32fce956e
1 .TH PRIO 8 "16 December 2001" "iproute2" "Linux"
2 .SH NAME
3 PRIO \- Priority qdisc
4 .SH SYNOPSIS
5 .B tc qdisc ... dev
6 dev
7 .B  ( parent
8 classid 
9 .B | root) [ handle 
10 major: 
11 .B ] prio [ bands 
12 bands
13 .B ] [ priomap
14 band,band,band... 
15 .B ] [ estimator 
16 interval timeconstant
17 .B ]
19 .SH DESCRIPTION
20 The PRIO qdisc is a simple classful queueing discipline that contains
21 an arbitrary number of classes of differing priority. The classes are
22 dequeued in numerical descending order of priority. PRIO is a scheduler 
23 and never delays packets - it is a work-conserving qdisc, though the qdiscs
24 contained in the classes may not be.
26 Very useful for lowering latency when there is no need for slowing down
27 traffic.
29 .SH ALGORITHM
30 On creation with 'tc qdisc add', a fixed number of bands is created. Each
31 band is a class, although is not possible to add classes with 'tc qdisc
32 add', the number of bands to be created must instead be specified on the
33 commandline attaching PRIO to its root.
35 When dequeueing, band 0 is tried first and only if it did not deliver a
36 packet does PRIO try band 1, and so onwards. Maximum reliability packets
37 should therefore go to band 0, minimum delay to band 1 and the rest to band
40 As the PRIO qdisc itself will have minor number 0, band 0 is actually
41 major:1, band 1 is major:2, etc. For major, substitute the major number
42 assigned to the qdisc on 'tc qdisc add' with the
43 .B handle
44 parameter.
46 .SH CLASSIFICATION
47 Three methods are available to PRIO to determine in which band a packet will
48 be enqueued.
49 .TP
50 From userspace
51 A process with sufficient privileges can encode the destination class
52 directly with SO_PRIORITY, see
53 .BR tc(7).
54 .TP 
55 with a tc filter
56 A tc filter attached to the root qdisc can point traffic directly to a class
57 .TP 
58 with the priomap
59 Based on the packet priority, which in turn is derived from the Type of
60 Service assigned to the packet.
62 Only the priomap is specific to this qdisc. 
63 .SH QDISC PARAMETERS
64 .TP
65 bands
66 Number of bands. If changed from the default of 3,
67 .B priomap
68 must be updated as well.
69 .TP 
70 priomap
71 The priomap maps the priority of
72 a packet to a class. The priority can either be set directly from userspace,
73 or be derived from the Type of Service of the packet.
75 Determines how packet priorities, as assigned by the kernel, map to
76 bands. Mapping occurs based on the TOS octet of the packet, which looks like
77 this:
79 .nf
80 0   1   2   3   4   5   6   7
81 +---+---+---+---+---+---+---+---+
82 |           |               |   |
83 |PRECEDENCE |      TOS      |MBZ|
84 |           |               |   |
85 +---+---+---+---+---+---+---+---+
86 .fi
88 The four TOS bits (the 'TOS field') are defined as:
90 .nf
91 Binary Decimcal  Meaning
92 -----------------------------------------
93 1000   8         Minimize delay (md)
94 0100   4         Maximize throughput (mt)
95 0010   2         Maximize reliability (mr)
96 0001   1         Minimize monetary cost (mmc)
97 0000   0         Normal Service
98 .fi
100 As there is 1 bit to the right of these four bits, the actual value of the
101 TOS field is double the value of the TOS bits. Tcpdump -v -v shows you the
102 value of the entire TOS field, not just the four bits. It is the value you
103 see in the first column of this table:
106 TOS     Bits  Means                    Linux Priority    Band
107 ------------------------------------------------------------
108 0x0     0     Normal Service           0 Best Effort     1
109 0x2     1     Minimize Monetary Cost   1 Filler          2
110 0x4     2     Maximize Reliability     0 Best Effort     1
111 0x6     3     mmc+mr                   0 Best Effort     1
112 0x8     4     Maximize Throughput      2 Bulk            2
113 0xa     5     mmc+mt                   2 Bulk            2
114 0xc     6     mr+mt                    2 Bulk            2
115 0xe     7     mmc+mr+mt                2 Bulk            2
116 0x10    8     Minimize Delay           6 Interactive     0
117 0x12    9     mmc+md                   6 Interactive     0
118 0x14    10    mr+md                    6 Interactive     0
119 0x16    11    mmc+mr+md                6 Interactive     0
120 0x18    12    mt+md                    4 Int. Bulk       1
121 0x1a    13    mmc+mt+md                4 Int. Bulk       1
122 0x1c    14    mr+mt+md                 4 Int. Bulk       1
123 0x1e    15    mmc+mr+mt+md             4 Int. Bulk       1
126 The second column contains the value of the relevant
127 four TOS bits, followed by their translated meaning. For example, 15 stands
128 for a packet wanting Minimal Montetary Cost, Maximum Reliability, Maximum
129 Throughput AND Minimum Delay. 
131 The fourth column lists the way the Linux kernel interprets the TOS bits, by
132 showing to which Priority they are mapped.
134 The last column shows the result of the default priomap. On the commandline,
135 the default priomap looks like this:
137     1, 2, 2, 2, 1, 2, 0, 0 , 1, 1, 1, 1, 1, 1, 1, 1
139 This means that priority 4, for example, gets mapped to band number 1.
140 The priomap also allows you to list higher priorities (> 7) which do not
141 correspond to TOS mappings, but which are set by other means.
143 This table from RFC 1349 (read it for more details) explains how
144 applications might very well set their TOS bits:
147 TELNET                   1000           (minimize delay)
149         Control          1000           (minimize delay)
150         Data             0100           (maximize throughput)
152 TFTP                     1000           (minimize delay)
154 SMTP 
155         Command phase    1000           (minimize delay)
156         DATA phase       0100           (maximize throughput)
158 Domain Name Service
159         UDP Query        1000           (minimize delay)
160         TCP Query        0000
161         Zone Transfer    0100           (maximize throughput)
163 NNTP                     0001           (minimize monetary cost)
165 ICMP
166         Errors           0000
167         Requests         0000 (mostly)
168         Responses        <same as request> (mostly)
172 .SH CLASSES
173 PRIO classes cannot be configured further - they are automatically created
174 when the PRIO qdisc is attached. Each class however can contain yet a
175 further qdisc.
177 .SH BUGS
178 Large amounts of traffic in the lower bands can cause starvation of higher
179 bands. Can be prevented by attaching a shaper (for example, 
180 .BR tc-tbf(8)
181 to these bands to make sure they cannot dominate the link.
183 .SH AUTHORS
184 Alexey N. Kuznetsov, <kuznet@ms2.inr.ac.ru>,  J Hadi Salim
185 <hadi@cyberus.ca>. This manpage maintained by bert hubert <ahu@ds9a.nl>