[master] 437171d Document the vtc extensions for UDS in "Upgrading to 6.0".
Geoff Simmons
geoff at uplex.de
Mon Feb 26 19:27:10 UTC 2018
commit 437171de490251dd6cc10d7660e21a5300c92b0b
Author: Geoff Simmons <geoff at uplex.de>
Date: Mon Feb 26 20:26:08 2018 +0100
Document the vtc extensions for UDS in "Upgrading to 6.0".
diff --git a/doc/sphinx/whats-new/upgrading-6.0.rst b/doc/sphinx/whats-new/upgrading-6.0.rst
index 4f5d75a..d2af1ac 100644
--- a/doc/sphinx/whats-new/upgrading-6.0.rst
+++ b/doc/sphinx/whats-new/upgrading-6.0.rst
@@ -56,23 +56,65 @@ XXX: ...
Other changes
=============
-* ``varnishd(1)``:
+* ``varnishlog(1)``:
- * XXX ...
+ * Added a third field to the ``ReqStart`` log record that contains the
+ name of the listener address over which the request was received, see
+ :ref:`vsl(7)`.
* XXX ...
-* ``varnishstat(1)``:
+* ``varnishtest(1)``:
- * XXX ...
+ * The ``client -connect`` and ``server -listen`` commands in vtc
+ scripts now allow Unix domain sockets as addresses, recognized
+ when the argument begins with a ``/``.
- * XXX ...
+ A client attempts the connection immediately, so the socket file
+ must exist at the given path when the client is started, and the
+ client must be able to access it.
-* ``varnishlog(1)``:
+ The ``server -listen`` command must be able to create the socket
+ file when it executes ``bind(2)``. To make it easier for other
+ processes to connect to the socket, the server's umask is
+ temporarily set to 0 before the listen is attempted, to minimize
+ issues with permissions. No further attempted is made to set the
+ socket's permissions.
- * Added a third field to the ``ReqStart`` log record that contains the
- name of the listener address over which the request was received, see
- :ref:`vsl(7)`.
+ To test a Varnish instance listening at a UDS, just use the
+ ``varnish -arg`` command with the appropriate settings for the
+ ``-a`` command line argument, see :ref:`varnishd(1)`.
+
+ A convenient location for socket files to be used in a test is the
+ temporary directory created by ``varnishtest`` for each test,
+ whose path is held in the macro ``${tmpdir}``. So this is a common
+ idiom for tests that involve UDSen::
+
+ varnish v1 -arg "-a ${tmpdir}/v1.sock" -vcl { ... } -start
+
+ client c1 -connect "${tmpdir}/v1.sock" { ... } -run
+
+ When a Varnish instance in a vtc test is listening at a UDS, then
+ its ``vN_*`` macros are set like this:
+
+ * ``v1_addr``: ``/path/to/socket``
+ * ``v1_port``: ``-`` (hyphen)
+ * ``v1_sock``: ``/path/to/socket -``
+
+ When a server ``s1`` is listening at a UDS:
+
+ * ``s1_addr``: ``0.0.0.0``
+ * ``s1_port``: ``0``
+ * ``s1_sock``: ``/path/to/socket``
+
+ The vtc variables ``remote.ip`` and ``remote.port``, which can be
+ used in ``expect`` expressions for both server and client scripts,
+ are set to ``0.0.0.0`` and ``0``, respectively, when the peer
+ address is a UDS.
+
+ We have added the variable ``remote.path`` as a counterpart to the
+ other two. Its value is the path when the peer address is a UDS,
+ and NULL otherwise (matching ``<undef>`` in the latter case).
* XXX ...
More information about the varnish-commit
mailing list