NOTE: The present document is work in progress for the September 2018 release. The version number 6.1.0 is provisional and may change. See Upgrading to Varnish 6.0 for notes about the currently most recent Varnish release.

Upgrading to Varnish 6.1

Headline Changes

XXX

varnishd parameters

We have added the max_vcl parameter to set a threshold for the number of loaded VCL programs, since it is a common error to let previous VCL instances accumulate without discarding them. The remnants of undiscarded VCLs take the form of files in the working directory of the management process. Over time, too many of these may take up significant storage space, and administrative operations such as vcl.list may become noticeably slow, or even time out, when Varnish has to iterate over many files.

The default threshold in max_vcl is 100, and VCL labels are not counted against the total. The max_vcl_handling parameter controls what happens when you reach the limit. By default you just get a warning from the VCL compiler, but you can set it to refuse to load more VCLs, or to ignore the threshold.

Added the backend_local_error_holddown and backend_remote_error_holddown parameters. These define delays for new attempts to connect to backends when certain classes of errors have been encountered, for which immediate re-connect attempts are likely to be counter-productive. See the parameter documentation for details.

Changes to VCL

Headline VCL changes

XXX

VCL variables

req.ttl, req.grace and keep

req.ttl had been previously listed as deprecated, but it is now fully supported, since there are use cases that cannot be solved without it.

req.ttl and req.grace set upper bounds on the TTL and grace times that are permitted for the current request -- if these variables are set and the TTL/grace of a cache object is longer than their settings, then a new response is fetched from the backend, despite the presence of the response in the cache.

A common application is to set shorter TTLs when the backend is known to be healthy, so that responses are fresher when all is well. But if the backend is unhealthy, then use cached responses with longer TTLs to relieve load on the troubled backend:

sub vcl_recv {
      # ...
      if (std.healthy(req.backend_hint)) {
              # Get responses no older than 70s for healthy backends
              set req.ttl = 60s;
              set req.grace = 10s;
      }

      # If the backend is unhealthy, then permit cached responses
      # that are older than 70s.
}

The evaluation of the beresp.keep timer has changed a bit. keep sets a lifetime in the cache in addition to TTL for objects that can be validated by a 304 "Not Modified" response from the backend to a conditional request (with If-None-Match or If-Modified-Since). If an expired object is also out of grace time, it is no longer possible to deliver a "keep" object from vcl_hit. It is possible to validate a 304 candidate from vcl_miss.

The documentation in Grace mode and keep has been expanded to discuss these matters in greater depth, look there for more details.

beresp.filters and support for backend response processing with VMODs

The beresp.filters variable is readable and writable in vcl_backend_response. This is a space-separated list of modules that we call VFPs, for "Varnish fetch processors", that may be applied to a backend response body as it is being fetched. In default Varnish, the list may include values such as gzip, gunzip, esi and stream, depending on how you have set the beresp.do_* variables.

This addition makes it possible for VMODs to define VFPs to filter or manipulate backend response bodies, which can be added by changing the list in beresp.filters. VFPs are applied in the order given in beresp.filters, and you may have to ensure that a VFP is positioned correctly in the list, for example if it can only apply to uncompressed response bodies.

This is a new capability, and at the time of release we only know of test VFPs implemented in VMODs. Over time we hope that an "ecology" of VFP code will develop that will enrich the features available to Varnish deployments.

Other changes to VCL

  • The Host header in client requests is mandatory for HTTP/1.1, as proscribed by the HTTP standard. If it is missing, then builtin.vcl causes a synthetic 400 "Bad request" response to be returned.
  • You can now provide a string argument to return(fail("Foo!")), which can be used in vcl_init to emit an error message if the VCL load fails due to the return.

VMODs

Added the fnmatch(...) function to vmod_std, which you can use for shell-style wildcard matching (if you prefer that to regular expressions).

vmod_unix is now supported for SunOS and descendants. This entails changing the privilege set of the child process while the VMOD is loaded, see the documentation.

anything else

XXX

