UUID(1)

NAME
uuid - generate, convert, and decode Universally Unique IDentifiers

SYNOPSIS
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] [-v 1] [-m1]
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] -v 3 uuid|nil|max|ns:{DNS|URL|OID|X500} data
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] -v 4
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] -v 5 uuid|nil|max|ns:{DNS|URL|OID|X500} data
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] -v 6
uuid [-n count] [-o outfile] [-r|-F BIN|STR|SIV] -v 7

uuid -d [-o outfile] [ -r|'u'-F BIN|'u'STR|SIV] uuid
uuid -d [-o outfile] [-r|-F BIN|STR|SIV] -

DESCRIPTION
By default, generates a UUID (Universally Unique Identifier), of a version specified by -v (default 1) in the canonical STRing format.
With -d, decodes uuid (or reads it in from the standard input stream if "-"), yielding something akin to
    encode: STR:     92a3d3de-6bbf-11ef-9f5b-774ebb537938
            SIV:     194917928982963228599463962120788605240
    decode: variant: DCE 1.1, ISO/IEC 11578:1996
            version: 1 (time and node based)
            content: time:  2024-09-05 19:46:41.491043.0 UTC
                     clock: 8027 (usually random)
                     node:  77:4e:bb:53:79:38 (local multicast)

or
    encode: STR:     7e017d98-cecc-41f6-8030-552d23cd38e6
            SIV:     167490467173639937831846401373276813542
    decode: variant: DCE 1.1, ISO/IEC 11578:1996
            version: 4 (random data based)
            content: 7E:01:7D:98:CE:CC:01:F6:00:30:55:2D:23:CD:38:E6
                     (no semantics: random data only)

A UUID is a 128-bit (16-byte) number whose format (method of generation) makes it very likely that it will be unique, both spatially and temporally. This makes them well-suited for identifying anything from ephemera like database queries to databases themselves.

The three principal -Formats are:
STRing
    01234567-890a-bcde-f012-3456789abcde (hexadecimal string broken up by dashes)
SIV (Single Integer Value)
    128-bit decimal integer
BINary or "raw"
    the 16 bytes of the UUID in big endian order (most significant first)

UUIDs come in a few -versions:
1   based on the current time (to the precision of 100ns), and the host's MAC address (this implementation uses the MAC address of the first NIC it finds, unless -m, in which case random data is substituted for the MAC)
6   very similar, but the most significant (slowest-changing) parts of the timestamp are stored first, which improves locality in some database applications

7   contains the current UNIX time — versions 1 and 6 encode a UUID time which is off by like 400 years — (to the precision of 1ms), then 10 bytes of random data.
    This version should be preferred to 1 and 6.

3   hashes the "namespace" (first argument, either a STRing-format UUID or a well-known name (see below)) and the "name" (second argument, arbitrary data) with the MD5(3) digest, and uses that directly (a few branding bytes are replaced to identify the format)
5   the same as version 3, but uses the first 16 bytes of the SHA1(3) digest

4   just random data

The namespaces understood when generating version 3 and 5 UUIDs are:
uuid
    (any valid STRingified UUID)
nil 00000000-0000-0000-0000-000000000000 — the special all-zero UUID
max ffffffff-ffff-ffff-ffff-ffffffffffff — the special all-bits-set/sorts-after-everything sentinel UUID
ns:DNS
    6ba7b810-9dad-11d1-80b4-00c04fd430c8 — for fully-qualified domain names
ns:URL
    6ba7b811-9dad-11d1-80b4-00c04fd430c8 — for URLs
ns:OID
    6ba7b812-9dad-11d1-80b4-00c04fd430c8 — for ISO OIDs
ns:X500
    6ba7b814-9dad-11d1-80b4-00c04fd430c8 — for X.500 Distinguished Names

OPTIONS
-n count
    Generate count UUIDs. Defaults to 1.
-o outfile
    Write to outfile.
-F BIN|STR|SIV
    Produce output in the given format. Defaults to STR.
-r  -F BIN
-v 1|3|4|5|6|7
    Version to generate. Defaults to 1.
-m  -v 1|6 only: ignore the current host's MAC addresses, use random data instead (this may still happen if the if a MAC can't be determined or all MACs are multicast).
-1  -v 1 only, count >1 only: generate each UUID independently. Version 1 UUIDs have a field that increases monotonically within a session; thus, for example, in
        $ uuid -n 4
        366ab5a3-6bc4-11ef-a31a-0026b986fdd4
        366ab5ce-6bc4-11ef-a31b-0026b986fdd4
        366ab5f8-6bc4-11ef-a31c-0026b986fdd4
        366ab621-6bc4-11ef-a31d-0026b986fdd4
                           ^^^^

    the highlighted column starts random, but then increments. -1 generates each UUID de novo.

-d  Decode and parse uuid. -F sets which format to read. -F BIN is only available when reading from the standard input stream ("-").

EXAMPLES
A web site can be uniquely identified with a version 5 (SHA-1), namespace ns:DNS UUID, and a web-page — ns:URL (note that this information cannot be extracted, and only serves as a way to avoid collisions for otherwise-identical names):
    $ uuid -v 5 ns:DNS hinfo.network.
    f50b485f-ac66-591d-b95f-2c946c5a5668
    $ uuid -v 5 ns:URL https://hinfo.network
    8cebc56f-51d0-5323-a031-1b9258de14f8
    $ uuid -d 8cebc56f-51d0-5323-a031-1b9258de14f8
    encode: STR:     f50b485f-ac66-591d-b95f-2c946c5a5668
            SIV:     325719442146270326702531202385345926760
    decode: variant: DCE 1.1, ISO/IEC 11578:1996
            version: 5 (name based, SHA-1)
            content: F5:0B:48:5F:AC:66:09:1D:39:5F:2C:94:6C:5A:56:68
                     (not decipherable: truncated SHA-1 message digest only)

    $ uuid -v 7
    0191c41a-9de1-7f96-b8cb-88e4348ee74c
    $ uuid -d 0191c41a-9de1-7f96-b8cb-88e4348ee74c
    encode: STR:     0191c41a-9de1-7f96-b8cb-88e4348ee74c
            SIV:     2086088501348764349551890213853128524
    decode: variant: DCE 1.1, ISO/IEC 11578:1996
            version: 7 (UNIX time + random data)
            content: time:   2024-09-05 21:32:44.385 UTC
                     random: 0F:96:38:CB:88:E4:34:8E:E7:4C

SEE ALSO
uuid(3), OSSP::uuid(3)

STANDARDS
RFC 9562: Universally Unique IDentifiers (UUIDs): https://datatracker.ietf.org/doc/html/rfc9562 supersedes all previous standards with an unbecoming brevity.

There are many Versions, but only one useful Variant.