Xkey (Hash-Two, Surrogate keys)

This vmod adds one or more secondary hashes to objects, allowing fast purging on all objects with this/these hash key/s. Hash keys have to be separated by one or more "space" characters. Space characters: {' ', 'n', 't', 'v', 'f', 'r'}. 

You can use this to indicate relationships, a bit like a "tag". Then clear out all object that have this tag set. Two good use cases are news sites, where one might add all the stories mentioned on a particular page by article ID, letting each article referenced create a xkey header.  Similarly with a ecommerce site, where various SKUs are often referenced on a page.

This feature was previously known as Hash Ninja / Secondary Hash / Hash-two and it was open sourced by Varnish Software as part of the Varnish Cache 4.1 release. Built originally for LiveJournal inc.


import xkey;

# Example of purging using xkey:
# The key to be purged is gotten from the xkey-purge header
sub vcl_recv {
    if (req.http.xkey-purge) {
        if (xkey.purge(req.http.xkey-purge) != 0) {
            return (synth(200, "Purged"));
        } else {
            return (synth(404, "Key not found"));

# The backend is responsible for setting the header.
# If you where to do it in VCL it will look something like this:
sub vcl_backend_response {
    # Use the header vmod to add multiple headers for multiple keys
    set beresp.http.xkey = "purgeable_hash_key";
Used in production
Varnish version supported: 
Commercial support: 
Varnish Software