NAME
tbrconfig
—
configure a token bucket regulator for
an output queue
SYNOPSIS
tbrconfig |
interface [tokenrate [bucketsize]] |
tbrconfig |
-d interface |
tbrconfig |
-a |
DESCRIPTION
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.
EXAMPLES
To configure a token bucket regulator for the interface en0 with 10Mbps token rate and 8KB bucket size,
# tbrconfig en0 10M 8K
To rate-limit the interface en0 up to 3Mbps,
# tbrconfig en0 3M auto
SEE ALSO
HISTORY
The tbrconfig
command first appeared in
WIDE/KAME IPv6 protocol stack kit as part of ALTQ tools.