Upgrading to Vinyl Cache 9.0

This document only lists breaking changes that you should be aware of when upgrading from Varnish Cache 8.x to Vinyl Cache 9.0. For a complete list of changes, please refer to the change log and Changes in Vinyl Cache 9.0.

Together with this release, we also announce a security issue, see vsv18.

Name change

As you may have noticed, the project name has been changed from Varnish Cache to Vinyl Cache, and this is the first release under the new name. All binaries, documentation, and other references have been updated to reflect this change. Starting from this release, the main program is now vinyld instead of varnishd. Similarly, all tools were renamed accordingly (vinyllog, vinylncsa.. etc).

Vinyl Cache is the official project name, and we use vinyl-cache or Vinyl-Cache with a dash only where a space is not technically possible, such as in domain names and certain HTTP headers, or breaking with conventions, such as in filenames. If neither of these work, the last resort is Vinyl_Cache or vinyl_cache. Any other spelling should be avoided. A short ASCII representation of the project name is \(, which resembles our new logo.

Our homepage is now https://vinyl-cache.org

Our mastodon account is https://fosstodon.org/@vinyl_cache

We have left github and the core code repository is now at https://code.vinyl-cache.org/vinyl-cache/vinyl-cache

For more information on the repository move see https://vinyl-cache.org/organization/moving.html

While the name change might look mostly cosmetic at first, besides, obviously, needing to start vinyld instead of varnishd, and running, for example, vinylstat instead of varnishstat, there are some less obvious consequences, so we recommend to read through the following changes. Other than that, the upgrade should work as usual and, in particular, VCL should require adjustments only in rare cases.

Affecting multiple programs

The environment variable VARNISH_DEFAULT_N is now VINYL_DEFAULT_N

The directory structure has been changed. Sparing details like differences where etc and lib reside, the changes are:

  • include/varnish is now include/vinyl-cache

  • lib/varnish is now lib/vinyl-cache

  • share/doc/varnish is now share/doc/vinyl-cache

  • share/varnish is now share/vinyl-cache

  • etc/varnish is now etc/vinyl-cache

  • var/varnish is now var/vinyl-cache if used, otherwise the state directory is most likely /var/run

Most notable of these is the default VCL location which, for most users, will change from /etc/varnish to /etc/vinyl-cache.

vinyld

Unix user changes

The Unix user and group used by the unix and linux jails have been changed from varnish to vinyl. Users transitioning from Varnish Cache 8.0 might find this snippet helpful to delete and create the relevant users/groups (see also vinyld(1)):

userdel varnish || true
userdel vcache || true
userdel varnishlog || true # to remove reference to varnish group
groupdel varnish || true

groupadd vinyl
useradd -g vinyl -d /nonexistent -s /bin/false \
  -c "Vinyl Cache Daemon User" vinyl
useradd -g vinyl -d /nonexistent -s /bin/false \
  -c "Vinyl Cache Worker User" vcache
useradd -g vinyl -d /nonexistent -s /bin/false \
  -c "Vinyl Log User" vinyllog

Path changes

The default vcl_path has changed

  • from: ${sysconfdir}/varnish:${datadir}/varnish/vcl

  • to: ${sysconfdir}/vinyl-cache:${datadir}/vinyl-cache/vcl

So, most notably, for a default installation, the location for VCL files is now /etc/vinyl-cache.

The default vmod_path has changed

  • from: ${libdir}/varnish/vmods

  • to: ${libdir}/vinyl-cache/vmods

Default header changes

The default Server and Via headers have been changed from Varnish to Vinyl-Cache.

The X-Varnish header is now X-Vinyl

VSV00018

The handling of HTTP/1.1 requests to an “absolute form” URI has been fixed to also cover the case where the absolute form has an empty path component:

Previously, a request with an empty path like GET http://example.com HTTP/1.1 would cause req.url to contain http://example.com and the Host: header to remain unchanged. This has now been fixed:

  • req.url gets set to * if the request method is OPTIONS and to / otherwise

  • The Host: header gets set to example.com.

For an empty path with query parameters like http://example.com?/foo, req.url gets normalized by addition of the leading slash. For the example, req.url would contain /?/foo.

For requests to an absolute form URI, the host field is now required. Requests without a host field are rejected with a Status 400 error.

The built-in VCL has been changed to require req.url to start with /, unless the request method is CONNECT or OPTIONS. For CONNECT, no additional check is applied, but CONNECT is not allowed by default. For OPTIONS, * is also allowed.

VCL variable beresp.storage_hint removed

The VCL variable beresp.storage_hint has been removed. If you were using this variable in your VCL, you will need to remove any references to it.

VCL variable req.ttl deprecated

The req.ttl variable has been renamed to req.max_age for clarity. req.ttl is retained as an alias and continues to work, but is now deprecated and will be removed in a future version of Vinyl Cache. You should update your VCL to use req.max_age instead.

Content-Length handling for requests without body

For requests having no request body, the Content-Length header will now only be unset when the request method is one of: GET, HEAD, DELETE, OPTIONS, TRACE. For other methods, a Content-Length header with value 0 will be set instead. This may affect backends that are sensitive to the presence of the Content-Length header.

vinylncsa

In vinylncsa formats, %{Varnish:....} has been replaced with %{Vinyl:....}

Upgrade notes for VMOD developers

Name change

The libvarnishapi library is now libvinylapi.

The pkg-config file varnishapi.pc is now vinylapi.pc.

The autoconf macro file varnish.m4 is now vinyl.m4, and the VARNISH_* macros are now called VINYL_*.

In vsc files, varnish_vsc is now vinyl_vsc.

On a git repository with an autotools-based VMOD where file names do not contain white space, the following one-liner should produce at least haft-decent results:

sed -i 's/varnishtest/vtest/g;s/varnish/vinyl/g;s/VARNISH/VINYL/g;s/Varnish.Cache/Vinyl Cache/g;s/Varnish/Vinyl Cache/g;' $(git ls-files)

Please note that these results should only be taken as the basis for manual edits!

The most important changes are:

  • In configure.ac, replace VARNISH_ macros with VINYL_.

  • In Makefile.ams, replace VARNISHAPI_ with VINYLAPI_ and VARNISH_ with VINYL_.

  • In vtc files, replace varnishtest with vtest and varnish with vinyl.

VSL_Setup() replaced with VSL_Init() and VSL_Alloc()

VSL_Setup() has been replaced with two new functions:

  • VSL_Init() to initialize caller-provided space as a VSL buffer

  • VSL_Alloc() to allocate the default vsl_buffer on the heap

VSL_Free() has been added to free the memory allocated by VSL_Alloc().

The coccinelle script tools/coccinelle/vsl_setup_retire.cocci can be used to partially automate the transition (it does not add VSL_Free() calls).

eof