1. Home
2. Reference documentation
3. VCL reference
4. Declarations

A penaltybox stores keys for a specified period and provides functions to determine whether a given string is currently in the stored set.

Penalty boxes are a primitive that is used primarily in constructing rate limiting solutions.

They provide two operations: ratelimit.penaltybox_add and ratelimit.penaltybox_has. Calling the add function with a time to live (TTL) adds an entry to the penalty box. Calling the has function checks to see if the entry is already present in the set.

Each penaltybox can contain up to 200,000 entries per site and, once that limit is reached, each new entry will evict the one with the smallest remaining TTL.

All the cache nodes within the site communicate with each other, sharing information about the penalty box entries in order to converge on a single dataset. Because of synchronization delays, the first time a penalty box is used on a given cache node it will appear to be empty, because it is not yet synchronized with the rest of the cache nodes in the site. Once synchronization is complete, the penalty box will converge to the same dataset across the site.

Each penaltybox can contain up to 200,000 unique entries per site and, once that limit is reached, each new entry will evict the one with the smallest remaining TTL. Each entry in a penalty box can be no longer than 256 bytes and will be silently truncated if it is longer. The effective minimum TTL of an entry is 2 minutes.

Penalty boxes do not have any properties and should be declared as an empty block:

penaltybox banned_users {
  # no properties
}