NGINX Content Caching

NGINX Content Caching
This chapter describes how to enable and configure caching of responses received from proxied servers. When caching is enabled, NGINX Plus saves responses in a disk cache and uses them to respond to clients without having to proxy requests for the same content every time.

To learn more about NGINX Plus’s caching capabilities, watch the Content Caching with NGINX webinar on demand and get an in-depth review of features such as dynamic content caching, cache purging, and delayed caching.

Enabling the Caching of Responses

To enable caching, include the proxy_cache_path directive in the top-level http context. The mandatory first parameter is the local filesystem path for cached content, and the mandatory keys_zone parameter defines the name and size of the shared memory zone that is used to store metadata about cached items.

Then include the proxy_cache directive in the context where you want to cache server responses, specifying the zone name defined by the keys_zone parameter to the proxy_cache_path directive (in this case, one):

http {
    proxy_cache_path /data/nginx/cache keys_zone=one:10m;

    server {
        proxy_cache one;
        location / {
            proxy_pass http://localhost:8000;

Note that the size defined by the keys_zone parameter does not limit the total amount of cached response data. Cached responses themselves are stored with a copy of the metadata in specific files on the filesystem. To limit the amount of cached response data, include the max_size parameter to the proxy_cache_path directive. (But note that the amount of cached data can temporarily exceed this limit, as described in the following section.)

NGINX Plus Processes Involved in Caching

There are two additional NGINX Plus processes involved in caching:

  • The cache manager is activated periodically to check the state of the cache. If the cache size exceeds the limit set by the max_size parameter to the proxy_cache_path directive, the cache manager removes the data that was accessed least recently. As previously mentioned, the amount of cached data can temporarily exceed the limit during the time between cache manager activations.

  • The cache loader runs only once, right after NGINX Plus starts. It loads metadata about previously cached data into the shared memory zone. Loading the whole cache at once could consume sufficient resources to slow NGINX Plus’s performance during the first few minutes after startup. To avoid this, configure iterative loading of the cache by including the following parameters to the proxy_cache_path directive:

    • loader_threshold – Duration of an iteration, in milliseconds (by default, 200)
    • loader_files – Maximum number of items loaded during one iteration (by default, 100)
    • loader_sleeps – Delay between iterations, in milliseconds (by default, 50)
    In the following example, iterations last 300 milliseconds or until 200 items have been loaded:

    proxy_cache_path /data/nginx/cache keys_zone=one:10m
                     loader_threshold=300 loader_files=200;

Specifying Which Requests to Cache

By default, NGINX Plus caches all responses to requests made with the HTTP GET and HEAD methods the first time such responses are received from a proxied server. As the key (identifier) for a request, NGINX Plus uses the request string. If a request has the same key as a cached response, NGINX Plus sends the cached response to the client. You can include various directives in the http, server, or location context to control which responses are cached.

To change the request characteristics used in calculating the key, include the proxy_cache_key directive:

proxy_cache_key "$host$request_uri$cookie_user";

To define the minimum number of times that clients must make requests with the same key before the response is cached, include the proxy_cache_min_uses directive:

proxy_cache_min_uses 5;

To cache responses to requests with methods other than GET and HEAD, list them along with GET and HEAD as parameters to the proxy_cache_methods directive:

proxy_cache_methods GET HEAD POST;

Limiting or Bypassing Caching

By default, responses remain in the cache indefinitely. They are removed only when the cache exceeds the maximum configured size, and then in order by length of time since they were last requested. You can set how long cached responses are considered valid, or even whether they are used at all, by including directives in the http, server, or location context:

To limit how long cached responses with specific status codes are considered valid, include the proxy_cache_valid directive:

proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;

In this example, responses with the code 200 or 302 are considered valid for 10 minutes, and responses with code 404 are valid for 1 minute. To define the validity time for responses with all status codes, specify any as the first parameter:

proxy_cache_valid any 5m;

To define conditions under which NGINX Plus does not send cached responses to clients, include the proxy_cache_bypass directive. Each parameter defines a condition and consists of a number of variables. If at least one parameter is not empty and does not equal “0” (zero), NGINX Plus does not look up the response in the cache, but instead forwards the request to the back-end server immediately.

proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;

To define conditions under which NGINX Plus does not cache a response at all, include the proxy_no_cache directive, defining parameters in the same way as for the proxy_cache_bypass directive.

proxy_no_cache $http_pragma $http_authorization;

Combined Configuration Example

The following sample configuration combines some of the caching options described above.

http {
    proxy_cache_path /data/nginx/cache keys_zone=one:10m
                     loader_threshold=300 loader_files=200

    server {
        listen 8080;
        proxy_cache one;

        location / {
            proxy_pass http://backend1;

        location /some/path {
            proxy_pass http://backend2;
            proxy_cache_valid any   1m;
            proxy_cache_min_uses 3;
            proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;

The example defines a virtual server with two locations that use the same cache but with different settings.

Because responses from the backend1 server rarely change, no cache-control directives are included. Responses are cached the first time a request is made, and remain valid indefinitely.

By contrast, responses to requests served by backend2 change frequently, so they are considered valid for only 1 minute and aren’t cached until the same request is made 3 times. Moreover, if a request matches the conditions defined by the proxy_cache_bypass directive, NGINX Plus immediately passes the request to backend2 without looking for it in the cache.

NGINX Plus is the commercially-supported version of the open source NGINX software, offering:
  • High-performance load balancing
  • Application-aware health checks
  • Massively-scalable content caching
  • Sophisticated streaming media delivery
  • Advanced activity monitoring
  • DevOps on-the-fly reconfiguration
backed by dedicated support from NGINX, Inc.

Read more about NGINX Plus features:

Get Started with NGINX Plus for Free Today

NGINX Plus combines web serving, load balancing, content caching, and media streaming into one easy to deploy and manage package. Add it to your existing applications today for an immediate performance boost. Try NGINX Plus for free today.
Have questions?

Contact NGINX »