NAME

       vmod_xkey - Surrogate keys support for Varnish Cache

SYNOPSIS

          import xkey [as name] [from "path"]

          INT purge(STRING keys)

          INT softpurge(STRING keys)

DESCRIPTION

       This vmod adds secondary hashes to objects, allowing fast purging on all objects with this
       hash key.

       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 an xkey header.

       Similarly with an e-commerce site, where various SKUs are often referenced on a page.

       Hash  keys  are  specified in the xkey response header. Multiple keys can be specified per
       header line with spaces and/or commas as separators. Alternatively, they can be  specified
       in multiple xkey response headers.

       Preferably  the  secondary  hash keys are set from the backend application, but the header
       can also be set from VCL in vcl_backend_response.

       VCL example:

          vcl 4.0;
          import xkey;

          backend default { .host = "192.0.2.11"; .port = "8080"; }

          acl purgers {
              "203.0.113.0"/24;
          }

          sub vcl_recv {
              if (req.method == "PURGE") {
                  if (client.ip !~ purgers) {
                      return (synth(403, "Forbidden"));
                  }
                  if (req.http.xkey) {
                      set req.http.n-gone = xkey.purge(req.http.xkey);
                      # or: set req.http.n-gone = xkey.softpurge(req.http.xkey)

                      return (synth(200, "Invalidated "+req.http.n-gone+" objects"));
                  } else {
                      return (purge);
                  }
              }
          }

   Example
       On an e-commerce site we have the backend application  issue  an  xkey  header  for  every
       product  that is referenced on that page. So the header for a certain page might look like
       this:

          HTTP/1.1 OK
          Server: Apache/2.2.15
          xkey: 8155054
          xkey: 166412
          xkey: 234323

       This requires a bit of VCL to be in place. The VCL can be found above.

       Then, in order to keep the web in sync with the database, a  trigger  is  set  up  in  the
       database.  When  an  SKU  is updated this will trigger an HTTP request towards the Varnish
       server, clearing out every object with the matching xkey header:

          PURGE / HTTP/1.1
          Host: www.example.com
          xkey: 166412

       Note the xkey header. It is probably a good idea to protect this with  an  ACL  so  random
       people from the Internet cannot purge your cache.

       Varnish will find the objects and clear them out, responding with:

          HTTP/1.1 200 Purged
          Date: Thu, 24 Apr 2014 17:08:28 GMT
          X-Varnish: 1990228115
          Via: 1.1 Varnish

       The objects are now cleared.

   INT purge(STRING keys)
       Description
              Purges  all  objects  hashed  on  any  key found in the keys argument.  Returns the
              number of objects that were purged.

              The keys may contain a list of space-separated ids.

   INT softpurge(STRING keys)
       Description
              Performs a "soft purge" for all objects  hashed  on  any  key  found  in  the  keys
              argument.  Returns the number of objects that were purged.

              A  softpurge  differs  from  a  regular purge in that it resets an object's TTL but
              keeps it available for grace mode and conditional requests for the remainder of its
              configured grace and keep time.

   Counters
   #
          varnish_vsc_begin:: xkey

XKEY – XKEY COUNTERS

          Metrics from vmod_xkey

       g_keys – gauge - info
          Number of surrogate keys

          Number  of  surrogate keys in use. Increases after a request that includes a new key in
          the xkey header. Decreases when a key is purged or when all  cache  objects  associated
          with a key expire.

       g_hashhead_bytes – gauge - debug
          Bytes used by all xkey_hashhead objects

          Total bytes used by hashhead objects. Tracks linearly with the number of surrogate keys
          in use.

       g_ochead_bytes – gauge - debug
          Bytes used by all xkey_ochead objects

          Total bytes used by ochead objects. Increases when an object is added to a key or a key
          is added to an object. Decreases when the relationship is removed.

       g_oc_bytes – gauge - debug
          Bytes used by all xkey_oc objects

          Total  bytes used by oc objects. Tracks linearly with the number of cached objects that
          are referenced by surrogate keys.

       g_bytes – gauge - info
          Bytes used by xkeys

          Current number of bytes used by xkeys and their references to the object cache.

                                                                                     VMOD_XKEY(3)