1TC(8) Linux TC(8)
2
6 tbf - Token Bucket Filter
7
9 tc qdisc ... tbf rate rate burst bytes/cell ( latency ms | limit bytes
10 ) [ mpu bytes [ peakrate rate mtu bytes/cell ] ]
11 burst is also known as buffer and maxburst. mtu is also known as min‐
13 burst.
14
16 The Token Bucket Filter is a classless queueing discipline available
17 for traffic control with the tc(8) command.
18 TBF is a pure shaper and never schedules traffic. It is non-work-con‐
20 serving and may throttle itself, although packets are available, to
21 ensure that the configured rate is not exceeded. On all platforms
22 except for Alpha, it is able to shape up to 1mbit/s of normal traffic
23 with ideal minimal burstiness, sending out data exactly at the config‐
24 ured rates.
25 Much higher rates are possible but at the cost of losing the minimal
27 burstiness. In that case, data is on average dequeued at the configured
28 rate but may be sent much faster at millisecond timescales. Because of
29 further queues living in network adaptors, this is often not a problem.
30 Kernels with a higher 'HZ' can achieve higher rates with perfect
32 burstiness. On Alpha, HZ is ten times higher, leading to a 10mbit/s
33 limit to perfection. These calculations hold for packets of on average
34 1000 bytes.
35
38 As the name implies, traffic is filtered based on the expenditure of
39 tokens. Tokens roughly correspond to bytes, with the additional con‐
40 straint that each packet consumes some tokens, no matter how small it
41 is. This reflects the fact that even a zero-sized packet occupies the
42 link for some time.
43 On creation, the TBF is stocked with tokens which correspond to the
45 amount of traffic that can be burst in one go. Tokens arrive at a
46 steady rate, until the bucket is full.
47 If no tokens are available, packets are queued, up to a configured
49 limit. The TBF now calculates the token deficit, and throttles until
50 the first packet in the queue can be sent.
51 If it is not acceptable to burst out packets at maximum speed, a
53 peakrate can be configured to limit the speed at which the bucket emp‐
54 ties. This peakrate is implemented as a second TBF with a very small
55 bucket, so that it doesn't burst.
56 To achieve perfection, the second bucket may contain only a single
58 packet, which leads to the earlier mentioned 1mbit/s limit.
59 This limit is caused by the fact that the kernel can only throttle for
61 at minimum 1 'jiffy', which depends on HZ as 1/HZ. For perfect shaping,
62 only a single packet can get sent per jiffy - for HZ=100, this means
63 100 packets of on average 1000 bytes each, which roughly corresponds to
64 1mbit/s.
65
68 See tc(8) for how to specify the units of these values.
69 limit or latency
71 Limit is the number of bytes that can be queued waiting for
72 tokens to become available. You can also specify this the other
73 way around by setting the latency parameter, which specifies the
74 maximum amount of time a packet can sit in the TBF. The latter
75 calculation takes into account the size of the bucket, the rate
76 and possibly the peakrate (if set). These two parameters are
77 mutually exclusive.
78 burst Also known as buffer or maxburst. Size of the bucket, in bytes.
80 This is the maximum amount of bytes that tokens can be available
81 for instantaneously. In general, larger shaping rates require a
82 larger buffer. For 10mbit/s on Intel, you need at least 10kbyte
83 buffer if you want to reach your configured rate!
84 If your buffer is too small, packets may be dropped because more
86 tokens arrive per timer tick than fit in your bucket. The mini‐
87 mum buffer size can be calculated by dividing the rate by HZ.
88 Token usage calculations are performed using a table which by
90 default has a resolution of 8 packets. This resolution can be
91 changed by specifying the cell size with the burst. For example,
92 to specify a 6000 byte buffer with a 16 byte cell size, set a
93 burst of 6000/16. You will probably never have to set this. Must
94 be an integral power of 2.
95 mpu A zero-sized packet does not use zero bandwidth. For ethernet,
97 no packet uses less than 64 bytes. The Minimum Packet Unit
98 determines the minimal token usage (specified in bytes) for a
99 packet. Defaults to zero.
100 rate The speed knob. See remarks above about limits! See tc(8) for
102 units.
103 Furthermore, if a peakrate is desired, the following parameters are
105 available:
106 peakrate
109 Maximum depletion rate of the bucket. Limited to 1mbit/s on
110 Intel, 10mbit/s on Alpha. The peakrate does not need to be set,
111 it is only necessary if perfect millisecond timescale shaping is
112 required.
113 mtu/minburst
116 Specifies the size of the peakrate bucket. For perfect accuracy,
117 should be set to the MTU of the interface. If a peakrate is
118 needed, but some burstiness is acceptable, this size can be
119 raised. A 3000 byte minburst allows around 3mbit/s of peakrate,
120 given 1000 byte packets.
121 Like the regular burstsize you can also specify a cell size.
123
125 To attach a TBF with a sustained maximum rate of 0.5mbit/s, a peakrate
126 of 1.0mbit/s, a 5kilobyte buffer, with a pre-bucket queue size limit
127 calculated so the TBF causes at most 70ms of latency, with perfect
128 peakrate behaviour, issue:
129 # tc qdisc add dev eth0 root tbf rate 0.5mbit \
131 burst 5kb latency 70ms peakrate 1mbit \
132 minburst 1540
133
136 tc(8)
137
140 Alexey N. Kuznetsov, <kuznet@ms2.inr.ac.ru>. This manpage maintained by
141 bert hubert <ahu@ds9a.nl>
142iproute2 13 December 2001 TC(8)