tbf - Token Bucket Filtering

Implements token bucket filtering for Varnish Cache.   The module is intended as a means of controlling request rate.  The algorithm works as follows.

  • Each bucket is associated with a key (a string value uniquely identifying this bucket).
  • A token is added to the bucket at a constant rate of 1 token per interval microseconds.
  • A bucket can hold at most burst_size tokens. Any tokens arriving when the bucket is full are discarded.
  • When cost items of data arrive, cost tokens are removed from the bucket and the data are accepted.
  • If fewer than cost tokens are available, no tokens are removed from the bucket and he data are not accepted.

This keeps the data traffic at a constant rate or cost items per interval microseconds with bursts of up to burst_size items. Such bursts occur when no data was being arrived for burst_size*interval or more microseconds.

The module provides two main entry points:

bool tbf.rate(string key, int cost, duration interval, int burst_size);

A low-level interface to this algorithm. Its arguments correspond exactly to the values used in the above description. The key argument identifies the bucket. The function returns TRUE if the data are accepted and FALSE otherwise. The sample usage is:

sub vcl_recv {
        if (!tbf.rate("ip:" + client.ip, 1, 0.1s, 20)) {
                error(429, "Request rate exceeded");

tbf.check(string key, string rate);

This function provides a higher-level interface. Its first argument identifies the bucket. The second argument is a textual rate specification in the form: N req/ KU, where N and K are floating-point numbers, and U is an optional unit specifier: s, m, h or d for seconds, minutes, hours or days, correspondingly. The parts of the rate specification can be separated by any amount of whitespace. Thus, 100req/1s stands for one hundred requests per second. The sample usage:

sub vcl_recv {
        if (!tbf.check(client.ip, "10.5 req/1s")) {
                error(429, "Request rate exceeded");

The buckets are kept in a Berkeley database file, so that statistics information persists accross restarts. Additional functions are provided for configuring the database.

A detailed documentation is available online.

Pointers to file download, source repository and further development news are available from the module development page.

This module is free software and is available under the terms of GNU General Public License version 3 or (at your option) any later version.

Used in production
Berkeley DB
Varnish version supported: 
Commercial support: 
NXC International