Scroll to navigation

UUID(1) General Commands Manual 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] [-F 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:

ing
(hexadecimal string broken up by dashes)
(Single Integer Value)
128-bit decimal integer
ary or "raw"
the 16 bytes of the UUID in big endian order (most significant first)

UUIDs come in a few -versions:

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)
very similar, but the most significant (slowest-changing) parts of the timestamp are stored first, which improves locality in some database applications

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.

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)
the same as version 3, but uses the first 16 bytes of the SHA1(3) digest

just random data

The namespaces understood when generating version 3 and 5 UUIDs are:

uuid
(any valid STRingified UUID)
— the special all-zero UUID
— the special all-bits-set/sorts-after-everything sentinel UUID
— for fully-qualified domain names
— for URLs
— for ISO OIDs
— for X.500 Distinguished Names

OPTIONS

count
Generate count UUIDs. Defaults to 1.
outfile
Write to outfile.
BIN|STR|SIV
Produce output in the given format. Defaults to STR.
BIN
1|3|4|5|6|7
Version to generate. Defaults to 1.
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 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 random, but then increments. -1 generates each UUID de novo.

Decode and parse uuid. -F sets which format to . -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 8cebc56f-51d0-5323-a031-1b9258de14f8 $ uuid -d 8cebc56f-51d0-5323-a031-1b9258de14f8 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) supersedes all previous standards with an unbecoming brevity.

There are many Versions, but only one useful Variant.

December 9, 2024 ossp-uuid 1.6.4