vmod-tbf − token bucket filtering for Varnish


import tbf;

VOID tbf.open(STRING dbdir, STRING params);

VOID tbf.close();

BOOL tbf.rate(STRING key, INT COST, DURATION interval, INT burst_size);

BOOL tbf.check(STRING key, STRING rate);

REAL tbf.getla(INT sample);

INT tbf.systime();

STRING tbf.strftime(STRING format, INT timestamp);

VOID tbf.sleep(DURATION time);


The vmod-tbf module implements token bucket filtering for Varnish Cache. It also implements several unrelated functions.

Rate control functions
In this implementation of the token bucket algorithm, each bucket is associated with a key (a string value uniquely identifying this bucket). The algorithm works as follows:

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 the 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 function tbf.rate provides 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");

This example will keep the incoming requests at the rate of 10 requests per second, allowing for bursts of up to 20 requests after each 2 second (or longer) period of inactivity.

For VCL 4.0, replace

        error(429, "Request rate exceeded");


        return(synth(429, "Request rate exceeded"));

The tbf.check function provides a higher-level interface. Its first argument identifies the bucket. The rate argument is a textual rate specification in the form:


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.

For example, the following statement will limit the request rate to ten and a half requests per second:

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

Buckets are kept in a Berkeley database file. The tbf.open function controls its location and permissions. The dbdir argument supplies the full pathname to the directory where the database is located. The params argument is a semicolon separated list of the following parameters:

Sets the name of the database file. Default is tbf.bdb.

truncate or trunc

Truncate the database if it already exists.


Set the file mode. OCT is an octal number. The default file mode is 640. Note that this parameter takes effect only when creating the file. If the database file already exists by the time tbf.open is called, its mode will not be altered.


Synchronize the database with the disk after each N writes.


Set debugging level.

Normally, this function should be called only once, from the vcl_init subroutine:

sub vcl_init {
    tbf.open("/var/run/varnish/tbf.db", "mode=600");

Note that the directory where the database file is located must be writable for the user Varnish runs as.

Unless the tbf.open function was called, both tbf.rate and tbf.check will attempt to use the database located in localstatedir/vmod-tbf, where localstatedir is the directory for modifiable single-machine data, which is set when configuring the package (e.g. /var/run or the like).

If the database directory does not exist, tbf.open will attempt to create it, deducing its mode from the database file mode (see the mode= parameter above) by setting executable bit in each triplet that has read or write bit set (e.g. 640 will become 750).

The tbf.close function flushes the data and closes the database. It is normally called from the vcl_fini subroutine:

sub vcl_fini {

Other functions
Several functions are provided that do not exactly belong to the TBF algorithm, but which may come useful when implementing rate control.

The tbf.getla function returns the system load average. Its argument identifies the interval for which to compute it: 1, 5 or 15 minutes.

The tbf.systime function returns the current time of day as the number of seconds since the Epoch (1970-01-01 00:00:00 UTC).

The tbf.strftime function formats the timestamp according to the specification in format. See strftime(3), for a description of available formats. For example, the following statements assigns the current year to the X−Year header:

set req.http.X-Year = tbf.strftime("%Y", systime());

The tbf.sleep function suspends execution for a specified amount of time.


Vmod-tbf is available for download from this location.

The latest version is vmod-tbf-2.1.

Recent news, changes and bugfixes can be tracked from the project's development page.


vcl(7), varnishd(1).


Sergey Poznyakoff


Report bugs to <gray@gnu.org>.


Copyright © 2013-2014 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at Ulysses.gnu.org.ua.

Powered by mansrv 1.0