Home | History | Annotate | Line # | Download | only in tbrconfig 
 $NetBSD: tbrconfig.8,v 1.6 2009/04/08 13:37:43 joerg Exp $
 $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.