1.\" $NetBSD: tbrconfig.8,v 1.4 2001/08/16 07:45:40 itojun Exp $ 2.\" $KAME: tbrconfig.8,v 1.2 2001/04/09 16:26:30 thorpej Exp $ 3.\" 4.\" Copyright (C) 2000 5.\" Sony Computer Science Laboratories Inc. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd July 25, 2000 29.Dt TBRCONFIG 8 30.Os 31.\" 32.Sh NAME 33.Nm tbrconfig 34.Nd configure a token bucket regulator for an output queue 35.\" 36.Sh SYNOPSIS 37.Nm 38.Ar interface 39.Oo 40.Ar tokenrate 41.Op Ar bucketsize 42.Oc 43.Nm tbrconfig 44.Fl d 45.Ar interface 46.Nm tbrconfig 47.Fl a 48.Sh DESCRIPTION 49.Nm 50configures a token bucket regulator for the output network 51inteface queue. 52A token bucket regulator limits both the average amount and 53instantaneous amount of packets that the underlying driver can dequeue 54from the network interface within the kernel. 55.Pp 56Conceptually, tokens accumulate in a bucket at the average 57.Ar tokenrate , 58up to the 59.Ar bucketsize . 60The driver can dequeue packets as long as there are positive amount 61of tokens, and the length of the dequeued packet is subtracted from 62the remaining tokens. Tokens can be negative as a deficit, and 63packets are not dequeued from the interface queue until the tokens 64become positive again. 65The 66.Ar tokenrate 67limits the average rate, and the 68.Ar bucketsize 69limits the maximum burst size. 70.Pp 71Limiting the burst size is essential to packet scheduling, since the 72scheduler schedules packets backlogged at the network interface. 73Limiting the burst size is also needed for drivers which dequeues more 74packets than they can send and end up with discarding excess packets. 75.Pp 76When the 77.Ar tokenrate 78is set to higher than the actual transmission rate, the transmission 79complete interrupt will trigger the next dequeue. 80On the other hand, when the 81.Ar tokenrate 82is set to lower than the actual transmission rate, the transmission 83complete interrupt would occur before the tokens become positive. 84In this case, the next dequeue will be triggered by a timer event. 85Because the kernel timer has a limited granularity, a larger 86.Ar bucketsize 87is required for a higher 88.Ar tokenrate . 89.Pp 90The 91.Ar interface 92parameter is a string of the form 93.Dq name unit , 94for example, 95.Dq en0 . 96.Pp 97The 98.Ar tokenrate 99parameter specifies the average rate in bits per second, and 100.Dq K 101or 102.Dq M 103can be appended to 104.Ar tokenrate 105as a short hand of 106.Dq Kilo-bps 107or 108.Dq Mega-bps , 109respectively. 110When 111.Ar tokenrate 112is omitted, 113.Nm 114displays the current parameter values. 115.Pp 116The 117.Ar bucketsize 118parameter specifies the bucket size in bytes, and 119.Dq K 120can be appended to 121.Ar bucketsize 122as a short hand of 123.Dq Kilo-bytes . 124When 125.Ar bucketsize 126is omitted, 127.Nm 128assumes the regulator is driven by transmission complete interrupts 129and, using heuristics, assigns a small bucket size according to the 130.Ar tokenrate . 131When the keyword 132.Dq auto 133is given as 134.Ar bucketsize , 135.Nm 136assumes the regulator is driven by the kernel timer, and 137computes the bucket size from 138.Ar tokenrate 139and the kernel clock frequency. 140.Pp 141If the 142.Fl d 143flag is passed before an interface name, 144.Nm 145will remove the token bucket regulator for the specified interface. 146.Pp 147Optionally, the 148.Fl a 149flag may be used instead of an interface name. This flag instructs 150.Nm 151to display information about all interfaces in the system. 152.Sh EXAMPLES 153To configure a token bucket regulator for the interface en0 with 15410Mbps token rate and 8KB bucket size, 155.Bd -literal -offset 156# tbrconfig en0 10M 8K 157.Ed 158.Pp 159To rate-limit the interface en0 up to 3Mbps, 160.Bd -literal -offset 161# tbrconfig en0 3M auto 162.Ed 163.Sh SEE ALSO 164.Xr altq.conf 5 , 165.Xr altqd 8 166.Sh HISTORY 167The 168.Nm 169command first appeared in WIDE/KAME IPv6 protocol stack kit as part of 170ALTQ tools. 171