[master] 14b62912a Document VEXT

[Poul-Henning Kamp]

commit 14b62912a8d5ffe489005282144323df5165c076
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date:   Wed Sep 7 09:02:44 2022 +0000

    Document VEXT

diff --git a/doc/sphinx/reference/index.rst b/doc/sphinx/reference/index.rst
index 09ae6342d..cb50ea6ff 100644
--- a/doc/sphinx/reference/index.rst
+++ b/doc/sphinx/reference/index.rst
@@ -97,6 +97,7 @@ For Developers & DevOps
 
 	Shell tricks <shell_tricks>
 	VMODS - Extensions to VCL <vmod>
+	VEXT - Varnish Extensions <vext>
 	VSM - Shared memory use <vsm>
 	VDIR - Backends & Directors <directors>
 	VCLI - CLI protocol API <cli_protocol>
diff --git a/doc/sphinx/reference/vext.rst b/doc/sphinx/reference/vext.rst
new file mode 100644
index 000000000..6570947d0
--- /dev/null
+++ b/doc/sphinx/reference/vext.rst
@@ -0,0 +1,29 @@
+..
+	Copyright (c) 2010-2021 Varnish Software AS
+	SPDX-License-Identifier: BSD-2-Clause
+	See LICENSE file for full text of license
+
+.. _ref-vext:
+
+%%%%%%%%%%%%%%%%%%%%%%%%%
+VEXT - Varnish Extensions
+%%%%%%%%%%%%%%%%%%%%%%%%%
+
+A Varnish Extension is a shared library, loaded into the worker
+process during startup, before privilges are dropped for good.  This
+allows a VEXT to do pretty much anything it wants to do in the
+worker process.
+
+A VEXT can (also) contain a VMOD, and it will work just like any
+other VMOD, which also means that VMODs can be loaded as VEXTs.
+
+The VEXTs are loaded in the child process, in the order they are
+specified on the commandline, after the ``heritage`` has been
+established, but before stevedores are initialized and jail
+privileges are dropped.
+
+There is currently no ``init`` entrypoint defined, but a
+VEXT can use a static initializer to get activated on loading.
+
+If those static initializers want to bail out, ``stderr`` and
+``exit(3)`` can be used to convey diagnostics.
diff --git a/doc/sphinx/reference/vtla.rst b/doc/sphinx/reference/vtla.rst
index 0a6b04543..ab017c523 100644
--- a/doc/sphinx/reference/vtla.rst
+++ b/doc/sphinx/reference/vtla.rst
@@ -59,6 +59,9 @@ VEND
 VEV
     Varnish EVent -- library functions to implement a simple event-dispatcher.
 
+VEXT
+    Varnish Extension -- Shared library loaded into the child process.
+
 VGB
     Varnish Governing Board -- May or may not exist.
     If you need to ask, you are not on it.
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index cc4b2ea61..f6745bb4e 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -23,7 +23,16 @@ varnishd
 Extensions
 ~~~~~~~~~~
 
-TODO: VEXT
+From the very first days of Varnish, we have been talking about having
+an extension points for "more advanced stuff" and we did, by and large,
+keep a place ready for it in the overall architecture.
+
+Now a credible use-case finally appeared, and we have implemented
+"Varnish Extensions" (VTLA: "VEXT"), which can both be used to load
+ambient VMODs and to implement entirely new functionaly, for instance
+stevedores.
+
+See :ref:`ref-vext` in the reference manual for more information.
 
 Parameters
 ~~~~~~~~~~
@@ -43,8 +52,11 @@ parameters. The latter still exist as deprecated aliases.
 Other changes in varnishd
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The VCC (compilation) process no longer loads VMODs using ``dlopen(3)`` to
-collect their metadata.
+The metadata VMODs exposes to Varnishd has changed to a non-binary
+format, and it is incompatible with all previous releases.
+That makes it possible for the VCC (compilation) process to avoid
+opening the VMODs with ``dlopen(3)``, which is both faster and
+safer.
 
 Background fetch tasks are no longer queued as this could result in slow
 grace hits subject to indefinite delays when thread pools are saturated.
@@ -72,8 +84,8 @@ the case, but is now (pun intended) formally defined behavior. It keeps the
 same value even if the execution blocks for a significant time, for example
 while calling a VMOD function.
 
-VMODs
-=====
+Bundled VMODs
+=============
 
 For a real time timestamp, the function ``std.now()`` can be used instead.
 There is also a new ``std.timed_call()`` to measure the execution time of a