Purge (purge/softpurge)

Varnish 6.0

This page documents both vmod_purge and the older vmod_softpurge. It is recommended to upgrade to vmod_purge if possible asits API is more complete.

Description

Both vmods contain functions that offer a finer-grained control than the purge transition in vcl_recv. The functions can only be called from vcl_hit or vcl_miss and they should in general be used in both to ensure that all variants of a same object are taken care of.

VCL example

# make sure to block unauthorized IP addresse 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);
	}
}

vmod_purge

purge.soft()

INT soft(DURATION ttl = 0, DURATION grace = -1, DURATION keep = -1)

Sets the TTL, grace and keep. By default, TTL is set to 0s with grace and keep periods left untouched. Setting a negative value for grace or keep periods leaves them untouched. Setting all three parameters to 0s is equivalent to a hard purge. It can only be called from vcl_hit or vcl_miss. It returns the number of soft-purged objects.

purge.hard()

INT hard()

This is equivalent to return(purge) but explicitly called from vcl_hit and vcl_miss. It returns the number of purged objects.

vmod_softpurge

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 vcl_hit and vcl_miss to make sure all variants of the chosen object are reset.

Migration

softpurge.softpurge() is functionally equivalent to purge.soft(), making the migration easy:

Import purge instead of softpurge;
Replace softpurge.softpurge() calls with purge.soft().

Availability

Both vmods are bundled directly in the varnish-plus package.