VMOD-TBF

NAME
SYNOPSIS
DESCRIPTION
DOWNLOADS
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

NAME

vmod-tbf - token bucket filtering for Varnish

SYNOPSIS

import tbf;

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

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

VOID tbf.dump(STRING file);

VOID tbf.dump_at_exit(STRING file);

VOID tbf.load(STRING file);

VOID tbf.gc(DURATION interval);

VOID tbf.set_gc_interval(DURATION interval);

VOID tbf.debug(INT level);

VOID tbf.log_tree(INT prio);

VOID tbf.log_stats(INT prio);

REAL tbf.getla(INT sample);

INT tbf.systime();

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

VOID tbf.sleep(DURATION time);

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:

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

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

Storage
Buckets are kept in a binary tree structure, indexed by the key value. In order to prevent stale data from accumulating in the memory, garbage collection is run periodically. During garbage collection, all buckets that have not been accessed more than predefined amount of time are removed from the tree and disposed of. The default interval is 1 hour. It can be configured using the tbf.set_gc_interval function.

Garbage collection can also be triggered explicitly, using the tbf.gc function with the interval as its argument.

The function tbf.dump dumps entire tree to the disk file. The function tbf.load loads the named dump file into the tree.

The function tbf.dump_at_exit configures the module to dump the tree before varnishd terminates. Use this to keep the tbf state across varnishd restarts. For example:

sub vcl_init {
tbf.load("/var/run/tbf.dump");
tbf.dump_at_exit("/var/run/tbf.dump");
}

Debugging
VOID tbf.debug(INT
level);

Sets the debug verbosity level. Meaningful argument values are 0 (no debugging info) to 2 (maximum verbosity).

VOID tbf.log_tree(INT prio);

Logs the content of the tbf tree to syslog priority prio. Note that this can produce extremely big amounts of info.

VOID tbf.log_stats(INT prio);

Logs the tree statistics to syslog priority prio. The following information is logged: total number of nodes in tree, number of leaves, shortest, longest and average paths.

Other functions
Several functions are provided that do not exactly belong to the TBF algorithm, but which may come useful when implementing rate control.
REAL tbf.getla(INT
sample);

Returns the system load average. The argument identifies interval for which to compute it: 1, 5 or 15 minutes.

INT tbf.systime();

Returns the current time of day as the number of seconds since the Epoch (1970-01-01 00:00:00 UTC).

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

Function formats the timestamp according to the specification in format. See strftime(3), for a description of available formats. For example, the following statement assigns the current year to the X-Year header:

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

VOID tbf.sleep(DURATION time);

Suspends execution for a specified amount of time.

DOWNLOADS

Vmod-tbf is available for download from this location.

The latest version is vmod-tbf-2.6.

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

SEE ALSO

vcl(7), varnishd(1).

AUTHORS

Sergey Poznyakoff

BUG REPORTS

Report bugs to <gray@gnu.org>.

COPYRIGHT

Copyright © 2013-2022 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 man.gnu.org.ua.

Powered by mansrv 1.1