Varnish 5: new features and improvements

Varnish 5 was released on September 15th 2016 and is the successor of version 4.1. So this is supposed to be major release that has new features and tons of improvements.

The reality is that Varnish 5 only offers a couple of interesting new features. The upside is that are few breaking changes.

The video

Have a look at the video I made, it summarizes the notable things about this “major” release.


Why version 5 and not 4.2?

Let’s face it: with only a few breaking changes, this release could have easily been called Varnish 4.2, and yet they went all the way and called it 5.0. In my opinion there are 2 reasons that could justify this major release:

  • The fact that Varnish no longer has feature releases, but switched to a time-based release schedule.
  • The “experimental” support for HTTP/2, which is admittedly a major feature.

Let’s not lose our shit over a version number, it’s just a number. And hey: every 6 months we’re getting some new features, so that’s good news!

The next release of Varnish 5 is planned for March 15th 2017 and will probably be called Varnish 5.1. It’s just a matter of getting used to the fact that we’re no longer waiting for a major feature, and just get what they’ve got when the new release arrives.

Have a look at the releases page on the Varnish website for more information about past, present and future releases.

Please also read the release notes for the Varnish 5 release.

HTTP/2 support in Varnish 5

The major talking point is of course “experimental” support for HTTP/2, or H2 as people tend to call it.

At Varnishcon in June, Poul-Henning Kamp (the Varnish project lead) confirmed that HTTP/2 would be part of the upcoming Varnish 5 release, or it least “some of it”.

I have tested it and it seems to work fine, however the Varnish community insists that it is not production ready.

What about TLS?

Yeah, the elephant in the room: TLS support.

The web browser community has decided that every HTTP/2 call should happen over an encrypted connection using TLS.

On the other hand you have the Varnish community, and more specifically Poul-Henning Kamp, who stands his ground and refuses to implement TLS in Varnish. If you want to know why, just have look at the “SSL revisited” post by Poul-Henning.

TLS terminators

To tackle this TLS issue, Varnish actively promotes the use of TLS terminators. Varnish also offers PROXY protocol support since version 4.1. This protocol makes it easier to determine the “real IP address” of the original client.

By offering PROXY support, they facilitate to use of other proxies (e.g. TLS terminators) to put in front of Varnish.  And by promoting TLS terminators, they’re “outsourcing” the problem to someone else. You can also say that TLS is not their core business and that crypto is hard and should be managed by specialized software.

You can terminate TLS with various pieces of (open source) software, these are a couple of examples:

  • HAProxy
  • Pound
  • Stud
  • Hitch
  • Nginx
  • Stunnel

The Varnish community actively tries to tackle the TLS issue by maintaining the Hitch project. Hitch is a minimalistic TLS terminator that supports both HTTP/2 and PROXY. It’s easy to set up and connects easily with Varnish.

The shard director

Varnish 5 does more than just HTTP/2. The new Varnish release also features a new director: the shard director.

Directors are responsible for loadbalancing, they group several backends and present them as one, and they have a decision making strategy to decide which request goes to what backend.

The shard director uses a consistent hashing algorithm to link a request to a specific backend: every time a request hits Varnish and the request is sent to the backend, the same backend is used.

Hit-for-pass becomes hit-for-miss

This is a behavior change, rather than a new feature. Hit-for-pass is an internal Varnish concept that does negative caching for items that aren’t considered cacheable.

This means that non-cacheable objects will be added to a blacklist. Requests for items in the hit-for-pass cache will be sent to the backend immediately for a set amount of time. This is usually 120 seconds.

So for the next 120 seconds, this item cannot be served from cache, or stored in cache, even if the resource is now cacheable. Safe to say this is a source of confusion for many, even for me back in the day.

Varnish 5 has changed this behaviour by turning into hit-for-miss. This means that non-cacheable content will cause a miss, but as soon as the resource is cacheable again, it will be stored in cache and served from cache.

We’ve changed from “the uncacheable case wins” to “the cacheable case wins” or from hit-for-pass to hit-for-miss.

Backend PROXY protocol support

I already mentioned that PROXY protocol is supported by Varnish since version 4.1. But that’s only at the client-level.

But as of Varnish 5, you can now send PROXY protocol requests to your backend. Of course, your backend needs to support it.

By using end-to-end PROXY support, the IP address of the original client will be sent to the backend, regardless of the number of proxies.

If you’re planning to use HTTP/2, you’ll need a TLS terminator and this feature will make total sense.

Here’s how you enable it:

By adding the proxy_header attribute to your backend definition, Varnish will start using the PROXY protocol for backend communication. The value of proxy_header is either 1 or 2. These values represent the PROXY protocol version.

Be sure to check which PROXY protocol version your backend supports.

Multiple VCL files and VCL label jumping

A final feature I’ll discuss is support for multiple VCL files in parallel. This doesn’t seem like a novelty since previous versions of Varnish already supported multiple VCL files.

The main difference is that Varnish 5 allows you to label your VCL files and load them on-the-fly from within your main VCL file.

In order to load these VCL files a new return state has been introduced:


As soon as the Varnish finite state machine sees a VCL return, it will immediately load that VCL file.

Here’s an example where I load and label multiple VCL files:

These commands will be executed in the Varnish CLI. Now we have 2 labels we can use in our VCL:

  • blog_vcl that refers to /etc/varnish/blog.vcl
  • talks_vcl that refers to /etc/varnish/talks.vcl

A good use case is offering support for multiple websites that are processed by the same Varnish instance. In that case you’ll check the hostname and load the VCL files accordingly.

Here’s how you do that:



Although this release is far from mindblowing, it is a very solid foundation for future releases. And that I’m excited about!

I’ll test Varnish 5.0 and I’m looking forward to a stable implementation of HTTP/2. I’ll keep an eye out for feedback of the current HTTP/2 implementation and I’m curious if people will have the guts to put it in production.

The only other reason I would upgrade to version 5 is to have backend PROXY support. And maybe even for the hit-for-miss feature.

Subscribe and follow me

Please subscribe to my channels and follow me on social media if you want to stay in the loop.