GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
VMOD_VSTHROTTLE(3) VMOD_VSTHROTTLE(3)

vmod_vsthrottle - Throttling VMOD

import vsthrottle [from "path"] ;

A Varnish vmod for rate-limiting traffic on a single Varnish server. Offers a simple interface for throttling traffic on a per-key basis to a specific request rate.
Keys can be specified from any VCL string, e.g. based on client.ip, a specific cookie value, an API token, etc.
The request rate is specified as the number of requests permitted over a period. To keep things simple, this is passed as two separate parameters, 'limit' and 'period'.
This VMOD implements a token bucket algorithm. State associated with the token bucket for each key is stored in-memory using BSD's red-black tree implementation.
Memory usage is around 100 bytes per key tracked.
Example:
vcl 4.0;
import vsthrottle;
backend default { .host = "192.0.2.11"; .port = "8080"; }
sub vcl_recv { # Varnish will set client.identity for you based on client IP.
if (vsthrottle.is_denied(client.identity, 15, 10s)) { # Client has exceeded 15 reqs per 10s return (synth(429, "Too Many Requests")); }
# There is a quota per API key that must be fulfilled. if (vsthrottle.is_denied("apikey:" + req.http.Key, 30, 60s)) { return (synth(429, "Too Many Requests")); }
# Only allow a few POST/PUTs per client. if (req.method == "POST" || req.method == "PUT") { if (vsthrottle.is_denied("rw" + client.identity, 2, 10s)) { return (synth(429, "Too Many Requests")); } } }


BOOL is_denied(STRING, INT, DURATION)
INT remaining(STRING, INT, DURATION)

Prototype
BOOL is_denied(STRING key, INT limit, DURATION period)

Arguments:
key: A unique identifier to define what is being throttled - more examples below
limit: How many requests in the specified period
period: The time period



Description
Can be used to rate limit the traffic for a specific key to a maximum of 'limit' requests per 'period' time. A token bucket is uniquely identified by the triplet of its key, limit and period, so using the same key multiple places with different rules will create multiple token buckets.
Example
sub vcl_recv {
        if (vsthrottle.is_denied(client.identity, 15, 10s)) {
                # Client has exceeded 15 reqs per 10s
                return (synth(429, "Too Many Requests"));
        }
# ... }



Prototype
INT remaining(STRING key, INT limit, DURATION period)
Arguments:
key: A unique identifier to define what is being throttled
limit: How many requests in the specified period
period: The time period


Description
Get the current number of tokens for a given token bucket. This can be used to create a response header to inform clients of their current quota.


Example
sub vcl_deliver {
   set resp.http.X-RateLimit-Remaining = vsthrottle.remaining(client.identity, 15, 10s);
}




Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.