vmod_purge(3)

Usage

import purge [as name] [from "path"]
INT hard()
INT soft(DURATION ttl, DURATION grace, DURATION keep)

Overview

vmod_purge contains functions that offer a finer-grained control than return(purge) from 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.

Examples

sub vcl_recv {
    if (req.method == "PURGE") {
        if (client.ip !~ purge_acl) {
            return (synth(405));
        }
        return (hash);
    }
}
sub my_purge {
    set req.http.purged = purge.hard();
    if (req.http.purged == "0") {
        return (synth(404));
    }
    else {
        return (synth(200));
    }
}
sub vcl_hit {
    if (req.method == "PURGE") {
        call my_purge;
    }
}
sub vcl_miss {
    if (req.method == "PURGE") {
        call my_purge;
    }
}
sub vcl_synth {
    if (req.method == "PURGE") {
        if (req.http.purged) {
            set resp.http.purged = req.http.purged;
        }
        return (deliver);
    }
}

INT hard()

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

Example:

set req.http.purged = purge.hard();

Restricted to: vcl_hit, vcl_miss.

INT soft(DURATION ttl, DURATION grace, DURATION keep)

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 grace or keep to a negative value or to something higher than the objects current value leaves them untouched. Setting all three parameters to 0 is equivalent to a hard purge. Returns the number of soft-purged objects.

A soft-purge can only decrease the lifetime of an object. Let's consider an object in cache created with ttl, grace, and keep of 60 seconds each:

purge.soft(ttl = 0s, grace = -1s, keep = -1s);

•: If the object is fresh, the ttl is reduced to 0 seconds and the object expires after 120 seconds.

•: If the object is stale, the expiry time is not changed.

purge.soft(ttl = 0s, grace = 10s, keep = 10s);

•: If the object is fresh, the ttl is reduced to 0 seconds, grace and keep are reduced to 10 seconds. The object expires after 20 seconds.

•: If the object has been stale for 5 seconds, grace is reduced to 5 seconds and keep is reduced to 10 seconds. The object expires after 15 seconds.

•: If the object has been stale for 15 seconds, grace is reduced to 0 seconds and keep is reduced to 5 seconds. The object expires after 5 seconds.

•: If the object has been stale for 20 seconds or more, the object immediately expires.

purge.soft(ttl = 10s, grace = -1s, keep = -1s);

•: If the object has been fresh for 5 seconds, the ttl is reduced to 10 seconds. The object expires after 130 seconds.

•: If the object has been fresh for 55 seconds, the ttl is not changed. The object expires after 125 seconds.

•: If the object is stale, the expiry time is not changed.

When the expiry time of an object is reduced due to a softpurge, an EXP_Reduce entry is logged under the ExpKill VSL tag. If a softpurge does not reduce the expiry time of an object, an EXP_Unchanged entry is logged instead.