The purge
vmod contains functions that offer a finer-grained control than the
purge
transition in sub vcl_recv
. The functions can only be called from
sub vcl_hit
or sub vcl_miss
and they should in general be used in both to
ensure that all variants of a same object are taken care of.
vmod_softpurge
is older and offers similar functionality to the newer vmod_purge
.
It is recommended to upgrade to vmod_purge
if possible, as its API is more complete.
softpurge.softpurge()
VOID softpurge()
The only function of the vmod performs a soft purge, setting the TTL of the
object to 0. It must be called both from sub vcl_hit
and sub vcl_miss
to make
sure all variants of the chosen object are reset.
softpurge.softpurge()
is functionally equivalent to purge.soft()
, making the
migration easy:
purge
instead of softpurge
;softpurge.softpurge()
calls with purge.soft()
.# make sure to block unauthorized IP addresses trying to purge
sub vcl_recv {
if (req.method == "PURGE") {
if (client.ip !~ purge_acl) {
return (synth(405));
} else {
return (hash);
}
}
}
# subroutine to kill the object (called from vcl_hit and vcl_miss)
# here, ttl and grace are zero'ed, but keep is set to one day so that the object
# must be revalidated before being sent to the client
sub my_purge {
set req.http.purged = purge.soft(ttl = 0s, grace = 0s, keep = 1d);
return (synth(200));
}
sub vcl_hit {
if (req.method == "PURGE") {
call my_purge;
}
}
sub vcl_miss {
if (req.method == "PURGE") {
call my_purge;
}
}
# we are sent here from my_purge, and we can now copy the purged header
# containing the number of purged objects to the response
sub vcl_synth {
if (req.method == "PURGE") {
set resp.http.purged = req.http.purged;
return (deliver);
}
}
INT hard()
This is equivalent to return(purge)
but explicitly called from
sub vcl_hit
and sub vcl_miss
. It returns the number of purged objects.
set req.http.purged = purge.hard();
Arguments: None
Type: Function
Returns: Int
INT soft(DURATION ttl = 0, DURATION grace = -1, DURATION keep = -1)
Sets the TTL, grace and keep. By default, TTL is set to 0 with grace
and keep periods left untouched. Setting a negative value for grace or
keep periods leaves them untouched. Setting all three parameters to
0 is equivalent to a hard purge. It can only be called from sub vcl_hit
or sub vcl_miss
. It returns the number of soft-purged objects.
Arguments:
ttl
accepts type DURATION with a default value of 0
optional
grace
accepts type DURATION with a default value of empty. optional
keep
accepts type DURATION with a default value of empty. optional
Type: Function
Returns: Int
The purge
VMOD is available in Varnish Enterprise version 6.0.0r0
and later.