1. Home
2. Reference documentation
3. VCL reference
4. Functions
5. Rate limiting

Available inall subroutines.

Add a user to a penalty box for some duration of time.

For rate limiting purposes, consider using the ratelimit.check_rate and ratelimit.check_rates functions instead, which correctly handle the necessary details.

Parameters

pb - The penalty box.

entry - The entry to keep track of. Typically client.ip, and any associated metadata. An entry can be, at maximum, 256 bytes long.

ttl - The penalty box TTL. Specifies how long a user remains penalized. Must be between 1m and 1h, and has minute granularity (rounded to the nearest minute).

Return value

Upon completion, this function does not return any value.

If an error occurs, the default return value is false; therefore errors (via fastly.error) must be handled specifically.

Errors

If the given entry is longer than 256 bytes, then false is returned, and fastly.error is set to EINVAL.

Example

The following example will immediately add every connecting client to the penalty box for 5 minutes, as identified by IP address:

penaltybox pbox { }

sub vcl_recv {
  ratelimit.penaltybox_add(pbox, client.ip, 5m);
}