171 lines
4.8 KiB
Groff
171 lines
4.8 KiB
Groff
.\" $NetBSD: tbrconfig.8,v 1.5 2006/03/08 22:47:40 jmmv 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.
|
|
.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.
|