.\"	$OpenBSD: tbrconfig.8,v 1.3 2001/07/25 10:04:56 mpech 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 KAME
.\"
.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
inteface 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.
.Pp
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.
.Pp
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.
.Pp
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 .
.Pp
The
.Ar interface
parameter is a string of the form
.Dq name unit ,
for example,
.Dq en0 .
.Pp
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.
.Pp
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.
.Pp
If the
.Fl d
flag is passed before an interface name,
.Nm
will remove the token bucket regulator for the specified interface.
.Pp
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,
.Bd -literal -offset
# tbrconfig en0 10M 8K
.Ed
.Pp
To rate-limit the interface en0 up to 3Mbps,
.Bd -literal -offset
# 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.