# tc-tbf

## 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.
    


* * *