Skip to content

Caching Responses

Jump to bottom Edit New page
EvgeniiMekhanik edited this page May 31, 2024 · 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
Syntax:         cache <mode>;
Default:        cache 2;
Context:        global
Reconfig:       false
Repeat:         false

Set cache mode. 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
Syntax:         cache_db <path_to_db>;
Default:        cache_db /opt/tempesta/db/cache.tdb;
Context:        global
Reconfig:       false
Repeat:         false

Path to a cache database files. The PATH must be absolute and the directory must exist. The database file must end with .tdb. 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
Syntax:         cache_size <size>;
Default:        cache_size 268435456; # (256MB)
Context:        global
Reconfig:       false
Repeat:         false

Size of each Tempesta DB file in bytes used as Web cache storage. Suffixes like 'MB' are not supported yet. The size must be multiple of 2MB (Tempesta DB extent size).

Minimum: 16777216 (16MB) Maximum: 137438953472 (128GB) 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
Syntax:         <caching policy> <OP> <string> [<string>];
Default:        disabled
Context:        global, vhost, location
Reconfig:       true
Repeat:         true

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>: 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.

cache_methods
Syntax:         cache_methods <list_of_methods>;
Default:        cache_methods GET;
Context:        global
Reconfig:       false
Repeat:         false

List of cacheable request methods. Responses to requests with these methods will be cached. HTTP methods, separated with spaces. Default list of cacheable methods can be extended with other methods supported by Tempesta FW if it is helpful for the application. Available methods: GET, HEAD, POST. Caching of all these methods is carried out in accordance with the RFC 9111. For example response to POST request can satisfy GET and HEAD but not POST requests.
Besides, some request methods may be cacheable only when certain additional restrictions are satisfied.

cache_control_ignore
Syntax:         cache_control_ignore <list_of_arguments>;
Default:        disabled
Context:        global, vhost, location
Reconfig:       true
Repeat:         true

Normally, caching behavior of Tempesta FW follows Cache-Control directives from server's responses. Particularly, server can specify to not store some headers in cached responses e.g. for a Cache-Control: no-cache="set-cookie" response Tempesta FW will send cached responses without Set-Cookie header for subsequent requests (provided the caching is allowed for those requests).
Sometimes it's hard to modify web application's behavior to make it respond with a custom Cache-Control header values. In this case Tempesta FW can be told to ignore some or all of Cache-Control directives. For example:

cache_control_ignore no-cache public;

to ignore no-cache and public directives in the response'sCache-Control header.

cache_resp_hdr_del
Syntax:         cache_resp_hdr_del <list_of_header_names>
Default:        disabled
Context:        global, vhost, location
Reconfig:       true
Repeat:         true

Remove the specified headers in cached HTTP responses. For example, if a client requests a resource 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 for the first request. However, the response is stored in the cache without the headers and all subsequent requests will receive a cached response without those headers.

cache_disable

Caching policy can be changed on per request basis with http chain rules. Http chains let for cache_disable rules action. For instance:

cookie "example_site_name*" == "*-do-not-cache" -> cache_disable;

The rule prevents caching for requests that contains cookie with name that prefixed (or equals to) with example_site_name and a value for that cookie equals or suffixed with -do-not-cache. For more information about http chains configuration please see HTTP Tables wiki page.

Note that cache_disable comes in two forms:

  • cache_disable or cache_disable = 1 — this enforces tempesta to ignore upstream headers and do not cache response.
  • cache_disable = 0 — this only cancels effect of previously matched cache_disabled = 1 directive (ie no caching is enforced). This could be useful if you specify a wider range of cache-disabling rules and then a set of fine-grained rules that cancel out some of previously defined cache-disabling rules. Check following example for more detail:
cookie "foo_items_in_cert*" == "*" -> cache_disable;
# allow caching of "*.png" urls, because this rule is applied after first one
uri == "*.png" -> cache_disable = 0;
cache_ttl
Syntax:         cache_ttl <seconds>;
Default:        cache_ttl 2147483647;
Context:        global
Reconfig:       false
Repeat:         false

sets default lifetime of the response in the cache in case response didn't contain any cache-related headers. This global value can be overriden by cache_ttl = <SECONDS> action of the HTTP tables mechanism.

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 serviced immediately right from the cache. Tempesta FW does not include the response body for the PURGE response to not to overload the client sending PURGE request and the network. 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.

According RFC 9111 4.4: A cache MUST invalidate the target URI when it receives a non-error status code in response to an unsafe request method (including methods whose safety is unknown). A "non-error response" is one with a 2xx (Successful) or 3xx (Redirection) status code. Tempesta FW follows RFC 9111 4.4.

HTTP/1 is only supported for cache entries purging.

cache_purge
Syntax:         cache_purge <mode>;
Default:        disabled
Context:        global
Reconfig:       false
Repeat:         false

Enable manual cache purging and set purging mode. 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
Syntax:         cache_purge_acl <list_of_ip_address>;
Default:        disabled
Context:        global
Reconfig:       false
Repeat:         false

IP addresses of hosts that are permitted to send PURGE requests. PURGE requests from all other hosts will be denied. 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