TC(8)								       Linux								     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 classless 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.  On all platforms except for Alpha, 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 config-
       ured rate but may be sent much faster at millisecond timescales. Because of further queues living in network adaptors, this is often not  a
       problem.

       Kernels	with a higher 'HZ' can achieve higher rates with perfect burstiness. On Alpha, HZ is ten times higher, leading to a 10mbit/s limit
       to perfection. These calculations hold for packets of on average 1000 bytes.

ALGORITHM

       As the name implies, traffic is filtered based on the expenditure of tokens.  Tokens roughly correspond to bytes, with the additional  con-
       straint 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 shap-
       ing, only a single packet can get sent per jiffy - for HZ=100, this means 100 packets of on average 1000 bytes each, which  roughly  corre-
       sponds 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 calcula-
	      tion  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. Limited to 1mbit/s on Intel, 10mbit/s on Alpha. 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 root tbf rate 0.5mbit 
	 burst 5kb latency 70ms peakrate 1mbit	     
	 minburst 1540

SEE ALSO

       tc(8)

AUTHOR

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

iproute2							 13 December 2001							     TC(8)