nginx-cache-purge/README.md

nginx-cache-purge

A tool to help purge Nginx cache. It can either run locally with the purge command, or run as a local unix service to allow for purging by Nginx http requests. The tool supports using wildcard/glob syntax in the purge key to match multiple keys from the cache.

Install

You can install either by downloading the latest binary release, or by building.

Building

Building should be as simple as running:

make

Usage

The following are some examples of ways to purge cache

Purge a specific key

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache example.com/index.html

Purge all keys for a domain

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache 'example.com/*'

Purge all keys for jpeg and png files

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache 'example.com/*.{jpg,jpeg,png}'

Purge all keys

$ nginx-cache-purge purge /var/nginx/proxy_temp/cache '*'

Purge a key that contains wildcard characters

Whether a key is a wildcard is otherwise guessed from the punctuation in it, and real cache keys carry that punctuation: a request URI with a query string puts ? in the key, and PHP-style array parameters put [ and ]. --exact says the key is a literal, for both the key and any excludes.

$ nginx-cache-purge purge --exact /var/nginx/proxy_temp/cache 'example.com/list.php?f[]=x'

Running as a service

If you want to run as a service to allow purge requests via http requests, the service can install itself:

nginx-cache-purge service install --cache-path /var/nginx/proxy_temp/cache
nginx-cache-purge service start

service also accepts stop, restart, status, and uninstall. The installed unit runs nginx-cache-purge server as a notify service, creates the runtime directory the socket lives in, and restarts on failure. --cache-path restricts which caches that server will purge, and is covered below.

Connecting to a UNIX socket needs write permission on it, so the socket is created mode 0660: the purge server and Nginx have to run as the same user, or share a group. The installed unit runs as root, so either add a User=/Group= drop-in for it, or widen the socket with --socket-mode.

Restricting which caches may be purged

The directory to purge comes from the request, and the purge deletes what it finds under it, so a server left unrestricted will purge any path its user can reach. Pass --cache-path to name the caches it may serve, repeating it for more than one:

nginx-cache-purge server --cache-path /var/nginx/proxy_temp/cache

A request naming any other directory is refused with 403. Directories inside a named cache are allowed, and symlinks are resolved, so a link to a named cache is recognised as that cache. Naming no path leaves every path purgeable, which is what a server without the flag has always done.

service install takes the same flag and writes it into the unit's ExecStart, so an installed service is restricted from its first start:

nginx-cache-purge service install --cache-path /var/nginx/proxy_temp/cache

Repeat the flag for more than one cache. Paths are made absolute at install, as the unit runs from a working directory of the service manager's choosing; symlinks are left as written and resolved per request. The allowlist lives in the unit, so changing it means installing again: service uninstall then service install with the paths you want.

Nginx config

If you want to purge via Nginx http requests, you'll need to add configuration to your Nginx config file.

The server reads four query parameters:

Parameter	Description
path	Path to the cache directory, the same one given to proxy_cache_path.
key	Cache key or wildcard match, the same one built by proxy_cache_key.
exclude	Key to keep, can be a wildcard. Repeat it to exclude more than one.
exact	Read the key and excludes as literals rather than wildcards.

Nginx substitutes $request_uri into the rewrite without escaping it, so a key containing % or + arrives as the literal bytes Nginx stored it under, and that is what is purged. A key escaped by a caller writing the request itself is purged too, so either convention works.

Literal keys and wildcards

A key built from $request_uri is a literal, and a request URI routinely holds the punctuation that would otherwise mark the key as a wildcard: ? from a query string, [ and ] from PHP-style array parameters. Read as wildcards those keys purge the wrong entries, fail outright, or match nothing while still answering PURGED and leaving the stale entry served. The examples below therefore pass exact=1, which is what you want when a PURGE request names one URL.

Leave exact off where the purge is meant to take a wildcard, such as the /purge(/.*) location further down, where a request for /purge/images/* clears everything under /images/.

Because $request_uri carries the client's own query string into the purge parameters, put exact=1 before key= in the rewrite. Parameters are taken first-wins, so an exact=0 a client appends to its request URI arrives second and is ignored. The same ordering already protects path. Note that exclude is collected rather than taken first-wins, so a client can append an exclude that holds back its own purge.

Map PURGE requests

http {
    map $request_method $is_purge {                                                             
        default   0;
        PURGE     1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&exact=1&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via cookie

http {
    map $cookie_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&exact=1&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via header

http {
    map $http_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache_bypass $is_purge;
            if ($is_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&exact=1&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Auth via header and IP white list.

http {
    map $http_purge_token $is_purge {
        default 0;
        nnCgKUx1p2bIABXR 1;
    }

    geo $purge_allowed {
        default 0;
        127.0.0.1 1;
        192.168.0.0/24 1;
    }

    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            set $should_purge $purge_allowed;
            if ($is_purge != 1) {
                set $should_purge 0;
            }
            proxy_cache_bypass $should_purge;
            if ($should_purge) {
                proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
                rewrite ^ /?path=/var/nginx/proxy_temp/cache&exact=1&key=$server_name$request_uri break;
            }

            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
    }
}

Using IP whitelists

This location takes a wildcard, so it leaves exact off: a request for /purge/images/* clears everything under /images/.

http {
    proxy_cache_path /var/nginx/proxy_temp/cache levels=1:2 keys_zone=my_cache:10m;
    proxy_cache_key $server_name$request_uri;

    server {
        location / {
            proxy_cache my_cache;
            proxy_pass http://upstream;
        }
        location ~ /purge(/.*) {
            allow 127.0.0.1;
            deny all;
            proxy_pass http://unix:/run/nginx-cache-purge/http.sock;
            rewrite ^ /?path=/var/nginx/proxy_temp/cache&key=$server_name$1 break;
        }
    }
}