nginxcachetool

README

nginxcachetool

A command line tool to work with the proxy cache directory created by NGINX's proxy_cache and proxy_cache_path directive. This tool can help you understand what's in your cache (--summary), search for items (--contains), purge items (--purge), and watch the changes to the cache in real time (--watch).

NGINX proxy caching stores each cached response as a flat file whose directory path is derived from the MD5 hash of the cache key. The file begins with a fixed binary header containing cache metadata (version, offsets, timing), followed by an ASCII block that embeds the original response headers and the cached body. This program will recursively scan a directory for these cache files and only read the metadata from each file to understand what it contains.

Enable proxy caching in NGINX with `proxy_cache_path` and `proxy_cache`:

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m inactive=60m;

server {
    location / {
        proxy_cache my_cache;
        proxy_pass http://upstream_backend;
    }
}

Installing

Install it into your Go bin directory (usually ~/go/bin) with:

go install github.com/leafo/nginxcachetool@latest

Building

In the checked out

go build

This produces the nginxcachetool binary in the project root.

Usage

nginxcachetool [flags] <cache-dir>

Common flags:

• --contains <needle> (repeatable) filters by substring on the cache entry’s key (KEY: value), full on-disk file path, or the Content-Type response header.
• --content-type <value> (repeatable) keeps entries whose Content-Type header matches (case-insensitive) or includes the provided value.
• --status <code> (repeatable) filters by cached HTTP status codes.
• --json streams matching entries as newline-delimited JSON.
• --full prints every metadata field and header when using human-readable output.
• --limit <n> stops after processing N matched entries (default: unlimited).
• --summary aggregates totals, sizes, and age buckets instead of listing.
• --print-file writes the cached response body (first match) to stdout.
• --purge deletes matching entries; add --dry-run to preview removals.
• --all disables filtering (required for dangerous operations like unconditional purge).
• --workers <n> sets the number of concurrent metadata scanners (defaults to CPU count).

Examples

List HTML cache entries and show their headers:

nginxcachetool --contains text/html --full /var/cache/nginx

Sample output:

KEY: production:5::/game-assets/tag-8-bit/tag-pirates:b1:
  Status: HTTP/1.1 200 OK
  Path: 0/00/0514439d879523f9d120d519b6cb7000
  Stored: 2025-07-29T22:20:41-07:00
  Size: 38.83 KB
  Status Code: 200
  Version: 5
  Header Offset: 395
  Body Offset: 705
  Raw Header Bytes: 298
  Raw Header Block:
    HTTP/1.1 200 OK
    Date: Wed, 30 Jul 2025 05:20:41 GMT
    Content-Type: text/html
    Transfer-Encoding: chunked
    Connection: keep-alive
    X-Accel-Expires: 600
    Server: lapis
    X-Frame-Options: SAMEORIGIN
    X-XSS-Protection: 1; mode=block
    X-Content-Type-Options: nosniff
    Referrer-Policy: no-referrer-when-downgrade

Export JSON object containing metadata for for 200 responses to a file:

nginxcachetool --status 200 --json /var/cache/nginx > cache-200.jsonl

Preview purging every cached 404 response without deleting anything yet:

nginxcachetool --status 404 --purge --dry-run /var/cache/nginx

Summary Mode

Gather high-level information about a subset of the cache with --summary. This scans the matching entries once and prints totals, average size, minimum and maximum sizes, content-type breakdowns, status counts, and age buckets (<1h, <1d, <7d, <30d, >=30d).

Summary mode can optionally be combined with filters like --contains and --status.

nginxcachetool --summary /var/cache/nginx

Sample output:

Summary for /var/cache/nginx
Total files: 661,378
Total size: 13.56 GB
Average size: 21.50 KB
Min size: 625 B (0/00/0514439d879523f9d120d519b6cb7000)
Max size: 3.96 MB (7/f1/aa0fdf2b6c483d0fb8ea0caaef4d8f17)

Content Types:
  application/json: 105,512
  application/rss+xml: 13
  application/xml: 316
  text/html: 555,537

Status Codes:
  200: 550,662
  301: 2,178
  302: 108,351
  404: 55
  451: 132

Watch Mode

Use --watch to follow cache activity as it happens. The tool recurses through the cache tree, subscribes to filesystem events with fsnotify, and reports create/update/remove actions with color-coded lines that include the size, status, and content type when available.

nginxcachetool --watch /var/cache/nginx

Press Ctrl+C to stop watching.