[5.2] 1156b8e Some work on the release docs
PÃ¥l Hermunn Johansen
hermunn at varnish-software.com
Fri Sep 15 11:17:21 UTC 2017
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Wed Sep 13 08:46:46 2017 +0000
Some work on the release docs
diff --git a/doc/sphinx/whats-new/changes-5.2.rst b/doc/sphinx/whats-new/changes-5.2.rst
index 4804a86..5688246 100644
@@ -3,26 +3,15 @@
Changes in Varnish 5.2
-The export of statistics counters via shared memory has been
-overhauled to get rid of limitations which made sense 11 years
-ago but not so much now.
-Statistics counters are now self-describing in shared memory,
-paving the way so that VMODs or maybe even VCL can define
-counters in the future, and have them show up in varnishstat
-and other VSC-API based programs.
+Varnish 5.2 is mostly changes under the hood so most varnish
+installations will be able to upgrade with no modifications.
New VMODs in the standard distribution
-*XXX: introductory paragraphs about new VMODs*
+We have added three new VMODs to the varnish project.
@@ -30,7 +19,7 @@ VMOD blob
We have added the variables ``req.hash`` and ``bereq.hash`` to VCL,
which contain the hash value computed by Varnish for the current
request, for use in cache lookup. Their data type is BLOB, which
-represents arbitrary data of any length -- the new variables contain
+represents opaque data of any length -- the new variables contain
the raw binary hashes.
This is the first time that an element of standard VCL has the BLOB
@@ -39,17 +28,34 @@ have added VMOD blob to facilitate their use. In particular, the VMOD
implements binary-to-text encodings, for example so that you can
assign the hash to a header as a base64 or hex string. It also
provides some other utilities such as getting the length of a BLOB or
-testing BLOBs for equality. See :ref:`vmod_blob(3)`.
+testing BLOBs for equality.
-*XXX: about VMOD purge*
+*XXX: DRIDI ? about VMOD purge*
-*XXX: about VMOD vtc*
+As long as we have had VMODs, we had an internal vmod called ``vmod_debug``
+which were used with ``varnishtest`` to exercise the VMOD related parts of
+``varnishd``. Over time this vmod grew other useful functions for writing
+We only distribute ``vmod_debug`` in source releases, because it has some
+pretty evil functionality, for instance ``debug.panic()``.
+We have split the non-suicidal test-writing stuff from ``vmod_debug``
+into a new ``vmod_vtc``, which is included in binary releases from
+now on, in order to make it easier for people to use ``varnishtest``
+to test local configurations, VMODs etc.
XXX: Any other headline changes ...
@@ -61,11 +67,34 @@ News for authors of VMODs and Varnish API client applications
*XXX: such news may include:*
+*XXX: DRIDI ?*
VSM/VSC API changes
-The rewrite of the VSM/VSC code has similified the API and
-made it much more robust, and code calling into these APIs
+The export of statistics counters via shared memory has been
+overhauled to get rid of limitations which made sense 11 years
+ago but not so much now.
+A set of statistics counters are now fully defined in a ``.vsc``
+file which is processed by the ``vsctool.py`` script into a .c and
+.h file, which is compiled into the relevant body of code.
+This means that statistics counters are now self-describing in
+shared memory, and ``varnishstat`` or other VSC-API using programs
+have no compiled in knowledge about which counters exist or how
+to treat them.
+This paves the way for VMODs or maybe even VCL to define
+custom counters, and have them show up in varnishstat and
+other VSC-API based programs just like the rest of the counters.
+The rewrite of the VSM/VSC code similified both APIs and
+made them much more robust but code calling into these APIs
will have to be updated to match.
The necessary changes mostly center around detecting if the
@@ -74,10 +103,10 @@ varnishd management/worker process has restarted.
In the new VSM-api once setup is done, VSM_Attach() latches
on to a running varnishd master process and stays there.
-VSM_Status() returns information about the master and worker
-process, if they are running, if they have been restarted
-(since the previous call to VSM_Status()) and updates the
-in-memory list of VSM segments.
+VSM_Status() updates the in-memory list of VSM segments, and
+returns information about the master and worker proces:
+Are they running? Have they been restarted? Have VSM segments
Each VSM segment is now a separate piece of shared memory
and the name of the segment can be much longer now.
@@ -89,6 +118,6 @@ should be called to release the segment again.
All in all, this should be simpler and more robust now.
-* *XXX: changes in VRT*
+*XXX: changes in VRT*
diff --git a/doc/sphinx/whats-new/upgrading-5.2.rst b/doc/sphinx/whats-new/upgrading-5.2.rst
index cc70923..2164e32 100644
@@ -7,8 +7,8 @@ Upgrading to Varnish 5.2
Varnish statistics and logging
-*XXX: anything new for users or admins concerning statistics,*
-*varnishstat, logging etc*
+There are extensive changes under the hood with respect to statistics
+counters, but these should all be transparent at the user-level.
More information about the varnish-commit