1TC(8)                                Linux                               TC(8)
2
3
4

NAME

6       tbf - Token Bucket Filter
7

SYNOPSIS

9       tc  qdisc ... tbf rate rate burst bytes/cell ( latency ms | limit bytes
10       ) [ mpu bytes [ peakrate rate mtu bytes/cell ] ]
11
12       burst is also known as buffer and maxburst. mtu is also known  as  min‐
13       burst.
14

DESCRIPTION

16       The Token Bucket Filter is a classful queueing discipline available for
17       traffic control with the tc(8) command.
18
19       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.  It is able  to  shape
22       up  to 1mbit/s of normal traffic with ideal minimal burstiness, sending
23       out data exactly at the configured rates.
24
25       Much higher rates are possible but at the cost of  losing  the  minimal
26       burstiness. In that case, data is on average dequeued at the configured
27       rate but may be sent much faster at millisecond timescales. Because  of
28       further queues living in network adaptors, this is often not a problem.
29
30

ALGORITHM

32       As  the  name  implies, traffic is filtered based on the expenditure of
33       tokens.  Tokens roughly correspond to bytes, with the  additional  con‐
34       straint  that  each packet consumes some tokens, no matter how small it
35       is. This reflects the fact that even a zero-sized packet  occupies  the
36       link for some time.
37
38       On  creation,  the  TBF  is stocked with tokens which correspond to the
39       amount of traffic that can be burst in  one  go.  Tokens  arrive  at  a
40       steady rate, until the bucket is full.
41
42       If  no  tokens  are  available,  packets are queued, up to a configured
43       limit. The TBF now calculates the token deficit,  and  throttles  until
44       the first packet in the queue can be sent.
45
46       If  it  is  not  acceptable  to  burst  out packets at maximum speed, a
47       peakrate can be configured to limit the speed at which the bucket  emp‐
48       ties.  This  peakrate  is implemented as a second TBF with a very small
49       bucket, so that it doesn't burst.
50
51       To achieve perfection, the second bucket  may  contain  only  a  single
52       packet, which leads to the earlier mentioned 1mbit/s limit.
53
54       This  limit is caused by the fact that the kernel can only throttle for
55       at minimum 1 'jiffy', which depends on HZ as 1/HZ. For perfect shaping,
56       only  a  single  packet can get sent per jiffy - for HZ=100, this means
57       100 packets of on average 1000 bytes each, which roughly corresponds to
58       1mbit/s.
59
60

PARAMETERS

62       See tc(8) for how to specify the units of these values.
63
64       limit or latency
65              Limit  is  the  number  of  bytes that can be queued waiting for
66              tokens to become available. You can also specify this the  other
67              way around by setting the latency parameter, which specifies the
68              maximum amount of time a packet can sit in the TBF.  The  latter
69              calculation  takes into account the size of the bucket, the rate
70              and possibly the peakrate (if set).  These  two  parameters  are
71              mutually exclusive.
72
73       burst  Also known as buffer or maxburst.  Size of the bucket, in bytes.
74              This is the maximum amount of bytes that tokens can be available
75              for instantaneously.  In general, larger shaping rates require a
76              larger buffer. For 10mbit/s on Intel, you need at least  10kbyte
77              buffer if you want to reach your configured rate!
78
79              If your buffer is too small, packets may be dropped because more
80              tokens arrive per timer tick than fit in your bucket.  The mini‐
81              mum buffer size can be calculated by dividing the rate by HZ.
82
83              Token  usage  calculations  are performed using a table which by
84              default has a resolution of 8 packets.  This resolution  can  be
85              changed by specifying the cell size with the burst. For example,
86              to specify a 6000 byte buffer with a 16 byte cell  size,  set  a
87              burst of 6000/16. You will probably never have to set this. Must
88              be an integral power of 2.
89
90       mpu    A zero-sized packet does not use zero bandwidth.  For  ethernet,
91              no  packet  uses  less  than  64  bytes. The Minimum Packet Unit
92              determines the minimal token usage (specified in  bytes)  for  a
93              packet. Defaults to zero.
94
95       rate   The  speed  knob.  See remarks above about limits! See tc(8) for
96              units.
97
98       Furthermore, if a peakrate is desired,  the  following  parameters  are
99       available:
100
101
102       peakrate
103              Maximum depletion rate of the bucket. The peakrate does not need
104              to be set, it is only necessary if perfect millisecond timescale
105              shaping is required.
106
107
108       mtu/minburst
109              Specifies the size of the peakrate bucket. For perfect accuracy,
110              should be set to the MTU of the interface.   If  a  peakrate  is
111              needed,  but  some  burstiness  is  acceptable, this size can be
112              raised. A 3000 byte minburst allows around 3mbit/s of  peakrate,
113              given 1000 byte packets.
114
115              Like the regular burstsize you can also specify a cell size.
116

EXAMPLE & USAGE

118       To  attach a TBF with a sustained maximum rate of 0.5mbit/s, a peakrate
119       of 1.0mbit/s, a 5kilobyte buffer, with a pre-bucket  queue  size  limit
120       calculated  so  the  TBF  causes  at most 70ms of latency, with perfect
121       peakrate behaviour, issue:
122
123       # tc qdisc add dev eth0 handle 10: root tbf rate 0.5mbit \
124         burst 5kb latency 70ms peakrate 1mbit       \
125         minburst 1540
126
127       To attach an inner qdisc, for example sfq, issue:
128
129       # tc qdisc add dev eth0 parent 10:1 handle 100: sfq
130
131       Without inner qdisc TBF queue acts as bfifo.  If  the  inner  qdisc  is
132       changed the limit/latency is not effective anymore.
133

SEE ALSO

135       tc(8)
136
137

AUTHOR

139       Alexey N. Kuznetsov, <kuznet@ms2.inr.ac.ru>. This manpage maintained by
140       bert hubert <ahu@ds9a.nl>
141
142
143
144iproute2                       13 December 2001                          TC(8)
Impressum