DESCRIPTION

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:

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");

with

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:

Nreq/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.

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

Storage
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:
dbname=NAME

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

truncate or
trunc

Truncate the database if it
already exists.

mode=OCT

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.

sync=N

Synchronize the database with the disk after each
N writes.

debug=N

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 {
tbf.close();
}

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.