[4.0] 98c949a Document why updating VMODs on the fly does not work.
lkarsten at varnish-software.com
Mon Sep 22 16:38:24 CEST 2014
Author: Poul-Henning Kamp <phk at FreeBSD.org>
Date: Tue Aug 26 08:20:36 2014 +0000
Document why updating VMODs on the fly does not work.
diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 033e04b..5ad685f 100644
@@ -325,3 +325,33 @@ unless they access VMOD specific global state, shared with other VCLs.
Traffic in other VCLs which also import this VMOD, will be happening
while housekeeping is going on.
+A compiled VMOD is a shared library file which Varnish dlopen(3)'s
+using flags RTLD_NOW | RTLD_LOCAL.
+As a general rule, once a file is opened with dlopen(3) you should
+never modify it, but it is safe to rename it and put a new file
+under the name it had, which is how most tools installs and updates
+However, when you call dlopen(3) with the same filename multiple
+times it will give you the same single copy of the shared library
+file, without checking if it was updated in the meantime.
+This is obviously an oversight in the design of the dlopen(3) library
+function, but back in the late 1980ies nobody could imagine why a
+program would ever want to have multiple different versions of the
+same shared library mapped at the same time.
+Varnish does that, and therefore you must restart the worker process
+before Varnish will discover an updated VMOD.
+If you want to test a new version of a VMOD, while being able to
+instantly switch back to the old version, you will have to install
+each version with a distinct filename or in a distinct subdirectory
+and use ``import foo from "...";`` to reference it in your VCL.
+We're not happy about this, but have found no sensible workarounds.
More information about the varnish-commit