NAME
tbrconfig —
configure a token bucket
regulator for an output queue
SYNOPSIS
tbrconfig |
interface
[tokenrate
[bucketsize]] |
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,
To rate-limit the interface en0 up to 3Mbps,
SEE ALSO
altq.conf(5),
altqd(8)
HISTORY
The
tbrconfig command first appeared in WIDE/KAME IPv6
protocol stack kit as part of ALTQ tools.