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 usually require manual intervention. The exceptions are called out in the release-specific notes below.
Release 6.0.18r1 was removed due to a regression; upgrade directly to
6.0.18r2 or later. The other 6.0.18r1 changes are retained, including a log rotation change: varnishncsa and varnishlog now reopen their -w output file on SIGUSR2, independent of whether they were started with -D. SIGHUP keeps its previous behavior only with -D. New deployments should prefer SIGUSR2; review your logrotate configuration when upgrading.
The MSE4 default_subdivisions setting changed its default from 4 to 1, and running with one subdivision is now the strong recommendation. Review your MSE4 configuration to align with the new default. The new per-category reorder_interval / default_reorder_interval settings replace the role of the global lru_interval parameter, which no longer has any effect on MSE4 caches. See the release notes.
This release hardens request-target handling (follow-up to security advisory VSV00018, fixed in 6.0.16r12):
https_scheme parameter is now enabled by default to process https:// absolute-form request-targets.req.url to start with /, unless the request method is CONNECT or OPTIONS (for OPTIONS, * is also allowed). Requests that were previously accepted may now receive a 400 response.ReqStart log record gained the protocol scheme as a fourth field, and varnishncsa emits https:// in %r for TLS connections. Review log parsers that consume these formats.See the release notes.
Deleted backends are no longer visible in varnishstat; the new gauges MAIN.n_backend_cold and MAIN.n_backend_deleted count them instead. Review dashboards that relied on the old behavior. The undocumented MSE4 configuration key eviction_batch_size is deprecated and has no effect; the memory governor’s eviction behavior was retuned and gained the memory_eviction_factor and memory_eviction_max_items parameters. See the release notes.
varnishstat now automatically switches to one-shot mode (-1) when standard output is not a terminal. Scripts that pipe varnishstat output may see different behavior.
Loading TLS certificates with duplicate or conflicting server name entries no longer fails; the certificate loaded last takes precedence for a conflicting name. Set the new tls_err_dup_servername parameter to on to restore the previous behavior of failing the load. See the release notes.
This release fixes a log format compatibility issue introduced in 6.0.14r6. Logs produced by 6.0.14r6 and 6.0.14r7 must only be read by log tools built for those specific releases, and tools from those releases may emit incorrect tags when reading logs from other versions. See the release notes.
The VHA6 limits framework was revamped: the max_requests_sec setting is replaced by the more granular broadcast_limit, broadcast_rate_limit and request_rate_limit controls. Setups already operating at full broadcast capacity may see higher VHA6 activity. Review your VHA configuration. See the release notes.
Two required migration steps in this release:
mkfs.mse4 -f -c <config> configure as part of the upgrade.See the release notes.
These releases updated the bundled cluster.vcl (version 2.1 as of r7). The changes are designed not to significantly change existing setups, but test or at least review the new cluster.vcl before deploying to production. See the release notes for 6.0.13r6 and 6.0.13r7.
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.