TC(8)                  (13 December 2001)                   TC(8)

     NAME
          tbf - Token Bucket Filter

     SYNOPSIS
          tc qdisc ... tbf rate rate burst bytes/cell ( latency ms |
          limit bytes ) [ mpu bytes [ peakrate rate mtu bytes/cell ] ]

          burst is also known as buffer and maxburst. mtu is also
          known as minburst.

     DESCRIPTION
          The Token Bucket Filter is a classful queueing discipline
          available for traffic control with the tc(8) command.

          TBF is a pure shaper and never schedules traffic. It is
          non-work-conserving and may throttle itself, although pack-
          ets are available, to ensure that the configured rate is not
          exceeded.  It is able to shape up to 1mbit/s of normal traf-
          fic with ideal minimal burstiness, sending out data exactly
          at the configured rates.

          Much higher rates are possible but at the cost of losing the
          minimal burstiness. In that case, data is on average
          dequeued at the configured rate but may be sent much faster
          at millisecond timescales. Because of further queues living
          in network adaptors, this is often not a problem.

     ALGORITHM
          As the name implies, traffic is filtered based on the expen-
          diture of tokens. Tokens roughly correspond to bytes, with
          the additional constraint that each packet consumes some
          tokens, no matter how small it is. This reflects the fact
          that even a zero-sized packet occupies the link for some
          time.

          On creation, the TBF is stocked with tokens which correspond
          to the amount of traffic that can be burst in one go. Tokens
          arrive at a steady rate, until the bucket is full.

          If no tokens are available, packets are queued, up to a con-
          figured limit. The TBF now calculates the token deficit, and
          throttles until the first packet in the queue can be sent.

          If it is not acceptable to burst out packets at maximum
          speed, a peakrate can be configured to limit the speed at
          which the bucket empties. This peakrate is implemented as a
          second TBF with a very small bucket, so that it doesn't
          burst.

     Page 1                      iproute2            (printed 5/23/22)

     TC(8)                  (13 December 2001)                   TC(8)

          To achieve perfection, the second bucket may contain only a
          single packet, which leads to the earlier mentioned 1mbit/s
          limit.

          This limit is caused by the fact that the kernel can only
          throttle for at minimum 1 'jiffy', which depends on HZ as
          1/HZ. For perfect shaping, only a single packet can get sent
          per jiffy - for HZ=100, this means 100 packets of on average
          1000 bytes each, which roughly corresponds to 1mbit/s.

     PARAMETERS
          See tc(8) for how to specify the units of these values.

          limit or latency
               Limit is the number of bytes that can be queued waiting
               for tokens to become available. You can also specify
               this the other way around by setting the latency param-
               eter, which specifies the maximum amount of time a
               packet can sit in the TBF. The latter calculation takes
               into account the size of the bucket, the rate and pos-
               sibly the peakrate (if set). These two parameters are
               mutually exclusive.

          burst
               Also known as buffer or maxburst.  Size of the bucket,
               in bytes. This is the maximum amount of bytes that
               tokens can be available for instantaneously.  In gen-
               eral, larger shaping rates require a larger buffer. For
               10mbit/s on Intel, you need at least 10kbyte buffer if
               you want to reach your configured rate!

               If your buffer is too small, packets may be dropped
               because more tokens arrive per timer tick than fit in
               your bucket.  The minimum buffer size can be calculated
               by dividing the rate by HZ.

               Token usage calculations are performed using a table
               which by default has a resolution of 8 packets.  This
               resolution can be changed by specifying the cell size
               with the burst. For example, to specify a 6000 byte
               buffer with a 16 byte cell size, set a burst of
               6000/16. You will probably never have to set this. Must
               be an integral power of 2.

          mpu  A zero-sized packet does not use zero bandwidth. For
               ethernet, no packet uses less than 64 bytes. The Mini-
               mum Packet Unit determines the minimal token usage
               (specified in bytes) for a packet. Defaults to zero.

          rate The speed knob. See remarks above about limits! See
               tc(8) for units.

     Page 2                      iproute2            (printed 5/23/22)

     TC(8)                  (13 December 2001)                   TC(8)

          Furthermore, if a peakrate is desired, the following parame-
          ters are available:

          peakrate
               Maximum depletion rate of the bucket. The peakrate does
               not need to be set, it is only necessary if perfect
               millisecond timescale shaping is required.

          mtu/minburst
               Specifies the size of the peakrate bucket. For perfect
               accuracy, should be set to the MTU of the interface.
               If a peakrate is needed, but some burstiness is accept-
               able, this size can be raised. A 3000 byte minburst
               allows around 3mbit/s of peakrate, given 1000 byte
               packets.

               Like the regular burstsize you can also specify a cell
               size.

     EXAMPLE & USAGE
          To attach a TBF with a sustained maximum rate of 0.5mbit/s,
          a peakrate of 1.0mbit/s, a 5kilobyte buffer, with a pre-
          bucket queue size limit calculated so the TBF causes at most
          70ms of latency, with perfect peakrate behaviour, issue:

          # tc qdisc add dev eth0 handle 10: root tbf rate 0.5mbit \
            burst 5kb latency 70ms peakrate 1mbit       \
            minburst 1540

          To attach an inner qdisc, for example sfq, issue:

          # tc qdisc add dev eth0 parent 10:1 handle 100: sfq

          Without inner qdisc TBF queue acts as bfifo. If the inner
          qdisc is changed the limit/latency is not effective anymore.

     SEE ALSO
          tc(8)

     AUTHOR
          Alexey N. Kuznetsov, <kuznet@ms2.inr.ac.ru>. This manpage
          maintained by bert hubert <ahu@ds9a.nl>

     Page 3                      iproute2            (printed 5/23/22)