$KAME: tbrconfig.8,v 1.2 2001/04/09 16:26:30 thorpej Exp $
Copyright (C) 2000
Sony Computer Science Laboratories Inc. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
.Dd July 25, 2000 .Dt TBRCONFIG 8 .Os
.Sh NAME .Nm tbrconfig .Nd configure a token bucket regulator for an output queue
.Sh SYNOPSIS .Nm .Ar interface .Oo .Ar tokenrate .Op Ar bucketsize .Oc .Nm tbrconfig .Fl d .Ar interface .Nm tbrconfig .Fl a .Sh DESCRIPTION .Nm 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.
p Conceptually, tokens accumulate in a bucket at the average .Ar tokenrate , up to the .Ar 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 .Ar tokenrate limits the average rate, and the .Ar bucketsize limits the maximum burst size.
p 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.
p When the .Ar 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 .Ar 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 .Ar bucketsize is required for a higher .Ar tokenrate .
p The .Ar interface parameter is a string of the form .Dq name unit , for example, .Dq en0 .
p The .Ar tokenrate parameter specifies the average rate in bits per second, and .Dq K or .Dq M can be appended to .Ar tokenrate as a short hand of .Dq Kilo-bps or .Dq Mega-bps , respectively. When .Ar tokenrate is omitted, .Nm displays the current parameter values.
p The .Ar bucketsize parameter specifies the bucket size in bytes, and .Dq K can be appended to .Ar bucketsize as a short hand of .Dq Kilo-bytes . When .Ar bucketsize is omitted, .Nm assumes the regulator is driven by transmission complete interrupts and, using heuristics, assigns a small bucket size according to the .Ar tokenrate . When the keyword .Dq auto is given as .Ar bucketsize , .Nm assumes the regulator is driven by the kernel timer, and computes the bucket size from .Ar tokenrate and the kernel clock frequency.
p If the .Fl d flag is passed before an interface name, .Nm will remove the token bucket regulator for the specified interface.
p Optionally, the .Fl a flag may be used instead of an interface name. This flag instructs .Nm to display information about all interfaces in the system. .Sh EXAMPLES To configure a token bucket regulator for the interface en0 with 10Mbps token rate and 8KB bucket size, d -literal -offset indent # tbrconfig en0 10M 8K .Ed
p To rate-limit the interface en0 up to 3Mbps, d -literal -offset indent # tbrconfig en0 3M auto .Ed .Sh SEE ALSO .Xr altq.conf 5 , .Xr altqd 8 .Sh HISTORY The .Nm command first appeared in WIDE/KAME IPv6 protocol stack kit as part of ALTQ tools.