misc-utils/uuidgen.1

   1 .\" Copyright 1999 Andreas Dilger (adilger@enel.ucalgary.ca)
   2 .\"
   3 .\" This file may be copied under the terms of the GNU Public License.
   4 .TH UUIDGEN 1 "June 2011" "util-linux" "User Commands"
   5 .SH NAME
   6 uuidgen \- create a new UUID value
   7 .SH SYNOPSIS
   8 .B uuidgen
   9 [options]
  10 .SH DESCRIPTION
  11 The
  12 .B uuidgen
  13 program creates (and prints)
  14 a new universally unique identifier (UUID) using the
  15 .BR libuuid (3)
  16 library.  The new UUID can reasonably be considered unique among
  17 all UUIDs created on the local system,
  18 and among UUIDs created on other systems in the past
  19 and in the future.
  20 .PP
  21 There are three types of UUIDs which
  22 .B uuidgen
  23 can generate: time-based UUIDs, random-based UUIDs, and hash-based UUIDs.
  24 By default
  25 .B uuidgen
  26 will generate a random-based UUID if a high-quality random number
  27 generator is present.  Otherwise, it will choose a time-based UUID.
  28 It is possible to force the generation of one of these first two
  29 UUID types by using the
  30 .B \-\-random
  31 or
  32 .B \-\-time
  33 options.
  34 .PP
  35 The third type of UUID is generated with the
  36 .B \-\-md5
  37 or
  38 .B \-\-sha1
  39 options, followed by
  40 \fB\-\-namespace\fR \fInamespace\fR
  41 and
  42 \fB\-\-name\fR \fIname\fR.
  43 The \fInamespace\fR may either be a well-known UUID, or else
  44 an alias to one of the well-known UUIDs defined in RFC 4122, that is
  45 .BR @dns ,
  46 .BR @url ,
  47 .BR @oid ,
  48 or
  49 .BR @x500 .
  50 The \fIname\fR is an arbitrary string value.  The generated UUID is the
  51 digest of the concatenation of the namespace UUID and the name value, hashed
  52 with the MD5 or SHA1 algorithms.  It is, therefore, a predictable value
  53 which may be useful when UUIDs are being used as handles or nonces for
  54 more complex values or values which shouldn't be disclosed directly.
  55 See the RFC for more information.
  56 .SH OPTIONS
  57 .TP
  58 .BR \-r , " \-\-random"
  59 Generate a random-based UUID.  This method creates a UUID consisting mostly
  60 of random bits.  It requires that the operating system have a high
  61 quality random number generator, such as
  62 .IR /dev/random .
  63 .TP
  64 .BR \-t , " \-\-time"
  65 Generate a time-based UUID.  This method creates a UUID based on the system
  66 clock plus the system's ethernet hardware address, if present.
  67 .TP
  68 .BR \-h , " \-\-help"
  69 Display help text and exit.
  70 .TP
  71 .BR \-V , " \-\-version"
  72 Display version information and exit.
  73 .TP
  74 .BR \-m , " \-\-md5"
  75 Use MD5 as the hash algorithm.
  76 .TP
  77 .BR \-s , " \-\-sha1"
  78 Use SHA1 as the hash algorithm.
  79 .TP
  80 .BR \-n , " \-\-namespace " \fInamespace\fP
  81 Generate the hash with the \fInamespace\fP prefix. The \fInamespace\fP is UUID,
  82 or '@ns' where "ns" is well-known predefined UUID addressed by namespace name
  83 (see above).
  84 .TP
  85 .BR \-N , " \-\-name " \fIname\fR
  86 Generate the hash of the \fIname\fR.
  87 .TP
  88 .BR \-x , " \-\-hex"
  89 Interpret name \fIname\fR as a hexadecimal string.
  90 .SH "CONFORMING TO"
  91 OSF DCE 1.1
  92 .SH EXAMPLES
  93 uuidgen \-\-sha1 \-\-namespace @dns \-\-name "www.example.com"
  94 .SH AUTHOR
  95 .B uuidgen
  96 was written by Andreas Dilger for libuuid.
  97 .SH SEE ALSO
  98 .BR libuuid (3),
  99 .B "RFC 4122"
 100 .SH AVAILABILITY
 101 The uuidgen command is part of the util-linux package and is available from
 102 https://www.kernel.org/pub/linux/utils/util-linux/.