Migrating from old versions¶
This page is a continuous work in progress, and contributions to it are welcome. Do not hesitate to open a pull request.
Upgrading should be easy¶
First and foremost, we make every effort to keep upgrades as seamless as possible. A long time ago, a big change happened between Varnish Cache 3.x and 4.x, which forced many users to rewrite large parts of their VCL, and we have since been careful to not demand huge changes again.
That said, we want to keep Vinyl Cache great, and this requires to sometimes throw old concepts overboard and make changes. And sometimes we are forced externally to change even the fundamentals, such as the project name.
Versions¶
We try to follow “somehow semantic” versions, with major version bumps when we break something existing in some meaningful way, such as parameters or bundled VMOD functions being removed.
We have a lot of documentation¶
To help users migrate from older versions, we write an Upgrading guide for each Vinyl Cache release. These guides should mention all aspects of each release which are relevant compared to the previous release. So, to upgrade from one release to another, we recommend to go through all the Upgrading guides for all intermediate releases.
We know that this can be a daunting task, but still we recommend to at least get an overview and look out for particularly relevant aspects, such that when errors pop up, you might remember a change being mentioned in the documentation…
Note that the Upgrading page also contains the Changes in … documents, which are more comprehensive than the Upgrading to … guides and also document new and improved features. You should not need to know these to perform a successful upgrade, but we still recommend to read them.
No silent changes¶
In general, we try to avoid “silent” changes, that is, we try to make sure that removed or changed behavior triggers an error message if used the old way. One particular way of marking changes which would otherwise be silent is the VCL version.
For example, with introduction of Unix Domain Socket support in 6.0, client.ip
could suddenly contain the value 0.0.0.0. To avoid this getting unnoticed,
we tied Unix Domain Socket support to VCL Version 4.1.
Versions of the VCL language¶
Currently there are two versions of the VCL language, 4.0 and 4.1, and they are only slightly different.
This table shows which versions of the VCL language are supported in different versions of Varnish:
Varnish version |
Supported VCL versions |
|---|---|
4.0 |
4.0 |
4.1 |
4.0 |
5.0 |
4.0 |
5.1 |
4.0 |
5.2 |
4.0 |
6.0 LTS |
4.0, 4.1 |
6.1 |
4.0, 4.1 |
6.2 |
4.0, 4.1 |
6.3 |
4.0, 4.1 |
6.4 |
4.0, 4.1 |
6.5 |
4.0, 4.1 |
6.6 |
4.0, 4.1 |
7.0 |
4.0, 4.1 |
7.1 |
4.0, 4.1 |
7.2 |
4.0, 4.1 |
7.3 |
4.0, 4.1 |
7.4 |
4.0, 4.1 |
7.5 |
4.0, 4.1 |
7.6 |
4.0, 4.1 |
7.7 |
4.0, 4.1 |
8.0 |
4.0, 4.1 |