The backend fetch parts of VCL have changed in Varnish 4. We’ve tried to compile a list of changes needed to upgrade here.
To make sure that people have upgraded their VCL to the current version, Varnish now requires the first line of VCL to indicate the VCL version number:
vcl 4.0;
To align better with RFC naming, req.request has been renamed to req.method.
To make directors (backend selection logic) easier to extend, the directors are now defined in loadable VMODs.
Setting a backend for future fetches in vcl_recv is now done as follows:
sub vcl_init {
new cluster1 = directors.round_robin();
cluster1.add_backend(b1, 1.0);
cluster1.add_backend(b2, 1.0);
}
sub vcl_recv {
set req.backend_hint = cluster1.backend();
}
Note the extra .backend() needed after the director name.
Since the client director was already a special case of the hash director, it has been removed, and you should use the hash director directly:
sub vcl_init {
new h = directors.hash();
h.add_backend(b1, 1);
h.add_backend(b2, 1);
}
sub vcl_recv {
set req.backend_hint = h.backend(client.identity);
}
To make a distinction between internally generated errors and VCL synthetic responses, vcl_backend_error will be called when varnish encounters an error when trying to fetch an object.
Setting headers on synthetic response bodies made in vcl_synth are now done on resp.http instead of obj.http.
The synthetic keyword is now a function:
if (resp.status == 799) {
set resp.status = 200;
set resp.http.Content-Type = "text/plain; charset=utf-8";
synthetic("You are " + client.ip);
return (deliver);
}
To better represent a the context in which it is called, you should now use beresp.* vcl_backend_error, where you used to use obj.* in vcl_error.
Example:
sub vcl_backend_response {
if (beresp.http.X-No-Cache) {
set beresp.uncacheable = true;
set beresp.ttl = 120s;
return (deliver);
}
}
req.* used to be available in vcl_fetch, but after the split of functionality, you only have ‘bereq.*’ in vcl_backend_response.
Any custom-made subs cannot be named ‘vcl_*’ anymore. This namespace is reserved for builtin subs.
Remember to import the std module if you’re not doing so already.
client.ip and server.ip are now proper datatypes, which renders as an IP address by default. You need to use the std.port() function to get the port number.
obj is now read-only. obj.hits, if enabled in VCL, now counts per objecthead, not per object. obj.last_use has been retired.
Note that obj.hits may not be reset in some cases where bans are in use. See bug 1492 for details.
Apart from the new synth return value described above, the following has changed:
- vcl_recv must now return hash instead of lookup
- vcl_hash must now return lookup instead of hash
- vcl_pass must now return fetch instead of pass
The VCL code that is appended to user-configured VCL automatically is now called the builtin VCL. (previously default.vcl)
The builtin VCL now honors Cache-Control: no-cache (and friends) to indicate uncacheable content from the backend.
Replaced by unset.
session_linger has been renamed to timeout_linger.
sess_timeout has been renamed to timeout_idle.
In 3.0 it was often necessary to increase sess_workspace if a lot of VMODs, complex header operations or ESI were in use.
This is no longer necessary, because ESI scratch space happens elsewhere in 4.0.
If you are using a lot of VMODs, you may need to increase either workspace_backend and workspace_client based on where your VMOD is doing its work.
You can now completely disable inline C in your VCL, and it is disabled by default.
The logging framework has a new filtering language, which means that the -m switch has been replaced with a new -q switch. See Varnish VSL Query Expressions for more information about the new query language.