Changes in Varnish 6.3

For information about updating your current Varnish deployment to the new version, see Upgrading to Varnish 6.3.

A more detailed and technical account of changes in Varnish, with links to issues that have been fixed and pull requests that have been merged, may be found in the change log.



A new pipe_sess_max parameter allows to limit the number of concurrent pipe transactions. The default value is zero and means unlimited, for backwards compatibility.

Other changes in varnishd

The transferred bytes accounting for HTTP/2 sessions is more accurate: ReqAcct log records no longer report a full delivery if a stream did not complete.

The meaning of VCL temperature changed for the auto state: it used to automatically cool down a VCL transitioning from active to available, but that VCL would remain cold. It now works in both directions, and such a cold VCL keeps the auto state and may be used or labelled immediately without an explicit change of state to warm.

As a result, a VCL with the cold state will no longer warm up automatically.

The management of counters, and in particular dynamic counters (for example appearing or disappearing when a VCL is loaded or discarded), has seen significant performance improvements and setups involving a large amount of backends should be more responsive.

Changes to VCL

VCL variables

The timeout_idle parameter can be overriden in VCL using the sess.timeout_idle variable.

Other changes to VCL

A new error transition to vcl_backend_error allows to purposely move to that subroutine. It is similar to the synth transition and can optionally take arguments. The three following statements are equivalent:

return (error);
return (error(503));
return (error(503, "Service Unavailable"));

The error transition is available in vcl_backend_fetch and vcl_backend_response. Using an explicit error transition in vcl_backend_fetch does not increment the MAIN.fetch_failed counter.

It is possible to import the same VMOD twice, as long as the two imports are identical and wouldn’t otherwise conflict. This allows for example included VCL files to import the VMODs they need without preventing the including VCL to also perform the same import.

Similarly, it is now possible to include a VMOD under a different name:

import directors as dir;

sub vcl_init {
    new rr = dir.round_robin();

This can be useful for VMODs with a long name, or VMODs that could use a more expressive name in VCL code.

The built-in VCL turns the Host header lowercase in vcl_recv to improve its hashing later in vcl_hash since domain names are case insensitive.


std.ip() now takes an optional STRING argument to specify a port number or service name.

See: IP ip(STRING s, [IP fallback], BOOL resolve=1, [STRING p])


The syntax for VSL queries, mainly available via the -q option with varnishlog and similar tools, has slightly changed. Previously and end of line in a query would be treated as a simple token separator so in a script you could for example write this:

varnishlog -q '
    tag operator operand or
    tag operator operand or
    tag operator operand
' -g request ...

From now on, a query ends at the end of the line, but multiple queries can be specified in which case it acts as if the or operator was used to join all the queries.

With this change in the syntax, the following query:

varnishlog -q '

is equivalent to:

varnishlog -q '(query1) or (query2)'

In other words, if you are using a Varnish utility to process transactions for several independent reasons, you can decompose complex queries into simpler ones by breaking them into separate lines, and for the most complex queries possibly getting rid of parenthesis you would have needed in a single query.

If your query is complex and long, but cannot appropriately be broken down into multiple queries, you can still break it down into multiple lines by using a backslash-newline sequence:

tag operator operand and \
tag operator operand and \
tag operator operand

See vsl-query for more information about this change.

With this new meaning for an end of line in a query it is now possible to add comments in a query. If you run into the situation where again you need to capture transactions for multiple reasons, you may document it directly in the query:

varnishlog -q '
    # catch varnish errors

    # catch client errors
    BerespStatus >= 400 and BerespStatus < 500

    # catch backend errors
    BerespStatus >= 500
' -g request

This way when you later revisit a complex query, comments may help you maintain an understanding of each individual query. This can become even more convenient when the query is stored in a file.

varnishlog(1), varnishncsa(1) and others

Our collection of log-processing tools gained the ability to specify multiple -q options. While previously only the last -q option would prevail you may now pass multiple individual queries and filtering will operate as if the or operator was used to join all the queries.

A new -Q option allows you to read the query from a file instead. It can also be used multiple times and adds up to any -q option specified.

Similar to -c or -b for client or backend transactions, varnishncsa(1) can take a -E option to include ESI transactions.

BackendStart log records are no longer used, but newer versions of log utilities should still recognize deprecated records. It remains possible to read logs written to a file with an older version of varnishlog(1), and that backward compatibility officially goes as far as Varnish 6.0.0 even though it may be possible to read logs saved from older releases.

Debug records are no longer logged by default and can be removed from the vsl_mask parameter to appear in the logs. Since such records are not meant for production they are only automatically enabled by varnishtest(1).


A new MAIN.n_pipe gauge keeps track of the number of ongoing pipe transactions.

A new MAIN.pipe_limited counter keeps track of how many times a transaction failed to turn into a pipe because of the pipe_sess_max parameter.


A client can now use the -method action for txreq commands to specify the request method. This used to be done with -req which remains as an alias for compatibility.

A client or server may use the -bodyfrom action for respectively txreq or txresp commands to send a body from a file.

An HTTP/2 client or server can work with gzip content encoding and has access to -gzipbody and -gziplen.

Changes for developers and VMOD authors

The most notable change for VMOD developers is the deprecation of string lists in favor of strands.

As usual, new functions were added to VRT, and others were changed or removed. See vrt.h for a list of changes since the 6.2.0 release.

We continue to remove functions from VRT that weren’t meant to be used by VMOD authors and were only part of the VMOD infrastructure code.