usr.sbin/altq/tbrconfig/tbrconfig.8

   1 .\"     $NetBSD: tbrconfig.8,v 1.5 2006/03/08 22:47:40 jmmv 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
  50 configures a token bucket regulator for the output network
  51 interface queue.
  52 A token bucket regulator limits both the average amount and
  53 instantaneous amount of packets that the underlying driver can dequeue
  54 from the network interface within the kernel.
  55 .Pp
  56 Conceptually, tokens accumulate in a bucket at the average
  57 .Ar tokenrate ,
  58 up to the
  59 .Ar bucketsize .
  60 The driver can dequeue packets as long as there are positive amount
  61 of tokens, and the length of the dequeued packet is subtracted from
  62 the remaining tokens.  Tokens can be negative as a deficit, and
  63 packets are not dequeued from the interface queue until the tokens
  64 become positive again.
  65 The
  66 .Ar tokenrate
  67 limits the average rate, and the
  68 .Ar bucketsize
  69 limits the maximum burst size.
  70 .Pp
  71 Limiting the burst size is essential to packet scheduling, since the
  72 scheduler schedules packets backlogged at the network interface.
  73 Limiting the burst size is also needed for drivers which dequeues more
  74 packets than they can send and end up with discarding excess packets.
  75 .Pp
  76 When the
  77 .Ar tokenrate
  78 is set to higher than the actual transmission rate, the transmission
  79 complete interrupt will trigger the next dequeue.
  80 On the other hand, when the
  81 .Ar tokenrate
  82 is set to lower than the actual transmission rate, the transmission
  83 complete interrupt would occur before the tokens become positive.
  84 In this case, the next dequeue will be triggered by a timer event.
  85 Because the kernel timer has a limited granularity, a larger
  86 .Ar bucketsize
  87 is required for a higher
  88 .Ar tokenrate .
  89 .Pp
  90 The
  91 .Ar interface
  92 parameter is a string of the form
  93 .Dq name unit ,
  94 for example,
  95 .Dq en0 .
  96 .Pp
  97 The
  98 .Ar tokenrate
  99 parameter specifies the average rate in bits per second, and
 100 .Dq K
 101 or
 102 .Dq M
 103 can be appended to
 104 .Ar tokenrate
 105 as a short hand of
 106 .Dq Kilo-bps
 107 or
 108 .Dq Mega-bps ,
 109 respectively.
 110 When
 111 .Ar tokenrate
 112 is omitted,
 113 .Nm
 114 displays the current parameter values.
 115 .Pp
 116 The
 117 .Ar bucketsize
 118 parameter specifies the bucket size in bytes, and
 119 .Dq K
 120 can be appended to
 121 .Ar bucketsize
 122 as a short hand of
 123 .Dq Kilo-bytes .
 124 When
 125 .Ar bucketsize
 126 is omitted,
 127 .Nm
 128 assumes the regulator is driven by transmission complete interrupts
 129 and, using heuristics, assigns a small bucket size according to the
 130 .Ar tokenrate .
 131 When the keyword
 132 .Dq auto
 133 is given as
 134 .Ar bucketsize ,
 135 .Nm
 136 assumes the regulator is driven by the kernel timer, and
 137 computes the bucket size from
 138 .Ar tokenrate
 139 and the kernel clock frequency.
 140 .Pp
 141 If the
 142 .Fl d
 143 flag is passed before an interface name,
 144 .Nm
 145 will remove the token bucket regulator for the specified interface.
 146 .Pp
 147 Optionally, the
 148 .Fl a
 149 flag may be used instead of an interface name.  This flag instructs
 150 .Nm
 151 to display information about all interfaces in the system.
 152 .Sh EXAMPLES
 153 To configure a token bucket regulator for the interface en0 with
 154 10Mbps token rate and 8KB bucket size,
 155 .Bd -literal -offset indent
 156 # tbrconfig en0 10M 8K
 157 .Ed
 158 .Pp
 159 To rate-limit the interface en0 up to 3Mbps,
 160 .Bd -literal -offset indent
 161 # tbrconfig en0 3M auto
 162 .Ed
 163 .Sh SEE ALSO
 164 .Xr altq.conf 5 ,
 165 .Xr altqd 8
 166 .Sh HISTORY
 167 The
 168 .Nm
 169 command first appeared in WIDE/KAME IPv6 protocol stack kit as part of
 170 ALTQ tools.