{ "mode": "man", "parameter": "tc-tbf", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/tc-tbf/8/json", "generated": "2026-10-04T18:40:45Z", "synopsis": "tc qdisc ... tbf rate rate burst bytes/cell ( latency ms | limit bytes ) [ mpu bytes [\npeakrate rate mtu bytes/cell ] ]\nburst is also known as buffer and maxburst. mtu is also known as minburst.", "sections": { "NAME": { "content": "tbf - Token Bucket Filter\n", "subsections": [] }, "SYNOPSIS": { "content": "tc qdisc ... tbf rate rate burst bytes/cell ( latency ms | limit bytes ) [ mpu bytes [\npeakrate rate mtu bytes/cell ] ]\n\nburst is also known as buffer and maxburst. mtu is also known as minburst.\n", "subsections": [] }, "DESCRIPTION": { "content": "The Token Bucket Filter is a classful queueing discipline available for traffic control with\nthe tc(8) command.\n\nTBF is a pure shaper and never schedules traffic. It is non-work-conserving and may throttle\nitself, although packets are available, to ensure that the configured rate is not exceeded.\nIt is able to shape up to 1mbit/s of normal traffic with ideal minimal burstiness, sending\nout data exactly at the configured rates.\n\nMuch higher rates are possible but at the cost of losing the minimal burstiness. In that\ncase, data is on average dequeued at the configured rate but may be sent much faster at mil‐\nlisecond timescales. Because of further queues living in network adaptors, this is often not\na problem.\n\n", "subsections": [] }, "ALGORITHM": { "content": "As the name implies, traffic is filtered based on the expenditure of tokens. Tokens roughly\ncorrespond to bytes, with the additional constraint that each packet consumes some tokens, no\nmatter how small it is. This reflects the fact that even a zero-sized packet occupies the\nlink for some time.\n\nOn creation, the TBF is stocked with tokens which correspond to the amount of traffic that\ncan be burst in one go. Tokens arrive at a steady rate, until the bucket is full.\n\nIf no tokens are available, packets are queued, up to a configured limit. The TBF now calcu‐\nlates the token deficit, and throttles until the first packet in the queue can be sent.\n\nIf it is not acceptable to burst out packets at maximum speed, a peakrate can be configured\nto limit the speed at which the bucket empties. This peakrate is implemented as a second TBF\nwith a very small bucket, so that it doesn't burst.\n\nTo achieve perfection, the second bucket may contain only a single packet, which leads to the\nearlier mentioned 1mbit/s limit.\n\nThis limit is caused by the fact that the kernel can only throttle for at minimum 1 'jiffy',\nwhich depends on HZ as 1/HZ. For perfect shaping, only a single packet can get sent per jiffy\n- for HZ=100, this means 100 packets of on average 1000 bytes each, which roughly corresponds\nto 1mbit/s.\n\n", "subsections": [] }, "PARAMETERS": { "content": "See tc(8) for how to specify the units of these values.\n\nlimit or latency\nLimit is the number of bytes that can be queued waiting for tokens to become avail‐\nable. You can also specify this the other way around by setting the latency parameter,\nwhich specifies the maximum amount of time a packet can sit in the TBF. The latter\ncalculation takes into account the size of the bucket, the rate and possibly the\npeakrate (if set). These two parameters are mutually exclusive.\n\nburst Also known as buffer or maxburst. Size of the bucket, in bytes. This is the maximum\namount of bytes that tokens can be available for instantaneously. In general, larger\nshaping rates require a larger buffer. For 10mbit/s on Intel, you need at least\n10kbyte buffer if you want to reach your configured rate!\n\nIf your buffer is too small, packets may be dropped because more tokens arrive per\ntimer tick than fit in your bucket. The minimum buffer size can be calculated by di‐\nviding the rate by HZ.\n\nToken usage calculations are performed using a table which by default has a resolution\nof 8 packets. This resolution can be changed by specifying the cell size with the\nburst. For example, to specify a 6000 byte buffer with a 16 byte cell size, set a\nburst of 6000/16. You will probably never have to set this. Must be an integral power\nof 2.\n\nmpu A zero-sized packet does not use zero bandwidth. For ethernet, no packet uses less\nthan 64 bytes. The Minimum Packet Unit determines the minimal token usage (specified\nin bytes) for a packet. Defaults to zero.\n\nrate The speed knob. See remarks above about limits! See tc(8) for units.\n\nFurthermore, if a peakrate is desired, the following parameters are available:\n\n\npeakrate\nMaximum depletion rate of the bucket. The peakrate does not need to be set, it is only\nnecessary if perfect millisecond timescale shaping is required.\n\n\nmtu/minburst\nSpecifies the size of the peakrate bucket. For perfect accuracy, should be set to the\nMTU of the interface. If a peakrate is needed, but some burstiness is acceptable,\nthis size can be raised. A 3000 byte minburst allows around 3mbit/s of peakrate, given\n1000 byte packets.\n\nLike the regular burstsize you can also specify a cell size.\n\nEXAMPLE & USAGE\nTo attach a TBF with a sustained maximum rate of 0.5mbit/s, a peakrate of 1.0mbit/s, a 5kilo‐\nbyte buffer, with a pre-bucket queue size limit calculated so the TBF causes at most 70ms of\nlatency, with perfect peakrate behaviour, issue:\n\n# tc qdisc add dev eth0 handle 10: root tbf rate 0.5mbit \\\nburst 5kb latency 70ms peakrate 1mbit \\\nminburst 1540\n\nTo attach an inner qdisc, for example sfq, issue:\n\n# tc qdisc add dev eth0 parent 10:1 handle 100: sfq\n\nWithout inner qdisc TBF queue acts as bfifo. If the inner qdisc is changed the limit/latency\nis not effective anymore.\n", "subsections": [] }, "SEE ALSO": { "content": "tc(8)\n\n", "subsections": [] }, "AUTHOR": { "content": "Alexey N. Kuznetsov, . This manpage maintained by bert hubert\n\n\niproute2 13 December 2001 TC(8)", "subsections": [] } }, "summary": "tbf - Token Bucket Filter", "flags": [], "examples": [], "see_also": [ { "name": "tc", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/tc/8/json" } ] }