VMOD_UUID(3)

📦
version 1.10 · 2 versions
, in fedora 43

💖 VMOD_UUID(3) — the Varnish UUID module, bestie edition 💖

okay so welcome to vmod_uuid, it lives in section 3 of the manual (library functions, iykyk) and it's literally just here to hand you UUIDs. slay. let's go 🦋

✨ NAME ✨

vmod_uuid — Varnish UUID Module. that's the whole name, she's simple, she's iconic 💅

✨ SYNOPSIS ✨

import uuid;

that's it. that's the whole import. one line, no notes ✨

✨ DESCRIPTION ✨

so vmod_uuid is a UUID Varnish vmod, and what it does is generate a uuid, lowkey including versions 1, 3, 4 and 5 exactly as specified in RFC 4122. if you wanna know the deets about all the different versions, go read the RFC, bestie, it's all in there 📖

✨ FUNCTIONS ✨

💫 uuid

Prototype

uuid()

Return value: STRING

Description: returns a uuid version 1, which is based on the MAC address and the current time. vintage, fr fr ⏰

UUID

set req.http.X-Flow-ID = "cache-" + uuid.uuid();

💫 uuid_v1

Prototype

uuid_v1()

Return value: STRING

Description: returns a uuid version 1. and here's the tea: the functions uuid() and uuid_v1() are aliases for one another. same girl, two names 🫶

Example

set req.http.X-Flow-ID = "cache-" + uuid.uuid_v1();

💫 uuid_v3

Prototype

uuid_v3(STRING namespace, STRING name)

Return value: STRING

Description: returns a uuid version 3, based on an MD5 hash formed from namespace and name. the namespace argument MUST be one of the following, no exceptions, this is a vibe check and you will not pass if you freestyle it:

  • "nil" (for the "nil UUID")
  • "ns:DNS" (for the domain name system)
  • "ns:URL" (for the URL namespace)
  • "ns:OID" (for the ISO object identifier namespace)
  • "ns:X500" (for X.500 distinguished names)
  • a valid 36-character representation of a UUID, i.e. a string of the form "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", where all of the x's are hex digits, with appropriate restrictions on UUID formats (cf. the RFC)
🚨 if these conditions are not met, then uuid_v3() fails; it returns a null string (typically, the header specified in VCL will not be set), and an error message is emitted to the Varnish log with the tag VCL_error. so like, don't do that 💀

the name argument can be any string. any string bestie, go feral.

Example

set req.http.X-DNS-ID = uuid.uuid_v3("ns:DNS", "www.widgets.com");
set req.http.X-MyNS-ID = uuid.uuid_v3("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.widgets.com");

💫 uuid_v4

Prototype

uuid_v4()

Return value: STRING

Description: returns a uuid version 4, based on random numbers. chaos, but make it RFC-compliant 🎲

Example

set req.http.X-Rand-ID = uuid.uuid_v4();

💫 uuid_v5

Prototype

uuid_v5(STRING namespace, STRING name)

Return value: STRING

Description: returns a uuid version 5, based on a SHA1 hash formed from namespace and name. the same restrictions and failure conditions regarding the namespace argument hold as for uuid_v3() above (yes, all of them, go re-read that list, I'll wait 🌸). the name argument can be any string.

Example

set req.http.X-DNS-ID = uuid.uuid_v5("ns:DNS", "www.widgets.com");
set req.http.X-MyNS-ID = uuid.uuid_v5("6ba7b810-9dad-11d1-80b4-00c04fd430c8", "www.widgets.com");

✨ DEPENDENCIES ✨

libvmod-uuid requires the OSSP uuid library to generate uuids. it's available at <http://www.ossp.org/pkg/lib/uuid/> or possibly as a prepackaged library (usually named uuid) from your linux distribution. so check your package manager first, it's giving convenience 🧚

this version of the VMOD requires Varnish since version 6.0.0 or the master branch. see the project source code repository for versions compatible with a Varnish release.

✨ INSTALLATION ✨

see <INSTALL.rst> in the source repository. short and sweet, periodt 📄

✨ HISTORY ✨

the glow-up timeline, in order:

  • Version 1.5: RPM compatible with Varnish 6.0.0
  • Version 1.4: add RPM packaging
  • Version 1.3: compatible with Varnish 5.0.0 through 5.2.
  • Verison 1.2: compatible with Varnish since 5.0.0
  • Version 1.1: requires Varnish 4.1, creates internal UUID objects only once during a client or backend context and re-uses them for subsequent calls.
  • Version 1.0: Varnish 4 version, supporting all UUID variants by Geoffrey Simmons < <geoff@uplex.de> >, UPLEX Nils Goroll Systemoptimierung for Otto GmbH & KG <https://github.com/otto-de/libvmod-uuid>
  • Version 0.1: Initial Varnish 3 version, by Mitchell Broome of Sharecare <https://github.com/Sharecare/libvmod-uuid>

(yes, "Verison" 1.2 is spelled like that in the original, we don't fix typo history in this house 💖)

this document is licensed under the same license as the libvmod-uuid project. see LICENSE for details.

✨ AUTHOR ✨

Mitchell Broome, Geoff Simmons 👑

and that's the whole page bestie!! this one shipped as trunk, dated 2018-04-02, and it's the VMOD_UUID(3) manual page — take care of her, she's been slaying since forever 🌈✨💅

📦 where this page comes from