Other changes

  • varnishd(1):

    • Some VCL compile-time error messages have been improved, for example when a symbol is not found or arguments to VMOD calls are missing.
    • Varnish now won't rewrite the Content-Length header when responding to any HEAD request, making it possible to cache responses to HEAD requests independently from the GET responses (previously a HEAD request had to be a pass to avoid this rewriting).
    • If you have set .proxy_header=1 (to use the PROXYv1 protocol) for a backend addressed as a Unix domain socket (with a .path setting for the socket file), and have also defined a probe for the backend, then then the address family UNKNOWN is sent in the proxy header for the probe request. If you have set .proxy_header=2 (for PROXYv2) for a UDS backend with a probe, then PROXY LOCAL is sent for the probe request.
  • varnishlog(1) and vsl(7):

    • The contents of FetchError log entries have been improved to give better human-readable diagnostics for certain classes of backend fetch failures.
    • Debug log entries may also give more diagnostic information about session accept failures (failure to accept a client connection). These must be viewed in raw grouping, since accept failures are not part of any request/response transaction. The Debug message begins with the phrase "Accept failed".
    • When a backend is unhealthy, Backend_health now reports some diagnostic information in addition to the HTTP response and timing information.
    • The backend name logged for Backend_health is just the backend name without the VCL prefix (as appears otherwise for backend naming).
    • Added the log entry tag Filters, which gives a list of the filters applied to a response body (see beresp.filters discussed above).
  • varnishadm(1) and varnish-cli(7)

    • For a number of CLI commands, you can now use the -j argument to get a JSON response, which may help in automation. These include:

      • ping -j
      • backend.list -j
      • help -j
      • XXX...

      A JSON response in the CLI always includes a timestamp (epoch time in seconds with millisecond precision).

    • The backend.list command now lists both directors and backends, with their health status. The command now has a -v option for verbose output, in which detailed health states for each backend/director are displayed.

  • varnishstat(1) and varnish-counters(7):

    • We have added a number of counters to the VBE.* group to help better diagnose error conditions with backends:
      • VBE.*.unhealthy: the number of fetches that were not attempted because the backend was unhealthy
      • .busy: number of fetches that were not attempted because the .max_connections limit was reached
      • .fail: number of failed attempts to open a connection to the backend. Detailed reasons for the failures are given in the .fail_* counters (shown at DIAG level), and in the log entry FetchError. .fail is the sum of the values in the .fail_* counters.
      • .fail_eaccess, .fail_eaddrnotavail, .fail_econnrefused, .fail_enetunreach and .fail_etimedout: these are the number of attempted connections to the backend that failed with the given value of errno(3).
      • .fail_other: number of connections to the backend that failed for reasons other than those given by the other .fail_* counters.
      • .helddown: the number of connections not attempted because the backend was in the period set by one of the parameters backend_local_error_holddown or backend_remote_error_holddown
    • Similarly, we have added a series of counters for better diagnostics of session accept failures (failure to accept a connection from a client). As before, the sess_fail counter gives the total number of accept failures, and it is now augmented with the sess_fail_* counters. sess_fail is the sum of the values in sess_fail_*.
      • sess_fail_econnaborted, sess_fail_eintr, sess_fail_emfile, sess_fail_ebadf and sess_fail_enomem: the number of accept failures with the indicated value of errno(3). The varnish-counters man page, and the "long descriptions" shown by varnishstat, give possible reasons why each of these may happen, and what might be done to counter the problem.
      • sess_fail_other: number of accept failures for reasons other than those given by the other sess_fail_* counters. More details may appear in the Debug entry of the log (varnish-counters shows a varnishlog invocation that may help).
    • In curses mode, the information in the header lines (uptimes and cache hit rates) is always reported, even if you have defined a filter that leaves them out of the stats table.
    • Ban statistics are now reported more accurately (they had been subject to inconsistencies due to race conditions).
  • varnishtest(1) and vtc(7):

    • varnishtest and the vtc test script language now supports testing for haproxy as well as Varnish. The haproxy directive in a test can be used to define, configure, start and stop a haproxy instance, and you can also script messages to send on the haproxy CLI connection, and define expectations for the responses. See the haproxy section in VTC for details.
    • Related to haproxy support, you can now define a syslog instance in test scripts. This defines a syslog server, and allows you to test expectations for syslog output from a haproxy instance.
    • Added the -keepalive argument for client and server scripts to be used with the -repeat directive, which causes all test iterations to run on the same connection, rather than open a new connection each time. This makes the test run faster and use fewer ephemeral ports.
    • Added the -need-bytes argument for the process command, see VTC.
    • XXX
  • varnishhist(1):

    • The -P min:max command-line parameters are now optional, see varnishhist.
  • For all of the utilities that access the Varnish log -- varnishlog(1), varnishncsa(1), varnishtop(1) and varnishhist(1) -- it is now possible to set multiple -I and -X command-line arguments. So you can use multiple include and exclude filters that apply regular expressions to selected log messages.

  • Changes for developers:

    • As mentioned above, VMODs can now implement VFPs that can be added to backend response processing by changing beresp.filters. The interface for VFPs is defined in cache_filters.h, and the debug VMOD included in the distribution shows an example of a VFP for rot13.
    • The Varnish API soname version (for libvarnishapi.so) has been bumped to 2.0.0.
    • When PRIV_TASK and PRIV_TOP parameters are defined for a VMOD method or function, space for the struct vrt_priv object is allocated on the appropriate workspace before invocation -- the task workspace (client or backend) for PRIV_TASK, and the client workspace for PRIV_TOP. So it is no longer necessary for the VMOD code to do the allocation. The address of the allocated object is passed as the parameter to your implementation of the method or function. If the address is NULL, then allocation failed, probably due to workspace exhaustion (so your VMOD should check for that).
    • We have improved support for the STRANDS data type, which you may find easier to use than the varargs-based STRING_LIST. See vrt.h for details. vmod_blob has been refactored to use STRANDS, so you can look there for an example.
    • We have fixed a bug that had limited the precision available for the INT data type, so you now get the full 64 bits.
    • Portions of what had previously been declared in cache_director.h have been moved into vrt.h, constituting the public API for directors. The remainder in cache_director.h is not public, and should not be used by a VMOD intended for VRT ABI compatibility.
    • Python 3 is now preferred in builds, and will likely be required in future versions.

eof