Caching Responses

With caching enabled TempestaFW saves responses into a database cache to serve clients requests without contacting backend servers on each request. Cache database and caching policy must be configured to enable caching.

Cache DB

cache <MODE>: Set cache mode.
Defaults: 2
The next modes are available:

• 0 - no caching at all, pure proxying mode;
• 1 - Sharding mode. Each NUMA node contains independent shard of whole cache. This mode has the smallest memory requirements;
• 2 - Replicated mode. Each NUMA node has whole replica of the cache. It requires more RAM, but delivers the highest performance.

---

cache_db <PATH_TO_DB>: Path to a cache database files.
Defaults: /opt/tempesta/db/cache.tdb
The PATH must be absolute and the directory must exist. The database file must end with .tbd. However, this is the only path pattern rather than real path. Tempesta creates per NUMA node database files, so if you have two processor packages on modern hardware, then the following files will be created (one for each processor package) for the example above:

/opt/tempesta/db/cache0.tdb
/opt/tempesta/db/cache1.tdb

---

cache_size <SIZE>: Size of each Tempesta DB file in bytes used as Web cache storage. Minimum: 16777216 (16MB) Maximum: 137438953472 (128GB) Defaults: 268435456 (256MB) Suffixes like 'MB' are not supported yet. The size must be multiple of 2MB (Tempesta DB extent size).

128GB is the maximum size of one Tempesta DB table. If the size of isn't enough, then consider to use the replicated mode.

The web cache Tempesta DB table can not exceed the size of preserved huge pages memory region specified with tempesta_dbmem. Please check Prepare to start chapter.

Caching Policy

cache_methods <METHOD LIST> List of cacheable request methods. Responses to requests with these methods will be cached. METHOD LIST - HTTP methods, separated with spaces, see example below.
Defaults: GET.
Default list of cachable methods can be extended with other methods supported by TempestaFW if it is helpful for the application. Available methods: COPY, DELETE, GET, HEAD, LOCK, MKCOL, MOVE, OPTIONS, PATCH, POST, PROPFIND, PROPPATCH, PUT, TRACE, UNLOCK.
Note that not all of HTTP request methods are cacheable by the HTTP standards. Besides, some request methods may be cachable only when certain additional restrictions are satisfied.
Example:

cache_methods GET HEAD;

---

Caching policy is controlled by set of rules that match the destination URL against the pattern specified in the rule and using the match operator specified in the same rule. The full syntax is as follows:

<caching policy> <OP> <string> [<string>];

<caching policy>: one of the following values:

• cache_fulfill - Serve the request from cache. If the response is not found in cache, then forward the request to a back end server, and store the response in cache to serve future requests for the same resource. Update the cached response when necessary.
• cache_bypass - Skip the cache. Simply forward the request to a server. Do not store the response in cache.

<string>: the anticipated substring of URL. It is matched against the URL in a request according to the match operator specified by <OP>. Note that the string must be verbatim. Regular expressions are not supported at this time.

<OP>: one of the match operators below:

• eq - URL is fully equal to <string>.
• prefix - URL starts with <string>.
• suffix - URL ends with <string>.

Example:

cache_fulfill suffix ".jpg" ".png";
cache_bypass suffix ".avi";
cache_bypass prefix "/static/dynamic_zone/";
cache_fulfill prefix "/static/";

Caching policy directives are processed one-by-one in the order they appear in the configuration file. Also, a special variant of wildcard matching is supported. It makes all requests and responses either use or skip the cache. It should be used with caution.

cache_fulfill * *;
cache_bypass * *;

Note that Tempesta FW always takes priority to Cache-Control HTTP header to prevent web cache deception attack. For example if you specify cache_fulfill * * in you configuration, but a web server sends a response with Cache-Control: no-cache, then the response is not cached.

Manual Cache Purging

Cached responses may be purged manually using the PURGE request method and the URL of the cached response. A typical use case is that when some content is changed on the upstream server, then a PURGE request followed by a GET request will update an appropriate entry in the cache.

A PURGE request can be issued using any tool that is convenient. Below is just one example:

curl -X PURGE http://192.168.10.10/

---

cache_purge [MODE]: Enable manual cache purging and set purging mode.
Defaults: manual purging is disabled.
MODE can be one of the following:

• invalidate - just mark the cache record as stale and requiring validation. The cached response may still be returned to a client under certain conditions. This is default mode.

---

cache_purge_acl <ip_address>: IP addresses of hosts that are permitted to send PURGE requests. PURGE requests from all other hosts will be denied.
Defaults: deny purging from all hosts.
The directive is mandatory when cache_purge directive is specified. Multiple addresses are separated with white spaces.

<ip_address> can be an IPv4 or IPv6 address. An IP address can be specified in CIDR format where the address is followed by a slash character and the prefix (or mask) with the number of significant bits in the addresses. Below are examples of a valid IP address specification:

127.0.0.1
192.168.10.50/24
::ffff:c0a8:b0a
[::ffff:c0a8:a0a]
::ffff:c0a8:b0b/120
[::ffff:c0a8:b0b]/120

Example:

cache_purge_acl 192.168.10.50/24 [::ffff:c0a8:a0a];