🪴 Zero's Garden

NGINX proxy cache

3 min read

Checklist

  1. Do not cache sensitive content without authentication token included in proxy_cache_key. It is recommended to include a random secret in the string to further prevent hash collision attacks.
  2. Avoid proxy_cache_valid any and use specific status codes.
  3. If you want to limit the cache to certain arguments or other patterns, use proxy_no_cache and proxy_cache_bypass with a map-ed variable, where the string can be templated to match a set of conditions efficiently.
  4. With proxy_cache_lock enabled, a request returning cached content may have been delayed by a lock, resulting in longer $request_time in logs.
  5. Use the following config to instruct NGINX to deliver stale content when clients request an item that is expired or is in the process of being updated from the origin server. All updates will be done in the background. The stale file is returned for all requests until the updated file is fully downloaded.
proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
proxy_cache_background_update on;
proxy_cache_lock on;

The updating parameter to the proxy_cache_use_stale directive, combined with enabling the proxy_cache_background_update directive, instructs NGINX to deliver stale content when clients request an item that is expired or is in the process of being updated from the origin server. All updates will be done in the background. The stale file is returned for all requests until the updated file is fully downloaded.

If UPDATING starts to appear in $upstream_cache_status, background update is enabled.

Instrumentation

add_header X-Cache-Status $upstream_cache_status;

This example adds an X-Cache-Status HTTP header in responses to clients. The following are the possible values for $upstream_cache_status:

  • MISS – The response was not found in the cache and so was fetched from an origin server. The response might then have been cached.
  • BYPASS – The response was fetched from the origin server instead of served from the cache because the request matched a proxy_cache_bypass directive (see Can I Punch a Hole Through My Cache? below.) The response might then have been cached.
  • EXPIRED – The entry in the cache has expired. The response contains fresh content from the origin server.
  • STALE – The content is stale because the origin server is not responding correctly, and proxy_cache_use_stale was configured.
  • UPDATING – The content is stale because the entry is currently being updated in response to a previous request, and proxy_cache_use_stale updating is configured.
  • REVALIDATED – The proxy_cache_revalidate directive was enabled and NGINX verified that the current cached content was still valid (If-Modified-Since or If-None-Match).
  • HIT – The response contains valid, fresh content direct from the cache.

Notes

  1. Cache data is stored in files. The filename in a cache is a result of applying the MD5 function to the cache key.
  2. In addition, all active keys and information about data are stored in a shared memory zone, whose name and size are configured by the keys_zone parameter. One megabyte zone can store about 8 thousand keys.

Graph View

Backlinks