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 packets are available, to ensure that the configured rate is not exceeded.  It is able to  shape
       up to 1mbit/s of normal traffic 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 expenditure 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 configured 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.

       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  parameter,  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 possibly 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 general, 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  Minimum  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.

       Furthermore, if a peakrate is desired, the following parameters 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 acceptable, 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>