1VMOD_UUID(3)                                                      VMOD_UUID(3)
2
3
4

NAME

6       vmod_uuid - Varnish UUID Module
7

SYNOPSIS

9       import uuid;
10

DESCRIPTION

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

FUNCTIONS

17   uuid
18       Prototype
19
20                 uuid()
21
22       Return value
23              STRING
24
25       Description
26              Returns  a  uuid version 1 (based on MAC address and the current
27              time)
28
29       UUID
30
31                 set req.http.X-Flow-ID = "cache-" + uuid.uuid();
32
33   uuid_v1
34       Prototype
35
36                 uuid_v1()
37
38       Return value
39              STRING
40
41       Description
42              Returns a uuid version 1. The functions uuid() and uuid_v1() are
43              aliases for one another.
44
45       Example
46
47                 set req.http.X-Flow-ID = "cache-" + uuid.uuid_v1();
48
49   uuid_v3
50       Prototype
51
52                 uuid_v3(STRING namespace, STRING name)
53
54       Return value
55              STRING
56
57       Description
58              Returns a uuid version 3, based on an MD5 hash formed from name‐
59              space and name. The namespace argument MUST be one of  the  fol‐
60              lowing:
61
62       • "nil" (for the "nil UUID")
63
64       • "ns:DNS" (for the domain name system)
65
66       • "ns:URL" (for the URL namespace)
67
68       • "ns:OID" (for the ISO object identifier namespace)
69
70       • "ns:X500" (for X.500 distinguished names)
71
72       • 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
77       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 VCL_er‐
80       ror.
81
82       The name argument can be any string.
83
84       Example
85
86                 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
89   uuid_v4
90       Prototype
91
92                 uuid_v4()
93
94       Return value
95              STRING
96
97       Description
98              Returns a uuid version 4, based on random numbers.
99
100       Example
101
102                 set req.http.X-Rand-ID = uuid.uuid_v4();
103
104   uuid_v5
105       Prototype
106
107                 uuid_v5(STRING namespace, STRING name)
108
109       Return value
110              STRING
111
112       Description
113              Returns a uuid version 5, based on a SHA1 hash formed from name‐
114              space and name. The same restrictions and failure conditions re‐
115              garding  the namespace argument hold as for uuid_v3() above. The
116              name argument can be any string.
117
118       Example
119
120                 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

DEPENDENCIES

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 (usually named uuid) from your linux distribution.
127
128       This version of the VMOD requires Varnish since version  6.0.0  or  the
129       master branch. See the project source code repository for versions com‐
130       patible with a Varnish release.
131

INSTALLATION

133       See INSTALL.rst in the source repository.
134

HISTORY

136       • Version 1.5: RPM compatible with Varnish 6.0.0
137
138       • Version 1.4: add RPM packaging
139
140       • Version 1.3: compatible with Varnish 5.0.0 through 5.2.
141
142       • Verison 1.2: compatible with Varnish since 5.0.0
143
144       • Version 1.1: requires Varnish 4.1, creates internal UUID objects only
145         once  during  a client or backend context and re-uses them for subse‐
146         quent calls.
147
148       • Version 1.0: Varnish 4 version, supporting all UUID variants by Geof‐
149         frey  Simmons  <geoff@uplex.de>,  UPLEX Nils Goroll Systemoptimierung
150         for Otto GmbH & KG https://github.com/otto-de/libvmod-uuid
151
152       • Version 0.1: Initial Varnish 3 version, by Mitchell Broome of  Share‐
153         care https://github.com/Sharecare/libvmod-uuid
154

156       This  document  is  licensed under the same license as the libvmod-uuid
157       project. See LICENSE for details.
158

AUTHOR

160       Mitchell Broome, Geoff Simmons
161
162
163
164
165trunk                             2018-04-02                      VMOD_UUID(3)
Impressum