Master NGINX Content Caching: Boost Performance and Reduce Backend Load

NGINX Plus can cache static and dynamic content from proxied web and application servers, speeding up delivery to clients and reducing backend load.

Overview

When caching is enabled, NGINX Plus stores responses in a disk cache and serves them to clients without re‑proxying the same content.

For more details see the “Content Caching with NGINX” webinar.

Enabling response cache

To enable caching, add a

proxy_cache_path

directive in the top‑level

http

context. The first required parameter is the local filesystem path for cached data, and the

keys_zone

parameter defines a shared memory zone for cache metadata.

<code>http {
    # …
    proxy_cache_path /data/nginx/cache keys_zone=mycache:10m;
}</code>

Then add

proxy_cache

in the context where you want to cache responses, referencing the zone name defined above.

<code>http {
    proxy_cache_path /data/nginx/cache keys_zone=mycache:10m;
    server {
        proxy_cache mycache;
        location / {
            proxy_pass http://localhost:8000;
        }
    }
}</code>

The

keys_zone

size limits only the metadata; to limit the total size of cached data, add the

max_size

parameter to

proxy_cache_path

.

NGINX processes involved in caching

The cache manager periodically checks the cache size and removes the least‑recently used items when the max_size limit is exceeded.

The cache loader runs once at startup, loading metadata of existing cache files into shared memory. To avoid a heavy startup load, configure iterative loading with loader_threshold , loader_files , and loader_sleeps .

loader_threshold

– duration of each iteration in milliseconds (default 200).

loader_files

– maximum items loaded per iteration (default 100).

loader_sleeps

– pause between iterations in milliseconds (default 50).

Example with a 300 ms iteration threshold and a stop after loading 200 items:

<code>proxy_cache_path /data/nginx/cache keys_zone=mycache:10m loader_threshold=300 loader_files=200;</code>

Specifying which requests to cache

By default NGINX Plus caches responses to HTTP GET and HEAD requests. The request line is used as the cache key. Use

proxy_cache_key

to customize the key, for example:

<code>proxy_cache_key "$host$request_uri$cookie_user";</code>

Use

proxy_cache_min_uses

to require a request to be seen a certain number of times before it is cached:

<code>proxy_cache_min_uses 5;</code>

To cache additional methods, list them in

proxy_cache_methods

:

<code>proxy_cache_methods GET HEAD POST;</code>

Limiting or disabling cache

Responses remain in the cache indefinitely unless the cache exceeds its configured size. Use

proxy_cache_valid

to set a lifetime for specific status codes:

<code>proxy_cache_valid 200 302 10m;
proxy_cache_valid 404 1m;</code>

Use

proxy_cache_bypass

to prevent cache lookup for certain conditions, and

proxy_no_cache

to skip caching altogether.

Clearing cached content

NGINX can purge cached files when it receives a request with a custom HTTP header or the PURGE method.

Configuring cache purge

Define a variable that evaluates to 1 for PURGE requests:

<code>http {
    map $request_method $purge_method {
        PURGE 1;
        default 0;
    }
}</code>

In the location that uses caching, add

proxy_cache_purge

with the variable:

<code>server {
    listen 80;
    server_name www.example.com;
    location / {
        proxy_pass https://localhost:8002;
        proxy_cache mycache;
        proxy_cache_purge $purge_method;
    }
}</code>

Send a purge request with curl:

<code>curl -X PURGE -D – "https://www.example.com/*"</code>

Restrict purge access by IP using the

geo

module and the same variable logic.

Full removal of cached files

Enable the built‑in cache purger by adding

purger=on

to

proxy_cache_path

:

<code>proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=mycache:10m purger=on;</code>

Byte‑range caching

For large files, enable the Cache Slice module to cache partial ranges and fill the cache gradually.

Compile NGINX with the

slice

module.

Set the slice size:

<code>location / {
    slice 1m;
}</code>

Include the slice range in the cache key:

<code>proxy_cache_key $uri$is_args$args$slice_range;</code>

Cache 206 responses:

<code>proxy_cache_valid 200 206 1h;</code>

Pass the range header to the upstream:

<code>proxy_set_header Range $slice_range;</code>

Combined configuration example

<code>http {
    # …
    proxy_cache_path /data/nginx/cache keys_zone=mycache:10m loader_threshold=300 loader_files=200 max_size=200m;
    server {
        listen 8080;
        proxy_cache mycache;
        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;
        }
    }
}</code>