OpenPKG Specs: openpkg/uuid.8@a2c6460cfb16

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

     1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)

     2 .\"

     3 .\" Standard preamble:

     4 .\" ========================================================================

     5 .de Sp \" Vertical space (when we can't use .PP)

     6 .if t .sp .5v

     7 .if n .sp

     8 ..

     9 .de Vb \" Begin verbatim text

    10 .ft CW

    11 .nf

    12 .ne \\$1

    13 ..

    14 .de Ve \" End verbatim text

    15 .ft R

    16 .fi

    17 ..

    18 .\" Set up some character translations and predefined strings.  \*(-- will

    19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

    20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will

    21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and

    22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,

    23 .\" nothing in troff, for use with C<>.

    24 .tr \(*W-

    25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

    26 .ie n \{\

    27 .    ds -- \(*W-

    28 .    ds PI pi

    29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch

    30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch

    31 .    ds L" ""

    32 .    ds R" ""

    33 .    ds C`

    34 .    ds C'

    35 'br\}

    36 .el\{\

    37 .    ds -- \|\(em\|

    38 .    ds PI \(*p

    39 .    ds L" ``

    40 .    ds R" ''

    41 'br\}

    42 .\"

    43 .\" Escape single quotes in literal strings from groff's Unicode transform.

    44 .ie \n(.g .ds Aq \(aq

    45 .el       .ds Aq '

    46 .\"

    47 .\" If the F register is turned on, we'll generate index entries on stderr for

    48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index

    49 .\" entries marked with X<> in POD.  Of course, you'll have to process the

    50 .\" output yourself in some meaningful fashion.

    51 .ie \nF \{\

    52 .    de IX

    53 .    tm Index:\\$1\t\\n%\t"\\$2"

    54 ..

    55 .    nr % 0

    56 .    rr F

    57 .\}

    58 .el \{\

    59 .    de IX

    60 ..

    61 .\}

    62 .\"

    63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

    64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.

    65 .    \" fudge factors for nroff and troff

    66 .if n \{\

    67 .    ds #H 0

    68 .    ds #V .8m

    69 .    ds #F .3m

    70 .    ds #[ \f1

    71 .    ds #] \fP

    72 .\}

    73 .if t \{\

    74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)

    75 .    ds #V .6m

    76 .    ds #F 0

    77 .    ds #[ \&

    78 .    ds #] \&

    79 .\}

    80 .    \" simple accents for nroff and troff

    81 .if n \{\

    82 .    ds ' \&

    83 .    ds ` \&

    84 .    ds ^ \&

    85 .    ds , \&

    86 .    ds ~ ~

    87 .    ds /

    88 .\}

    89 .if t \{\

    90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

    91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'

    92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'

    93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'

    94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'

    95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

    96 .\}

    97 .    \" troff and (daisy-wheel) nroff accents

    98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'

    99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'

   100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]

   101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'

   102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'

   103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]

   104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]

   105 .ds ae a\h'-(\w'a'u*4/10)'e

   106 .ds Ae A\h'-(\w'A'u*4/10)'E

   107 .    \" corrections for vroff

   108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'

   109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'

   110 .    \" for low resolution devices (crt and lpr)

   111 .if \n(.H>23 .if \n(.V>19 \

   112 \{\

   113 .    ds : e

   114 .    ds 8 ss

   115 .    ds o a

   116 .    ds d- d\h'-1'\(ga

   117 .    ds D- D\h'-1'\(hy

   118 .    ds th \o'bp'

   119 .    ds Th \o'LP'

   120 .    ds ae ae

   121 .    ds Ae AE

   122 .\}

   123 .rm #[ #] #H #V #F C

   124 .\" ========================================================================

   125 .\"

   126 .IX Title "UUID 8"

   127 .TH UUID 8 "OpenPKG" "UUID(8)" "OpenPKG"

   128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes

   129 .\" way too many mistakes in technical documents.

   130 .if n .ad l

   131 .nh

   132 .SH "NAME"

   133 openpkg uuid \- OpenPKG UUID Update Utility

   134 .SH "SYNOPSIS"

   135 .IX Header "SYNOPSIS"

   136 \&\fBopenpkg uuid\fR [\fB\-\-verbose\fR] [\fB\-\-multicast\fR] \fBreset\fR|\fBupdate\fR|\fBinfo\fR

   137 .SH "DESCRIPTION"

   138 .IX Header "DESCRIPTION"

   139 The \fBopenpkg uuid\fR command is the maintenance utility for the \s-1DCE\s0 1.1

   140 and \s-1ISO/IEC\s0 11578:1996 compliant \fIUniversally Unique Identifiers\fR

   141 (\s-1UUID\s0) of an \fBOpenPKG\fR instance. It is internally based on \fB\s-1OSSP\s0

   142 uuid\fR.

   143 .PP

   144 UUIDs are 128 bit numbers which are intended to have a high likelihood

   145 of uniqueness over space and time and are computationally difficult

   146 to guess. They are globally unique identifiers which can be locally

   147 generated without contacting a global registration authority. UUIDs are

   148 intended as unique identifiers for both mass tagging objects with an

   149 extremely short lifetime and to reliably identifying very persistent

   150 objects across a network. The three classical \s-1UUID\s0 variants are \s-1DCE\s0 1.1

   151 UUIDs of version 1 (time and node based), version 3 (name based) and

   152 version 4 (random number based).

   153 .PP

   154 For an \fBOpenPKG\fR instance, three different UUIDs are used:

   155 .ie n .IP "1. \fBOpenPKG Registry\fR (\*(C`UUID_REGISTRY\*(C')" 3

   156 .el .IP "1. \fBOpenPKG Registry\fR (\f(CW\*(C`UUID_REGISTRY\*(C'\fR)" 3

   157 .IX Item "1. OpenPKG Registry (UUID_REGISTRY)"

   158 This is a version 1 \s-1UUID\s0 which uniquely identifiers the \fBOpenPKG\fR

   159 instance for global registration purposes. It is generated just once in

   160 the lifetime of the \fBOpenPKG\fR instance. The value of this \s-1UUID\s0 cannot

   161 be recalculated deterministically.

   162 .ie n .IP "2. \fBOpenPKG Instance\fR (\*(C`UUID_INSTANCE\*(C')" 3

   163 .el .IP "2. \fBOpenPKG Instance\fR (\f(CW\*(C`UUID_INSTANCE\*(C'\fR)" 3

   164 .IX Item "2. OpenPKG Instance (UUID_INSTANCE)"

   165 This is a version 3 \s-1UUID\s0 which summarizes the \fBOpenPKG\fR

   166 instance parameters. Currently the values of the following

   167 particular OpenPKG \s-1RPM\s0 macros are uses as input:

   168 .Sp

   169 .Vb 5

   170 \& %{l_openpkg_release} %{l_prefix}

   171 \& %{l_susr} %{l_suid} %{l_sgrp} %{l_sgid}

   172 \& %{l_musr} %{l_muid} %{l_mgrp} %{l_mgid}

   173 \& %{l_rusr} %{l_ruid} %{l_rgrp} %{l_rgid}

   174 \& %{l_nusr} %{l_nuid} %{l_ngrp} %{l_ngid}

   175 .Ve

   176 .Sp

   177 The value of this \s-1UUID\s0 can be recalculated deterministically and will

   178 not chance as long as none of the values of the above macro do not

   179 change. This \s-1UUID\s0 can be used for detecting OpenPKG release upgrades,

   180 accidentally changed UIDs or GIDs, etc. Notice that version 3 UUIDs are

   181 message digests (actually \s-1MD5\s0 based) and so are one-way functions which do

   182 not allow one to recalculate the input values from the \s-1UUID\s0.

   183 .ie n .IP "3. \fBOpenPKG Platform\fR (\*(C`UUID_PLATFORM\*(C')" 3

   184 .el .IP "3. \fBOpenPKG Platform\fR (\f(CW\*(C`UUID_PLATFORM\*(C'\fR)" 3

   185 .IX Item "3. OpenPKG Platform (UUID_PLATFORM)"

   186 This is a version 3 \s-1UUID\s0 which summarizes the \fBOpenPKG\fR platform

   187 parameters. Currently the OpenPKG \s-1RPM\s0 platform id plus the \s-1FQDN\s0 and \s-1IP\s0

   188 address of the underlying host are used as input. This \s-1UUID\s0 can be used

   189 for detecting operating system and host changes. Notice that version

   190 3 UUIDs are message digests (actually \s-1MD5\s0 based) and so are one-way

   191 functions which do not allow one to recalculate the input values from

   192 the \s-1UUID\s0.

   193 .SH "OPTIONS"

   194 .IX Header "OPTIONS"

   195 .IP "\fB\-\-verbose\fR" 4

   196 .IX Item "--verbose"

   197 Print verbose messages during operation.

   198 .IP "\fB\-\-multicast\fR" 4

   199 .IX Item "--multicast"

   200 Generate a random multicast \s-1MAC\s0 address instead of using the real \s-1IEEE\s0

   201 802 \s-1MAC\s0 address of the underlying host when generating the version 1

   202 \&\s-1UUID\s0 \f(CW\*(C`UUID_REGISTRY\*(C'\fR.

   203 .SH "COMMANDS"

   204 .IX Header "COMMANDS"

   205 .IP "\fBreset\fR" 4

   206 .IX Item "reset"

   207 This resets the three UUIDs \f(CW\*(C`UUID_REGISTRY\*(C'\fR, \f(CW\*(C`UUID_INSTANCE\*(C'\fR and

   208 \&\f(CW\*(C`UUID_PLATFORM\*(C'\fR to the \*(L"Nil \s-1UUID\s0\*(R". They are then automatically

   209 regenerated within one day if already done explicitly afterward with

   210 "\f(CW\*(C`openpkg uuid update\*(C'\fR".

   211 .IP "\fBupdate\fR" 4

   212 .IX Item "update"

   213 This updates the three UUIDs \f(CW\*(C`UUID_REGISTRY\*(C'\fR, \f(CW\*(C`UUID_INSTANCE\*(C'\fR and

   214 \&\f(CW\*(C`UUID_PLATFORM\*(C'\fR to the \*(L"Nil \s-1UUID\s0\*(R". \f(CW\*(C`UUID_REGISTRY\*(C'\fR is kept unless it

   215 is the \*(L"Nil \s-1UUID\s0\*(R" (see "\f(CW\*(C`openpkg uuid reset\*(C'\fR" command above). The UUIDs

   216 \&\f(CW\*(C`UUID_INSTANCE\*(C'\fR and \f(CW\*(C`UUID_PLATFORM\*(C'\fR are updated only if their input

   217 values (and this way the resulting UUIDs) have changed. This operation

   218 is performed daily automatically.

   219 .IP "\fBinfo\fR" 4

   220 .IX Item "info"

   221 This print summary page of identification information, including all

   222 UUIDs and all of their calculation inputs.

   223 .SH "FILES"

   224 .IX Header "FILES"

   225 The three UUIDs of the \fBOpenPKG\fR instance are stored in the file

   226 \&\f(CW\*(C`@l_prefix@/etc/openpkg/uuid\*(C'\fR in Bourne-Shell syntax. An example

   227 content is:

   228 .PP

   229 .Vb 3

   230 \& UUID_REGISTRY="81eca44e\-4d18\-11d8\-a837\-0090272ff725"

   231 \& UUID_INSTANCE="c55a8d2d\-31bb\-3ae0\-9edb\-68337af61acc"

   232 \& UUID_PLATFORM="05ec2532\-9e3f\-37dc\-a7ed\-b291c2c463ed"

   233 .Ve

   234 .SH "CAVEATS"

   235 .IX Header "CAVEATS"

   236 By default and in full compliance with \s-1DCE\s0 1.1 and \s-1ISO/IEC\s0 11578:1996,

   237 the OpenPKG Registry \s-1UUID\s0 (\f(CW\*(C`UUID_REGISTRY\*(C'\fR) contains the \s-1IEEE\s0 802 \s-1MAC\s0

   238 address of the underlying host. If this is not acceptable by local

   239 security policies you can easily at any time generate a new OpenPKG

   240 Registry \s-1UUID\s0 with a random multicast \s-1MAC\s0 address instead by running:

   241 .PP

   242 .Vb 2

   243 \& $ openpkg uuid reset

   244 \& $ openpkg uuid \-\-multicast update

   245 .Ve

   246 .SH "SEE ALSO"

   247 .IX Header "SEE ALSO"

   248 \&\fB\s-1OSSP\s0 uuid\fR <http://www.ossp.org/pkg/lib/uuid/>.

   249 .SH "HISTORY"

   250 .IX Header "HISTORY"

   251 The \fBopenpkg uuid\fR command first appeared in \fBOpenPKG 2.0\fR.

OpenPKG Specs / file revision

openpkg/uuid.8@a2c6460cfb16

openpkg/uuid.8