Skip to content

Caching Responses

Jump to bottom Edit New page
Alexander K edited this page Feb 1, 2022 · 20 revisions

With caching enabled Tempesta FW 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 cacheable methods can be extended with other methods supported by Tempesta FW 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 cacheable 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.

If a web application is hard to change to set custom Cache-Control header values for specific resources, then Tempesta FW can be be told to some or all of Cache-Control directives. This can be done with cache_control_ignore <argument>... configuration option, e.g.

cache_control_ignore no-cache public;

to ignore no-cache and public directives in the Cache-Control header.

cache_resp_hdr_del <list of header names> removes specified headers from cached HTTP responses. For example, if a client requests a resource, which is returned with Set-Cookie and X-Client-ID headers, and Tempesta FW has

cache_resp_hdr_del Set-Cookie X-Client-ID;

in the configuration, then the client receives the response with the headers. However, the response is stored in the cache without the headers and all following requests will fetch the response from the cache without the headers.

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/

You also can use X-Tempesta-Cache: get header, e.g.

curl -X PURGE -H 'X-Tempesta-Cache: get' http://192.168.10.10/

to make Tempesta FW immediately fetch a new version of the resource from the upstream server. Once Tempesta FW receives the request it purges the resource from the cache and sends a GET request to the upstream. When Tempesta FW receives a response for the request, it caches it and any following client request will be services immediately right from the cache. Actually, Tempesta FW just rewrites the method (from PURGE to GET) in the request, so you can add any other headers, which you need to pass to the upstream.

HTTP/1 is only supported for cache entries purging.

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];
Add a custom footer

Contents

Clone this wiki locally