Nginx proxy_cache_path: Sizing keys_zone, Temporary File Storage, and Cache Manager Limits

In Nginx, the proxy_cache_path directive configures where cached files reside on disk and defines parameters for shared memory allocation and disk-space limits. This directive is configured in the http context.

Shared Memory Allocation with keys_zone

The keys_zone parameter defines the name and size of a shared memory zone. In this zone, Nginx stores all active keys and information about cached data.

Memory capacity scales based on the zone size and Nginx edition:

• In standard open-source Nginx, a 1-megabyte memory zone can store approximately 8,000 keys.
• Under a commercial subscription, the shared memory zone also stores extended cache information, requiring a larger zone for the same volume of keys (a 1-megabyte zone stores approximately 4,000 keys).

Disk Storage Hierarchy and Temporary Files

Cache data are stored in files within the path specified by proxy_cache_path. The on-disk filename is generated by applying the MD5 function to the cache key.

The levels parameter configures the directory hierarchy levels of the cache, supporting 1 to 3 levels where each level accepts values of 1 or 2 characters (for example, levels=1:2).

When saving a response, Nginx first writes the content to a temporary file and then renames it:

• Starting in version 0.8.9, temporary files and the cache directory can reside on different filesystems. However, cross-filesystem moves require copying the file instead of a cheap renaming operation. Nginx documentation therefore recommends placing both the cache directory and the temporary files directory on the same filesystem.
• The directory for temporary files is governed by the use_temp_path parameter (introduced in version 1.7.10). If omitted or set to on, Nginx uses the directory specified by proxy_temp_path. If set to off, temporary files are put directly in the cache directory.

Cache Manager Eviction Limits

Nginx uses a dedicated cache manager process to track disk usage and apply configured limits:

When the configured max_size is exceeded or available filesystem space falls below min_free, the cache manager process removes the least recently used (LRU) data.

This cleanup runs in iterations governed by parameters introduced in version 1.11.5:

• manager_files: Sets the maximum number of items deleted during one iteration (defaults to 100).
• manager_threshold: Sets the duration of one iteration.
• manager_sleep: Sets the pause between iterations.

Access-Based Removal with the inactive Parameter

Cached files are also subject to removal based on access timing rather than origin expiration headers:

The inactive parameter specifies a duration (defaulting to 10 minutes). Cached data that are not accessed during this configured time get removed from the cache regardless of their freshness.

Example Configuration

The following example illustrates proxy_cache_path configuration options in the http block:

http {
    proxy_cache_path /data/nginx/cache
                     levels=1:2
                     keys_zone=cache_zone:10m
                     use_temp_path=off
                     inactive=60m
                     max_size=10g
                     min_free=1g
                     manager_files=100
                     manager_sleep=50ms
                     manager_threshold=200ms;
}

In this configuration, Nginx assigns a 10 MB shared memory zone named cache_zone, places temporary files directly inside the cache directory, sets a 60-minute inactivity timer, and sets a 10 GB maximum cache size and 1 GB minimum filesystem free space across throttled cache manager iterations.

Research Method and Limitations

This explainer was prepared from the supplied public source excerpt of the official Nginx ngx_http_proxy_module documentation. Competing coverage was limited to an excerpt of portal boilerplate that contained no technical details. Sections of the primary source documentation excerpt were truncated. Operational mechanics and parameters are described strictly as documented in the provided excerpts without unverified claims regarding external monitoring tools or unstated disk-write blocking behaviors.

Source references

• nginx.org documentation