From the manpage, the only constraint on burst
is that it must be high enough to allow your configured rate: it must be at least rate / HZ. HZ is a kernel configuration parameter; you can figure out what it is on your system by checking your kernel config. E.g., on Debian, you can:
$ egrep '^CONFIG_HZ_[0-9]+' /boot/config-`uname -r`
CONFIG_HZ_250=y
so HZ on my system is 250. To hit a rate of 10mbps, I'd thus need a burst
of at least 10,000,000 bits/sec ÷ 250 Hz = 40,000 bits = 5000 bytes. (Note the higher value in the manpage is from when HZ=100 was the default).
But beyond this, burst
is also a policy tool. It configures the extent to which you can use less bandwidth now to "save" it for future use. One common thing here is that you may want to allow small downloads (say, a web page) to go very fast, while throttling big downloads. You do this by increasing burst
to the size you consider a small download. (Though, you'd often switch to a classfull qdisc like htb, so you can segment out the different traffic types.)
So: you configure burst to be at least large enough to achieve the desired rate
. Beyond that, you may increase it further, depending on what you're trying to achieve.
Conceptual Model of a Token Bucket Filter
A "bucket" is a metaphorical object. Its key properties are that it can hold tokens, and that the number of tokens it can hold is limited—if you attempt to add more, it "overflows" and the extra tokens are lost (just like trying to put too much water in an actual bucket). The size of the bucket is called burst
.
In order to actually transmit a packet onto the network, that packet must obtain tokens equal to its size in bytes or mpu
(whichever is larger).
There is (or can be) a line (queue) of packets waiting for tokens. This occurs when the bucket is empty, or alternatively has fewer tokens than the size of the packet. There is only so much room on the sidewalk in front of the bucket, and the amount of room (in bytes) is set directly by limit
. Alternatively, it can be set indirectly with latency
(in an ideal world, the calculation would be rate
×latency
).
When the kernel wants to send a packet out the filtered interface, it attempts to place the packet at the end of the line. If there isn't any room on the sidewalk, that's unfortunate for the packet, because at the end of the sidewalk is a bottomless pit, and the kernel drops the packet.
The final piece is a token-making machine that adds rate
/HZ
tokens to the bucket every tick. (This is why your bucket must be at least this large, otherwise some of the newly-minted tokens will be immediately discarded).