..
	Copyright (c) 2017-2019 Varnish Software AS
	SPDX-License-Identifier: BSD-2-Clause
	See LICENSE file for full text of license

.. _whatsnew_upgrading_5.2:

%%%%%%%%%%%%%%%%%%%%%%%%
Upgrading to Varnish 5.2
%%%%%%%%%%%%%%%%%%%%%%%%

Varnish statistics and logging
==============================

There are extensive changes under the hood with respect to statistics
counters, but these should all be transparent at the user-level.

varnishd parameters
===================

The ``vsm_space`` and ``cli_buffer`` parameters are now deprecated and
ignored.  They will be removed in a future major release.

The updated shared memory implementation manages space automatically, so
it no longer needs ``vsm_space``. Memory for the CLI command buffer is now
dynamically allocated.

We have updated the documentation for :ref:`ref_param_send_timeout`,
:ref:`ref_param_idle_send_timeout`, :ref:`ref_param_timeout_idle` and
:ref:`ref_param_ban_cutoff`.

Added the debug bit ``vmod_so_keep``, see :ref:`ref_param_debug` and
the notes about changes for developers below.

Changes to VCL
==============

We have added a few new variables and clarified some matters. VCL
written for Varnish 5.1 should run without changes on 5.2.

Consistent symbol names
~~~~~~~~~~~~~~~~~~~~~~~

VCL symbols originate from various parts of Varnish: there are built-in
variables, subroutines, functions, and the free-form headers. Symbols
may live in a namespace denoted by the ``'.'`` (dot) character as in
``req.http.Cache-Control``. When you create a VCL label, a new symbol
becomes available, named after the label. Storage backends always have
a name, even if you don't specify one, and they can also be accessed in
VCL: for example ``storage.Transient``.

Because headers and VCL names could contain dashes, while subroutines or
VMOD objects couldn't, this created an inconsistency. All symbols follow
the same rules now and must follow the same (case-insensitive) pattern:
``[a-z][a-z0-9_-]*``.

You can now write code like::

  sub my-sub {
      new my-obj = my_vmod.my_constuctor(storage.my-store);
  }

  sub vcl_init {
      call my-sub;
  }

As you may notice in the example above, it is not possible yet to have
dashes in a vmod symbol.

Long storage backend names used to be truncated due to a limitation in
the VSC subsystem, this is no longer the case.

VCL variables
~~~~~~~~~~~~~

``req.hash`` and ``bereq.hash``
-------------------------------

Added ``req.hash`` and ``bereq.hash``, which contain the hash value
computed by Varnish for cache lookup in the current transaction, to
be used in client or backend context, respectively. Their data type
is BLOB, and they contain the raw binary hash.

You can use :ref:`vmod_blob(3)` to work with the hashes::

  import blob;

  sub vcl_backend_fetch {
      # Send the transaction hash to the backend as a hex string
      set bereq.http.Hash = blob.encode(HEX, blob=bereq.hash);
  }

  sub vcl_deliver {
      # Send the hash in a response header as a base64 string
      set resp.http.Hash = blob.encode(BASE64, blob=req.hash);
  }
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         