tbrconfig configures a token bucket regulator for the output network interface queue. A token bucket regulator limits both the average amount and instantaneous amount of packets that the underlying driver can dequeue from the network interface within the kernel.
Conceptually, tokens accumulate in a bucket at the average
tokenrate, up to the
bucketsize. The driver can dequeue packets as long as there are positive amount of tokens, and the length of the dequeued packet is subtracted from the remaining tokens. Tokens can be negative as a deficit, and packets are not dequeued from the interface queue until the tokens become positive again. The
tokenrate limits the average rate, and the
bucketsize limits the maximum burst size.
Limiting the burst size is essential to packet scheduling, since the scheduler schedules packets backlogged at the network interface. Limiting the burst size is also needed for drivers which dequeues more packets than they can send and end up with discarding excess packets.
When the
tokenrate is set to higher than the actual transmission rate, the transmission complete interrupt will trigger the next dequeue. On the other hand, when the
tokenrate is set to lower than the actual transmission rate, the transmission complete interrupt would occur before the tokens become positive. In this case, the next dequeue will be triggered by a timer event. Because the kernel timer has a limited granularity, a larger
bucketsize is required for a higher
tokenrate.
The
interface parameter is a string of the form “name unit”, for example, “en0”.
The
tokenrate parameter specifies the average rate in bits per second, and “K” or “M” can be appended to
tokenrate as a short hand of “Kilo-bps” or “Mega-bps”, respectively. When
tokenrate is omitted,
tbrconfig displays the current parameter values.
The
bucketsize parameter specifies the bucket size in bytes, and “K” can be appended to
bucketsize as a short hand of “Kilo-bytes”. When
bucketsize is omitted,
tbrconfig assumes the regulator is driven by transmission complete interrupts and, using heuristics, assigns a small bucket size according to the
tokenrate. When the keyword “auto” is given as
bucketsize,
tbrconfig assumes the regulator is driven by the kernel timer, and computes the bucket size from
tokenrate and the kernel clock frequency.
If the
-d flag is passed before an interface name,
tbrconfig will remove the token bucket regulator for the specified interface.
Optionally, the
-a flag may be used instead of an interface name. This flag instructs
tbrconfig to display information about all interfaces in the system.