tc-tbf.8

   1 .TH TC 8 "13 December 2001" "iproute2" "Linux"
   2 .SH NAME
   3 tbf \- Token Bucket Filter
   4 .SH SYNOPSIS
   5 .B tc qdisc ... tbf rate
   6 rate
   7 .B burst
   8 bytes/cell
   9 .B ( latency
  10 ms
  11 .B | limit
  12 bytes
  13 .B ) [ mpu
  14 bytes
  15 .B [ peakrate
  16 rate
  17 .B mtu
  18 bytes/cell
  19 .B ] ]
  20 .P
  21 burst is also known as buffer and maxburst. mtu is also known as minburst.
  22 .SH DESCRIPTION
  23
  24 The Token Bucket Filter is a classless queueing discipline available for
  25 traffic control with the
  26 .BR tc (8)
  27 command.
  28
  29 TBF is a pure shaper and never schedules traffic. It is non-work-conserving and may throttle
  30 itself, although packets are available, to ensure that the configured rate is not exceeded.
  31 On all platforms except for Alpha,
  32 it is able to shape up to 1mbit/s of normal traffic with ideal minimal burstiness,
  33 sending out  data exactly at the configured rates.
  34
  35 Much higher rates are possible but at the cost of losing the minimal burstiness. In that
  36 case, data is on average dequeued at the configured rate but may be sent much faster at millisecond
  37 timescales. Because of further queues living in network adaptors, this is often not a problem.
  38
  39 Kernels with a higher 'HZ' can achieve higher rates with perfect burstiness. On Alpha, HZ is ten
  40 times higher, leading to a 10mbit/s limit to perfection. These calculations hold for packets of on
  41 average 1000 bytes.
  42
  43 .SH ALGORITHM
  44 As the name implies, traffic is filtered based on the expenditure of
  45 .B tokens.
  46 Tokens roughly correspond to bytes, with the additional constraint that each packet consumes
  47 some tokens, no matter how small it is. This reflects the fact that even a zero-sized packet occupies
  48 the link for some time.
  49
  50 On creation, the TBF is stocked with tokens which correspond to the amount of traffic that can be burst
  51 in one go. Tokens arrive at a steady rate, until the bucket is full.
  52
  53 If no tokens are available, packets are queued, up to a configured limit. The TBF now
  54 calculates the token deficit, and throttles until the first packet in the queue can be sent.
  55
  56 If it is not acceptable to burst out packets at maximum speed, a peakrate can be configured
  57 to limit the speed at which the bucket empties. This peakrate is implemented as a second TBF
  58 with a very small bucket, so that it doesn't burst.
  59
  60 To achieve perfection, the second bucket may contain only a single packet, which leads to
  61 the earlier mentioned 1mbit/s limit.
  62
  63 This limit is caused by the fact that the kernel can only throttle for at minimum 1 'jiffy', which depends
  64 on HZ as 1/HZ. For perfect shaping, only a single packet can get sent per jiffy - for HZ=100, this means 100
  65 packets of on average 1000 bytes each, which roughly corresponds to 1mbit/s.
  66
  67 .SH PARAMETERS
  68 See
  69 .BR tc (8)
  70 for how to specify the units of these values.
  71 .TP
  72 limit or latency
  73 Limit is the number of bytes that can be queued waiting for tokens to become
  74 available. You can also specify this the other way around by setting the
  75 latency parameter, which specifies the maximum amount of time a packet can
  76 sit in the TBF. The latter calculation takes into account the size of the
  77 bucket, the rate and possibly the peakrate (if set). These two parameters
  78 are mutually exclusive.
  79 .TP
  80 burst
  81 Also known as buffer or maxburst.
  82 Size of the bucket, in bytes. This is the maximum amount of bytes that tokens can be available for instantaneously.
  83 In general, larger shaping rates require a larger buffer. For 10mbit/s on Intel, you need at least 10kbyte buffer
  84 if you want to reach your configured rate!
  85
  86 If your buffer is too small, packets may be dropped because more tokens arrive per timer tick than fit in your bucket.
  87 The minimum buffer size can be calculated by dividing the rate by HZ.
  88
  89 Token usage calculations are performed using a table which by default has a resolution of 8 packets.
  90 This resolution can be changed by specifying the
  91 .B cell
  92 size with the burst. For example, to specify a 6000 byte buffer with a 16
  93 byte cell size, set a burst of 6000/16. You will probably never have to set
  94 this. Must be an integral power of 2.
  95 .TP
  96 mpu
  97 A zero-sized packet does not use zero bandwidth. For ethernet, no packet uses less than 64 bytes. The Minimum Packet Unit
  98 determines the minimal token usage (specified in bytes) for a packet. Defaults to zero.
  99 .TP
 100 rate
 101 The speed knob. See remarks above about limits! See
 102 .BR tc (8)
 103 for units.
 104 .PP
 105 Furthermore, if a peakrate is desired, the following parameters are available:
 106
 107 .TP
 108 peakrate
 109 Maximum depletion rate of the bucket. Limited to 1mbit/s on Intel, 10mbit/s on Alpha. The peakrate does
 110 not need to be set, it is only necessary if perfect millisecond timescale shaping is required.
 111
 112 .TP
 113 mtu/minburst
 114 Specifies the size of the peakrate bucket. For perfect accuracy, should be set to the MTU of the interface.
 115 If a peakrate is needed, but some burstiness is acceptable, this size can be raised. A 3000 byte minburst
 116 allows around 3mbit/s of peakrate, given 1000 byte packets.
 117
 118 Like the regular burstsize you can also specify a
 119 .B cell
 120 size.
 121 .SH EXAMPLE & USAGE
 122
 123 To attach a TBF with a sustained maximum rate of 0.5mbit/s, a peakrate of 1.0mbit/s,
 124 a 5kilobyte buffer, with a pre-bucket queue size limit calculated so the TBF causes
 125 at most 70ms of latency, with perfect peakrate behaviour, issue:
 126 .P
 127 # tc qdisc add dev eth0 root tbf rate 0.5mbit \\
 128   burst 5kb latency 70ms peakrate 1mbit       \\
 129   minburst 1540
 130
 131 .SH SEE ALSO
 132 .BR tc (8)
 133
 134 .SH AUTHOR
 135 Alexey N. Kuznetsov, <kuznet@ms2.inr.ac.ru>. This manpage maintained by
 136 bert hubert <ahu@ds9a.nl>
 137
 138