Penguin
Recent Changes
Annotated edit history of tc-tbf(8) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 TC
2 !!!TC
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 ALGORITHM
7 PARAMETERS
8 EXAMPLE
9 SEE ALSO
10 AUTHOR
11 ----
12 !!NAME
13
14
15 tbf - Token Bucket Filter
16 !!SYNOPSIS
17
18
19 __tc qdisc ... tbf rate__ rate __burst__ bytes/cell
20 __( latency__ ms __| limit__ bytes __) [[ mpu__
21 bytes __[[ peakrate__ rate __mtu__ bytes/cell __]
22 ]__
23
24
25 burst is also known as buffer and maxburst. mtu is also
26 known as minburst.
27 !!DESCRIPTION
28
29
30 The Token Bucket Filter is a classless queueing discipline
31 available for traffic control with the tc(8)
32 command.
33
34
35 TBF is a pure shaper and never schedules traffic. It is
36 non-work-conserving and may throttle itself, although
37 packets are available, to ensure that the configured rate is
38 not exceeded. On all platforms except for Alpha, it is able
39 to shape up to 1mbit/s of normal traffic with ideal minimal
40 burstiness, sending out data exactly at the configured
41 rates.
42
43
44 Much higher rates are possible but at the cost of losing the
45 minimal burstiness. In that case, data is on average
46 dequeued at the configured rate but may be sent much faster
47 at millisecond timescales. Because of further queues living
48 in network adaptors, this is often not a
49 problem.
50
51
52 Kernels with a higher 'HZ' can achieve higher rates with
53 perfect burstiness. On Alpha, HZ is ten times higher,
54 leading to a 10mbit/s limit to perfection. These
55 calculations hold for packets of on average 1000
56 bytes.
57 !!ALGORITHM
58
59
60 As the name implies, traffic is filtered based on the
61 expenditure of __tokens.__ Tokens roughly correspond to
62 bytes, with the additional constraint that each packet
63 consumes some tokens, no matter how small it is. This
64 reflects the fact that even a zero-sized packet occupies the
65 link for some time.
66
67
68 On creation, the TBF is stocked with tokens which correspond
69 to the amount of traffic that can be burst in one go. Tokens
70 arrive at a steady rate, until the bucket is
71 full.
72
73
74 If no tokens are available, packets are queued, up to a
75 configured limit. The TBF now calculates the token deficit,
76 and throttles until the first packet in the queue can be
77 sent.
78
79
80 If it is not acceptable to burst out packets at maximum
81 speed, a peakrate can be configured to limit the speed at
82 which the bucket empties. This peakrate is implemented as a
83 second TBF with a very small bucket, so that it doesn't
84 burst.
85
86
87 To achieve perfection, the second bucket may contain only a
88 single packet, which leads to the earlier mentioned 1mbit/s
89 limit.
90
91
92 This limit is caused by the fact that the kernel can only
93 throttle for at minimum 1 'jiffy', which depends on HZ as
94 1/HZ. For perfect shaping, only a single packet can get sent
95 per jiffy - for HZ=100, this means 100 packets of on average
96 1000 bytes each, which roughly corresponds to
97 1mbit/s.
98 !!PARAMETERS
99
100
101 See tc(8) for how to specify the units of these
102 values.
103
104
105 limit or latency
106
107
108 Limit is the number of bytes that can be queued waiting for
109 tokens to become available. You can also specify this the
110 other way around by setting the latency parameter, which
111 specifies the maximum amount of time a packet can sit in the
112 TBF. The latter calculation takes into account the size of
113 the bucket, the rate and possibly the peakrate (if set).
114 These two parameters are mutually exclusive.
115
116
117 burst
118
119
120 Also known as buffer or maxburst. Size of the bucket, in
121 bytes. This is the maximum amount of bytes that tokens can
122 be available for instantaneously. In general, larger shaping
123 rates require a larger buffer. For 10mbit/s on Intel, you
124 need at least 10kbyte buffer if you want to reach your
125 configured rate!
126
127
128 If your buffer is too small, packets may be dropped because
129 more tokens arrive per timer tick than fit in your bucket.
130 The minimum buffer size can be calculated by dividing the
131 rate by HZ.
132
133
134 Token usage calculations are performed using a table which
135 by default has a resolution of 8 packets. This resolution
136 can be changed by specifying the __cell__ size with the
137 burst. For example, to specify a 6000 byte buffer with a 16
138 byte cell size, set a burst of 6000/16. You will probably
139 never have to set this. Must be an integral power of
140 2.
141
142
143 mpu
144
145
146 A zero-sized packet does not use zero bandwidth. For
147 ethernet, no packet uses less than 64 bytes. The Minimum
148 Packet Unit determines the minimal token usage (specified in
149 bytes) for a packet. Defaults to zero.
150
151
152 rate
153
154
155 The speed knob. See remarks above about limits! See
156 tc(8) for units.
157
158
159 Furthermore, if a peakrate is desired, the following
160 parameters are available:
161
162
163 peakrate
164
165
166 Maximum depletion rate of the bucket. Limited to 1mbit/s on
167 Intel, 10mbit/s on Alpha. The peakrate does not need to be
168 set, it is only necessary if perfect millisecond timescale
169 shaping is required.
170
171
172 mtu/minburst
173
174
175 Specifies the size of the peakrate bucket. For perfect
176 accuracy, should be set to the MTU of the interface. If a
177 peakrate is needed, but some burstiness is acceptable, this
178 size can be raised. A 3000 byte minburst allows around
179 3mbit/s of peakrate, given 1000 byte packets.
180
181
182 Like the regular burstsize you can also specify a
183 __cell__ size.
184 !!EXAMPLE !!
185
186
187 To attach a TBF with a sustained maximum rate of 0.5mbit/s,
188 a peakrate of 1.0mbit/s, a 5kilobyte buffer, with a
189 pre-bucket queue size limit calculated so the TBF causes at
190 most 70ms of latency, with perfect peakrate behaviour,
191 issue:
192
193
194 # tc qdisc add dev eth0 root tbf rate 0.5mbit \ burst 5kb
195 latency 70ms peakrate 1mbit \ minburst 1540
196 !!SEE ALSO
197
198
199 tc(8)
200 !!AUTHOR
201
202
203 Alexey N. Kuznetsov,
204 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.