1VMOD_UUID(3) VMOD_UUID(3)
2
6 vmod_uuid - Varnish UUID Module
7
9 import uuid;
10
12 UUID Varnish vmod used to generate a uuid, including versions 1, 3, 4
13 and 5 as specified in RFC 4122. See the RFC for details about the vari‐
14 ous versions.
15
17 uuid
18 Prototype
19 uuid()
21 Return value
23 STRING
24 Description
26 Returns a uuid version 1 (based on MAC address and the current
27 time)
28 UUID
30 set req.http.X-Flow-ID = "cache-" + uuid.uuid();
32 uuid_v1
34 Prototype
35 uuid_v1()
37 Return value
39 STRING
40 Description
42 Returns a uuid version 1. The functions uuid() and uuid_v1() are
43 aliases for one another.
44 Example
46 set req.http.X-Flow-ID = "cache-" + uuid.uuid_v1();
48 uuid_v3
50 Prototype
51 uuid_v3(STRING namespace, STRING name)
53 Return value
55 STRING
56 Description
58 Returns a uuid version 3, based on an MD5 hash formed from
59 namespace and name. The namespace argument MUST be one of the
60 following:
61 · "nil" (for the "nil UUID")
63 · "ns:DNS" (for the domain name system)
65 · "ns:URL" (for the URL namespace)
67 · "ns:OID" (for the ISO object identifier namespace)
69 · "ns:X500" (for X.500 distinguished names)
71 · a valid 36-character representation of a UUID, i.e. a string of the
73 form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", where all of the x's are
74 hex digits, with appropriate restrictions on UUID formats (cf. the
75 RFC)
76 If these conditions are not met, then uuid_v3() fails; it returns a
78 null string (typically, the header specified in VCL will not be set),
79 and an error message is emitted to the Varnish log with the tag
80 VCL_error.
81 The name argument can be any string.
83 Example
85 set req.http.X-DNS-ID = uuid.uuid_v3("ns:DNS", "www.widgets.com");
87 set req.http.X-MyNS-ID = uuid.uuid_v3("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.widgets.com");
88 uuid_v4
90 Prototype
91 uuid_v4()
93 Return value
95 STRING
96 Description
98 Returns a uuid version 4, based on random numbers.
99 Example
101 set req.http.X-Rand-ID = uuid.uuid_v4();
103 uuid_v5
105 Prototype
106 uuid_v5(STRING namespace, STRING name)
108 Return value
110 STRING
111 Description
113 Returns a uuid version 5, based on a SHA1 hash formed from
114 namespace and name. The same restrictions and failure conditions
115 regarding the namespace argument hold as for uuid_v3() above.
116 The name argument can be any string.
117 Example
119 set req.http.X-DNS-ID = uuid.uuid_v5("ns:DNS", "www.widgets.com");
121 set req.http.X-MyNS-ID = uuid.uuid_v5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.widgets.com");
122
124 Libvmod-uuid requires the OSSP uuid library to generate uuids. It is
125 available at http://www.ossp.org/pkg/lib/uuid/ or possibly as a
126 prepackaged library from your linux distribution.
127 In the case of Redhat/Fedora/CentOS, the rpm is named uuid. Ensure you
129 install the rpms with the following command:
130 yum install -y uuid uuid-devel
132 This version of the VMOD requires Varnish since version 5.0.0, and has
134 been tested against versions through 5.2.0.
135
137 The installation process is standard for a Varnish VMOD -- build the
138 VMOD on a system where an instance of Varnish is installed, and the
139 auto-tools will attempt to locate the Varnish instance, and then pull
140 in libraries and other support files from there.
141 Quick start
143 This sequence should be enough in typical setups:
144 1. ./autogen.sh (for git-installation)
146 2. ./configure
148 3. make
150 4. make check (regression tests)
152 5. make install (may require root: sudo make install)
154 In your VCL you could then use this vmod along the following lines:
156 import uuid;
158 sub vcl_recv {
160 # This sets req.http.X-Flow-ID to "cache-uuid"
161 set req.http.X-Flow-ID = "cache-" + uuid.uuid();
162 }
163 Alternative configs
165 As with Varnish itself, you can set additional flags and macros in the
166 configure step, and/or define environment variables to affect the build
167 config.
168 For example, if you are building the VMOD against a Varnish instance
170 with a non-standard installation prefix, then set these env variables
171 before running configure:
172 · PREFIX=/path/to/varnish/install/prefix
174 · export PKG_CONFIG_PATH=$PREFIX/lib/pkgconfig
176 · export ACLOCAL_PATH=$PREFIX/share/aclocal
178 · export PATH=$PREFIX/bin:$PREFIX/sbin:$PATH
180 configure must locate the varnishtest and varnishd binaries so that
182 make check can be run. Usually it should be able to find them, but if
183 necessary you can set the variables VARNISHTEST and/or VARNISHD with
184 the full paths.
185 For developers
187 As with Varnish, you can use these configure options for stricter com‐
188 piling:
189 · --enable-developer-warnings
191 · --enable-extra-developer-warnings (for GCC 4)
193 · --enable-werror
195 The VMOD must always build successfully with these options enabled.
197 Also as with Varnish, you can add --enable-debugging-symbols, so that
199 the VMOD's symbols are available to debuggers, in core dumps and so
200 forth.
201
203 · Verison 1.2: compatible with Varnish since 5.0.0
204 · Version 1.1: requires Varnish 4.1, creates internal UUID objects only
206 once during a client or backend context and re-uses them for subse‐
207 quent calls.
208 · Version 1.0: Varnish 4 version, supporting all UUID variants by Geof‐
210 frey Simmons <geoff@uplex.de>, UPLEX Nils Goroll Systemoptimierung
211 for Otto GmbH & KG https://github.com/otto-de/libvmod-uuid
212 · Version 0.1: Initial Varnish 3 version, by Mitchell Broome of Share‐
214 care https://github.com/Sharecare/libvmod-uuid
215
217 This document is licensed under the same license as the libvmod-uuid
218 project. See LICENSE for details.
219
221 Mitchell Broome, Geoff Simmons
2221.3 2017-10-30 VMOD_UUID(3)