SearchVarnish Enterprise
This is a general description of how to upgrade to newer versions of Varnish Enterprise. Most of the changes needed are identical to a Varnish Cache upgrade, so the open-source documentation is often referenced.
These instructions are not meant to be copied verbatim, but will give you an overview of the steps necessary when upgrading.
Note: A restart of Varnish is required to complete all upgrades.
Contact support to help with VCL configuration changes between versions.
Upgrades between minor versions, for example from 6.0.12r4 to 6.0.12r5, are considered stable and don’t require manual intervention.
Users of in-process TLS upgrading from version 6.0.13r1 or lower are encouraged to test their HTTPS setup before upgrading. New stricter coherence checks could prevent a restart of the service. If a certificate was loaded with incompatible ciphers, these ciphers could not be presented during a handshake. They must be removed from the configuration from 6.0.13r2 on.
Users upgrading from version 6.0.12r9 or lower are encouraged to test their VCL with this release before upgrading. If you encounter VCL compilation failures due to invalid VMOD usage, you will need to update your VCL before upgrading. If this VCL has never caused a problem for you before, it is likely that this VCL code was never reached.
Upgrading to 6.0 from 4.1 should be straight-forward, but there are some important changes that may force you to update your VCL and settings:
MSE 3.0 uses a specific mse.conf configuration file.
VHA doesn’t use vha-agent anymore and requires varnish-broadcaster.
You can make sure your VCL compiles with the newest version using: varnishd -Cf /etc/varnish/default.vcl
All VCL Objects are now defined before used, otherwise the compiler will generate an error.
VCL names are restricted to alphanumeric characters, dashes, and underscores. The first character should be alphabetic. The name should match “[A-Za-z][A-Za-z0-9_-]*”.
In sub vcl_recv, the rollback function has been retired.
In sub vcl_hit, remove all return (fetch)/return (miss). If you don’t, you will get many error log lines in the shared memory log.
The VMOD softpurge has been retired. The functionality is covered by the new purge VMOD.
kvstore is now object oriented. See kvstore 6.0 API.
Note: There are many improvements to VCL in Varnish 6.0 that are not covered here.
Here are a few snippets you’ll find on the internet that you shouldn’t use.
You’ll often find code trying to convey whether an object was deliver from cache or if it was a miss:
sub vcl_deliver {
if (obj.hits > 0) {
set resp.http.X-Cache = "HIT";
} else {
set resp.http.X-Cache = "MISS";
}
}
This snippet conflates anything that isn’t a hit as a miss, which is simply wrong. You can find a better, includable VCL covering this feature in this tutorial. Don’t forget to uncomment the last line for the clients to see the headers.
This snippet is found in the Varnish 4.0 book, but isn’t relevant anymore:
sub vcl_hit {
if (obj.ttl >= 0s) {
# normal hit
return (deliver);
}
# We have no fresh fish. Lets look at the stale ones.
if (std.healthy(req.backend_hint)) {
# Backend is healthy. Limit age to 10s.
if (obj.ttl + 10s > 0s) {
set req.http.grace = "normal(limited)";
return (deliver);
} else {
# No candidate for grace. Fetch a fresh object.
return(fetch);
}
} else {
# backend is sick - use full grace
if (obj.ttl + obj.grace > 0s) {
set req.http.grace = "full";
return (deliver);
} else {
# no graced object.
return (fetch);
}
}
}
In a nutshell, don’t return(fetch) (or return(miss)) from vcl_hit, as it can cause issues in the future. Instead, tweak the maximum grace a cache lookup will accept:
sub vcl_recv {
if (std.healthy(req.backend_hint)) {
// change the behavior for healthy backends: Cap grace to 10s
set req.grace = 10s;
}
}
It’s also much shorter! Of course, these two pieces of code only make sense if you have a way to mark backends as sick, otherwise std.healthy() will always return true.
Note: A better approach could be to use vmod-stale to implement the stale-if-error logic. With this you will go to the backend anyway, but if it returns an error you can decide to still use the grace object.
Upgrading from 4.0 to 4.1 is usually straight-forward. Before upgrading, the list of supported platforms should be reviewed. Note: On all platforms the varnish-plus-vmods package has been retired. Modules are now embedded in the main varnish-plus package. Also, the varnish-plus-vmods-extra package is still available.
mv /etc/yum.repos.d/varnish-4.0-plus.repo /etc/yum.repos.d/varnish-4.1-plus.repo
sed -i -e 's|4.0-plus|4.1-plus' /etc/yum.repos.d/varnish-4.1-plus.repo
yum clean metadata
yum update varnish-plus
mv /etc/apt/sources.list.d/varnish-4.0-plus.list /etc/apt/sources.list.d/varnish-4.1-plus.list
sed -i -e 's|4.0-plus|4.1-plus' /etc/apt/sources.list.d/varnish-4.1-plus.list
apt-get update
apt-get upgrade varnish-plus
VCL code only requires minimal changes. Check out this Varnish Cache page for more information.
Between versions 3.0 and 4.0, significant changes to VCL will make the transition more difficult than expected. Consult this upgrade documentation.
The most common substitutions can be done automatically using the Varnish 3 to 4 script.