.\" Man page generated from reStructuredText.
.
.TH VMOD_XKEY 3 "" "" ""
.SH NAME
vmod_xkey \- Surrogate keys support for Varnish Cache
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.\" 
.
.\" NB:  This file is machine generated, DO NOT EDIT!
.
.\" 
.
.\" Edit vmod.vcc and run make instead
.
.\" 
.
.SH SYNOPSIS
.sp
import xkey [from "path"] ;
.SH DESCRIPTION
.sp
This vmod adds secondary hashes to objects, allowing fast purging on
all objects with this hash key.
.sp
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.
.sp
Similarly with an e\-commerce site, where various SKUs are often
referenced on a page.
.sp
Hash keys are specified in the \fBxkey\fP response header. Multiple keys
can be specified per header line with a space
separator. Alternatively, they can be specified in multiple \fBxkey\fP
response headers.
.sp
Preferably the secondary hash keys are set from the backend
application, but can also be set from VCL in \fBvcl_backend_response\fP
as in the above example.
.SS Example
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 OK
Server: Apache/2.2.15
xkey: 8155054
xkey: 166412
xkey: 234323
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This requires a bit of VCL to be in place. The VCL can be found above.
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
GET / HTTP/1.1
Host: www.example.com
xkey\-purge: 166412
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note the xkey\-purge header. It is probably a good idea to protect
this with an ACL so random people from the Internet cannot purge your
cache.
.sp
Varnish will find the objects and clear them out, responding with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
HTTP/1.1 200 Purged
Date: Thu, 24 Apr 2014 17:08:28 GMT
X\-Varnish: 1990228115
Via: 1.1 Varnish
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The objects are now cleared.
.SH CONTENTS
.INDENT 0.0
.IP \(bu 2
\fIfunc_purge\fP
.IP \(bu 2
\fIfunc_softpurge\fP
.UNINDENT
.SS purge
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT purge(STRING key)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Purges all objects hashed on \fIkey\fP\&. Returns the number of objects that were
purged.
.UNINDENT
.SS softpurge
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
INT softpurge(STRING key)
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B Description
Performs a "soft purge" for all objects hashed on \fIkey\fP\&.
Returns the number of objects that were purged.
.sp
A softpurge differs from a regular purge in that it resets an
object\(aqs TTL but keeps it available for grace mode and conditional
requests for the remainder of its configured grace and keep time.
.UNINDENT
.\" Generated by docutils manpage writer.
.