[master] 83b0190f0 first round of release docs
Nils Goroll
nils.goroll at uplex.de
Wed Mar 11 09:02:07 UTC 2020
commit 83b0190f091c39de625ae8de921a3648505aed3d
Author: Nils Goroll <nils.goroll at uplex.de>
Date: Wed Mar 11 09:57:34 2020 +0100
first round of release docs
I went through changes.rst and carried all aspects over to the release
docs which I considered relevant.
Please feel free to polish, I will not be able to get back to this today.
diff --git a/doc/changes.rst b/doc/changes.rst
index 478e3083c..bcd4659cb 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -92,8 +92,8 @@ Varnish Cache 6.4.0 (2019-09-16)
* The ``if-range`` header is now handled, allowing clients to conditionally
request a range based on a date or an ETag.
-* Introduced struct reqtop to hold information on the ESI top request
- and PRIV_TOP, fixed regression 3019_
+* Introduced ``struct reqtop`` to hold information on the ESI top
+ request and ``PRIV_TOP``, fixed regression 3019_
* Allow numerical expressions in VCL to be negative / negated
@@ -187,12 +187,12 @@ Varnish Cache 6.4.0 (2019-09-16)
* Fixed a case where ``send_timeout`` would have no effect when
streaming from a backend fetch, see bug 3189_
-* Added ``VSB_tofile()`` to ``libvarnishapi``, see 3238_
-
*NOTE* Users upgrading varnish should re-check ``send_timeout`` with
respect to long pass and streaming fetches and watch out for
increased session close rates.
+* Added ``VSB_tofile()`` to ``libvarnishapi``, see 3238_
+
.. _1853: https://github.com/varnishcache/varnish-cache/issues/1853
.. _2418: https://github.com/varnishcache/varnish-cache/issues/2418
.. _3009: https://github.com/varnishcache/varnish-cache/issues/3009
diff --git a/doc/sphinx/whats-new/changes-6.4.rst b/doc/sphinx/whats-new/changes-6.4.rst
index dd10e7e9c..642d52503 100644
--- a/doc/sphinx/whats-new/changes-6.4.rst
+++ b/doc/sphinx/whats-new/changes-6.4.rst
@@ -5,7 +5,7 @@ Changes in Varnish 6.4.0
%%%%%%%%%%%%%%%%%%%%%%%%
For information about updating your current Varnish deployment to the
-new version, see :ref:`whatsnew_upgrading_CURRENT`.
+new version, see :ref:`whatsnew_upgrading_6.4`.
A more detailed and technical account of changes in Varnish, with
links to issues that have been fixed and pull requests that have been
@@ -16,8 +16,13 @@ merged, may be found in the `change log`_.
varnishd
========
-Parameters
-~~~~~~~~~~
+bugs
+~~~~
+
+Numerous bugs have been fixed.
+
+Generic Parameter Handling
+~~~~~~~~~~~~~~~~~~~~~~~~~~
Some parameters have dependencies and those are better documented now. For
example :ref:`ref_param_thread_pool_min` can't be increased above
@@ -43,51 +48,133 @@ the error message::
(attempting to set param 'thread_pool_reserve' to '100')
-**XXX changes in -p parameters**
+Parameters
+~~~~~~~~~~
+
+* Raised the minimum for the ``vcl_cooldown`` parameter to 1 second.
+
+Changes in behavior
+~~~~~~~~~~~~~~~~~~~
+
+* The ``if-range`` header is now handled, allowing clients to conditionally
+ request a range based on a date or an ETag.
-Other changes in varnishd
-~~~~~~~~~~~~~~~~~~~~~~~~~
+* Output VCC warnings also for VCLs loaded via the ``varnishd -f``
+ option
Changes to VCL
==============
+* backend ``none`` was added for "no backend".
+
+ It can be used whenever a backend is needed for syntactical
+ reasons. The ``none`` backend will fail any attempt to use it.
+
+* ``std.rollback(bereq)`` is now safe to use
+
+* Deliberately closing backend requests through ``return(abandon)``,
+ ``return(fail)`` or ``return(error)`` is no longer accounted as a
+ fetch failure
+
+* Numerical expressions can now be negative or negated as in ``set
+ resp.http.o = -std.integer("-200");``
+
+* Overloaded the ``+=`` operator to also append to headers as in ``set
+ reqp.http.header += "add this"``
+
VCL variables
~~~~~~~~~~~~~
-**XXX new, deprecated or removed variables, or changed semantics**
-
-Other changes to VCL
-~~~~~~~~~~~~~~~~~~~~
+* Add more vcl control over timeouts with ``sess.timeout_linger``,
+ ``sess.send_timeout`` and ``sess.idle_send_timeout``
VMODs
=====
-**XXX changes in the bundled VMODs**
+* Imported ``vmod_cookie`` from `varnish_modules`_
+
+ The previously deprecated function ``cookie.filter_except()`` has
+ been removed during import. It was replaced by ``cookie.keep()``
varnishlog
==========
-**XXX changes concerning varnishlog(1) and/or vsl(7)**
+* A ``Notice`` VSL tag has been added
varnishadm
==========
-**XXX changes concerning varnishadm(1) and/or varnish-cli(7)**
+* New ``pid`` command in the Varnish CLI, to get the master and optionally
+ cache process PIDs, for example from ``varnishadm``.
varnishstat
===========
-**XXX changes concerning varnishstat(1) and/or varnish-counters(7)**
+* Add vi-stype CTRL-f / CTRL-b for page down/up to interactive
+ varnishstat
-varnishtest
-===========
+* The ``MAIN.sess_drop`` counter is gone.
-**XXX changes concerning varnishtest(1) and/or vtc(7)**
+* Added ``rx_close_idle`` counter for separate accounting when
+ ``timeout_idle`` is reached. Also, ``send_timeout`` is no longer
+ reported as "remote closed".
Changes for developers and VMOD authors
=======================================
-**XXX changes concerning VRT, the public APIs, source code organization,
-builds etc.**
+general
+-------
+
+* New configure switch: --with-unwind. Alpine linux appears to offer a
+ ``libexecinfo`` implementation that crashes when called by Varnish, this
+ offers the alternative of using ``libunwind`` instead.
+
+* The option ``varnishtest -W`` is gone, the same can be achieved with
+ ``varnishtest -p debug=+witness``. A ``witness.sh`` script is available
+ in the source tree to generate a graphviz dot file and detect potential
+ lock cycles from the test logs.
+
+* Introduced ``struct reqtop`` to hold information on the ESI top request
+ and ``PRIV_TOP``
+
+* New or improved Coccinelle semantic patches that may be useful for
+ VMOD or utilities authors.
+
+* Added ``VSLs()`` and ``VSLbs()`` functions for logging ``STRANDS`` to
+ VSL
+
+* Added ``WS_VSB_new()`` / ``WS_VSB_finish()`` for VSBs on workspaces
+
+* added ``v_dont_optimize`` attribute macro to instruct compilers
+ (only gcc as of this release) to not optimize a function
+
+* Added ``VSB_tofile()`` to ``libvarnishapi``
+
+VMODs
+-----
+
+* It is now possible for VMOD authors to customize the connection pooling
+ of a dynamic backend. A hash is now computed to determine uniqueness and
+ a backend declaration can contribute arbitrary data to influence the pool.
+
+* ``VRB_Iterate()`` signature has changed
+
+* ``VRT_fail()`` now also works from director code
+
+* ``body_status`` and ``req_body_status`` have been collapsed into one
+ type. In particular, the ``REQ_BODY_*`` enums now have been replaced
+ with ``BS_*``.
+
+* Added ``VRT_AllocStrandsWS()`` as a utility function to allocate
+ STRANDS on a workspace.
+
+log tools
+---------
+
+* Log records can safely have empty fields or fields containing blanks
+ if they are delimited by "double quotes". This was applied to
+ ``SessError`` and ``Backend_health``.
+
+ Authors of log handling tools might need to review this change.
*eof*
diff --git a/doc/sphinx/whats-new/upgrading-6.4.rst b/doc/sphinx/whats-new/upgrading-6.4.rst
index a65f41bef..1962681e2 100644
--- a/doc/sphinx/whats-new/upgrading-6.4.rst
+++ b/doc/sphinx/whats-new/upgrading-6.4.rst
@@ -4,26 +4,53 @@
Upgrading to Varnish 6.4.0
%%%%%%%%%%%%%%%%%%%%%%%%%%
-**XXX: how to upgrade from previous deployments to this
-version. Limited to work that has to be done for an upgrade, new
-features are listed in "Changes". Explicitly mention what does *not*
-have to be changed, especially in VCL. May include, but is not limited
-to:**
+Upgrading to Varnish 6.4 from 6.3 should not require any changes
+to VCL.
-* Elements of VCL that have been removed or are deprecated, or whose
- semantics have changed.
+This document contains information about other relevant aspects which
+should be considered when upgrading.
-* -p parameters that have been removed or are deprecated, or whose
- semantics have changed.
+varnishd
+--------
-* Changes in the CLI.
+* The hash algorithm of the ``hash`` director was changed, so backend
+ selection will change once only when upgrading.
-* Changes in the output or interpretation of stats or the log, including
- changes affecting varnishncsa/-hist/-top.
+ Users of the ``hash`` director are advised to consider using the
+ ``shard`` director instead, which, amongst other advantages, offers
+ more stable backend selection through consistent hashing.
-* Changes that may be necessary in VTCs or in the use of varnishtest.
+* We fixed a case where ``send_timeout`` had no effect when streaming
+ from a backend fetch.
-* Changes in public APIs that may require changes in VMODs or VAPI/VUT
- clients.
+ Users with long running backend fetches should watch out of
+ increases connection close rates and consider increasing
+ ``send_timeout`` appropriately.
+
+ The timeout can also be set per connection from vcl as
+ ``sess.send_timeout``.
+
+Statistics
+----------
+
+* The ``MAIN.sess_drop`` counter is gone. It should be removed from
+ any statistics gathering tools, if present
+
+* Added ``rx_close_idle`` counter for separate accounting when
+ ``timeout_idle`` is reached. Also, ``send_timeout`` is no longer
+ reported as "remote closed".
+
+vsl/logs
+--------
+
+* The ``Process`` timestamp for ``vcl_synth {}`` was wrongly issued
+ before the VCL subroutine, now it gets emitted after VCL returns for
+ consistency with ``vcl_deliver {}``.
+
+ Users of this timestamp should be aware that it now includes
+ ``vcl_synth {}`` processing time and appears at a different
+ position.
+
+* A ``Notice`` VSL tag has been added
*eof*
More information about the varnish-commit
mailing list