Varnish 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.

Minor version upgrades

Upgrades between minor versions, for example from 6.0.12r4 to 6.0.12r5, are considered stable and don’t require manual intervention.

Upgrade to Varnish Enterprise 6.0

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.

Fixing irrelevant/outdated VCL

Here are a few snippets you’ll find on the internet that you shouldn’t use.

Hit/miss detection

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.

Variable depending on backend health

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.
    } 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 to Varnish Enterprise 4.1

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.

Enterprise Linux:

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

Ubuntu 14.04 LTS (trusty):

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

Configuration update

VCL code only requires minimal changes. Check out this Varnish Cache page for more information.

Upgrade to Varnish Enterprise 4.0

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.