[master] aac0281 Start filling out "Upgrading to Varnish 5.1".
Geoff Simmons
geoff at uplex.de
Fri Mar 10 12:09:06 CET 2017
commit aac0281b6fa3fa1e51861e1e4bf6715934454ac0
Author: Geoff Simmons <geoff at uplex.de>
Date: Fri Mar 10 12:04:43 2017 +0100
Start filling out "Upgrading to Varnish 5.1".
So far this what I find in the commit log from varnish-5.0.0 until
the beginning of 2017. Some "biggies" still to be mentioned are:
* varnishd command-line options
* VCl type conversions, stringification etc.
* ranges?
diff --git a/doc/sphinx/whats-new/changes-5.1.rst b/doc/sphinx/whats-new/changes-5.1.rst
index 2e4e877..b1bf6ad 100644
--- a/doc/sphinx/whats-new/changes-5.1.rst
+++ b/doc/sphinx/whats-new/changes-5.1.rst
@@ -203,6 +203,8 @@ removing the ``ETag`` or ``Last-Modified`` headers in
``vcl_backend_response``, or by removing the If-* client request
headers in ``vcl_pass``.
+.. _whatsnew_changes_5.1_vtest:
+
Project tool improvements
~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/sphinx/whats-new/upgrading-5.1.rst b/doc/sphinx/whats-new/upgrading-5.1.rst
index 7291736..c6186f6 100644
--- a/doc/sphinx/whats-new/upgrading-5.1.rst
+++ b/doc/sphinx/whats-new/upgrading-5.1.rst
@@ -4,15 +4,143 @@
Upgrading to Varnish 5.1
%%%%%%%%%%%%%%%%%%%%%%%%
+varnishd command-line options
+=============================
+
+* Added the ``workuser`` parameter to the ``-j`` option.
+
+varnishd parameters
+===================
+
+* The size of the shared memory log is now limited to 4G-1b
+ (4294967295 bytes). This places upper bounds on the ``-l``
+ command-line option and on the ``vsl_space`` and ``vsm_space``
+ parameters.
+
+* Added ``clock_step`` and ``thread_pool_reserve`` (see
+ :ref:`ref_param_clock_step`, :ref:`ref_param_thread_pool_reserve`).
+
+* ``thread_pool_stack`` is no longer considered experimental, and is
+ more extensively documented, see :ref:`ref_param_thread_pool_stack`.
+
+* ``thread_queue_limit`` only applies to queued client requests, see
+ :ref:`ref_param_thread_queue_limit`.
+
+* All parameters are defined on every platform, including those that
+ that are not functional on every platform. Most of these involve
+ features of the TCP stack, such as ``tcp_keepalive_intvl``,
+ ``tcp_keepalive_probes``, ``accept_filter`` and ``tcp_fastopen``.
+ The unavailability of a parameter is documented in the output of the
+ ``param.show`` command. Setting such a parameter is not an error,
+ but has no effect.
+
+
Changes to VCL
==============
+Type conversions
+~~~~~~~~~~~~~~~~
+
+* When ``bereq.backend`` and ``beresp.backend`` are set to a director,
+ then they return an actual backend on subsequent reads if the
+ director resolves to a backend immediately, or the director otherwise.
+ When used in string context, they return the name of the director
+ or of the resolved backend.
+
+* DURATION types may be used in boolean contexts, and are evaluated as
+ false when the duration is less than or equal to zero, true
+ otherwise.
+
+Response codes
+~~~~~~~~~~~~~~
+
+Response codes 1000 or greater may now be set in VCL internally.
+``resp.status`` is delivered modulo 1000 in client responses.
+
+IP address comparison
+~~~~~~~~~~~~~~~~~~~~~
+
+IP addresses can now be compared for equality::
+
+ if (client.ip == remote.ip) {
+ call do_if_equal;
+ }
+
+The objects are equal if they designate equal socket addresses, not
+including the port number. IPv6 addresses are always unequal to IPv4
+addresses (the comparison cannot consider v4-mapped IPv6 addresses).
+
+The STEVEDORE type and storage objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The data type STEVEDORE for storage backends is now available in VCL
+and for VMODs. Storage objects with names of the form
+``storage.SNAME`` will exist in a VCL instance, where ``SNAME`` is the
+name of a storage backend provided with the ``varnishd`` command-line
+option ``-s``. If no ``-s`` option is given, then ``storage.s0``
+denotes the default storage. The object ``storage.Transient`` always
+exists, designating transient storage. See :ref:`guide-storage`, and
+the notes about ``beresp.storage`` and ``req.storage`` below.
+
+All VCL subroutines (except ``vcl_fini``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Added ``return(fail)`` to immediately terminate VCL processing. In
+ all cases but ``vcl_synth``, control is directed to ``vcl_synth``
+ with ``resp.status`` and ``resp.reason`` set to 503 and "VCL
+ failed", respectively. ``vcl_synth`` is aborted on ``return(fail)``.
+ ``vcl_fini`` is executed whan a VCL instance in unloaded (enters the
+ COLD state) and has no failure condition.
+
+Client-side VCL subroutines
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* ``req.ttl`` is deprecated, see :ref:`vcl(7)`.
+
+vcl_recv
+~~~~~~~~
+
+* Added ``req.storage``, which tells Varnish which storage backend to
+ use if you choose to save the request body (see
+ :ref:`func_cache_req_body`).
+
vcl_backend_response
~~~~~~~~~~~~~~~~~~~~
* Added ``return(pass(DURATION))`` to set an object to hit-for-pass,
see :ref:`whatsnew_changes_5.1_hitpass`.
+* The object ``beresp.storage`` of type STEVEDORE should now be used
+ to set a storage backend; ``beresp.storage_hint`` is deprecated and
+ will be removed in a future release. Setting ``beresp.storage_hint``
+ to a valid storage will set ``beresp.storage`` as well. If the
+ storage is invalid, ``beresp.storage`` is left untouched.
+
+When multiple storage backends have been defined with the ``-s``
+command-line option for varnishd, but none is explicitly set in
+``vcl_backend_response``, storage selection and the use of the nuke
+limit has been reworked (see :ref:`ref_param_nuke_limit`). Previously,
+a storage backend was tried first with a nuke limit of 0, and retried
+on failure with the limit configured as the ``-p`` parameter
+``nuke_limit``. When no storage was specfied, Varnish went through
+every one in round-robin order with a nuke limit of 0 before retrying.
+
+Now ``beresp.storage`` is initialized with a storage backend before
+``vcl_backend_response`` executes, and the storage set in
+``beresp.storage`` after its execution will be used. The configured
+nuke limit is used in all cases.
+
+vcl_backend_error
+~~~~~~~~~~~~~~~~~
+
+* ``beresp.backend.ip`` is only available when the backend connection
+ is open, and hence not in ``vcl_backend_error``.
+
+VMOD std
+~~~~~~~~
+
+* Added ``std.getenv()``, see :ref:`func_getenv`.
+
Other changes
=============
@@ -33,3 +161,25 @@ Other changes
* An entry with the ``TTL`` tag and the prefix ``HFP`` is logged to
record the duration set for hit-for-pass objects.
+
+* ``varnishncsa(1)``:
+
+ * Clarified the meaning of the ``%r`` formatter, see NOTES in
+ :ref:`varnishncsa(1)`.
+
+* ``varnishtest(1)``:
+
+ * Added the ``process`` and ``setenv`` commands, see :ref:`vtc(7)` .
+
+ * ``-reason`` replaces ``-msg`` to set the reason string for a
+ response (default "OK").
+
+ * Added ``-cliexpect`` to match expected CLI responses to regular
+ expressions.
+
+ * ``varnishtest`` can be stopped with the ``TERM``, ``INT`` of ``KILL``
+ signals, but not with ``HUP``. These signals kill the process group,
+ so that processes started by running tests are stopped.
+
+* Added the ``vtest.sh`` tool to automate test builds, see
+ :ref:`whatsnew_changes_5.1_vtest`.
More information about the varnish-commit
mailing list