- written manual page for "openpkg uuid" - implemented "openpkg man" command for reading tool chain command manual pages

openpkg/HISTORY

@@ -2,6 +2,8 @@
 2004
 ====
 
+20040221 written manual page for "openpkg uuid"
+20040221 implemented "openpkg man" command for reading tool chain command manual pages
 20040220 fix "openpkg rpm-config --version" output
 20040220 cleanup displayed messages and do not display error message on failed commands
 20040218 upgraded to GNU shtool 2.0b1

openpkg/lsync.8

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -153,7 +153,7 @@ installed in a sub-directory of a package hierarchy (located under
 \&\fIroot\fR/\fIpkgdir\fR/) by managing symbolic links in an access layer
 (located under \fIroot\fR/) corresponding to package installation
 files (found in \fIroot\fR/\fIpkgdir\fR/pkgname/subdir/) which need to be
-collected in global directories (located under \fIroot\fR/subdir/). 
+collected in global directories (located under \fIroot\fR/subdir/).
 .PP
 The purpose of this is that individual packages can be installed and
 deinstalled seperately without interfering with other packages while

openpkg/man.sh

@@ -1,9 +1,9 @@
 #!@l_prefix@/lib/openpkg/bash
 ##
 ##  man -- OpenPKG Tool Chain "man" command
-##  Copyright (c) 2004 The OpenPKG Project <http://www.openpkg.org/>
-##  Copyright (c) 2004 Ralf S. Engelschall <rse@engelschall.com>
-##  Copyright (c) 2004 Cable & Wireless <http://www.cw.com/>
+##  Copyright (c) 2000-2004 The OpenPKG Project <http://www.openpkg.org/>
+##  Copyright (c) 2000-2004 Ralf S. Engelschall <rse@engelschall.com>
+##  Copyright (c) 2000-2004 Cable & Wireless <http://www.cw.com/>
 ##
 ##  Permission to use, copy, modify, and distribute this software for
 ##  any purpose with or without fee is hereby granted, provided that
@@ -24,5 +24,112 @@
 ##  SUCH DAMAGE.
 ##
 
-echo "FIXME: STILL NOT IMPLEMENTED"
+#   configuration
+prefix="@l_prefix@"
+
+#   minimum command line parsing
+opt_h=no
+while [ 1 ]; do
+    case "$1" in
+        -h | --help ) opt_h=yes; shift ;;
+        * ) break ;;
+    esac
+done
+if [ ".$opt_h" = .yes ]; then
+    echo "openpkg:man:USAGE: openpkg man [--help] [<section>] <command>"
+    exit 0
+fi
+if [ $# -eq 1 ]; then
+    man_sect=""
+    man_page="$1"
+elif [ $# -eq 2 ]; then
+    man_sect="$1"
+    man_page="$2"
+else
+    echo "openpkg:man:ERROR: invalid number of arguments" 1>&2
+    exit 1
+fi
+
+#   search for manual page in OpenPKG Tool Chain
+man_file=""
+man_type=""
+OIFS="$IFS"; IFS=":"
+for dir in ${OPENPKG_TOOLS_CMDPATH-"$prefix/libexec/openpkg"}; do
+    IFS="$OIFS"
+    for file in $dir/$man_page.${man_sect-"1"} $dir/$man_page.[1-9]; do
+        if [ -f "$file" ]; then
+            man_file="$file"
+            man_type="roff"
+            if [ ".$man_sect" = . ]; then
+                man_sect=`echo "$man_file" |\
+                    sed -e 's;^;X;' -e 's;^X.*\.\([1-9]\)$;\1;' -e 's;^X.*;;'`
+            fi
+            break
+        fi
+    done
+    if [ ".$man_type" = . ]; then
+        for file in $dir/$man_page.pod $dir/$man_page.pl $dir/$man_page.sh; do
+            if [ -f "$file" ]; then
+                if [ ".`grep '^=pod' $file`" != . ]; then
+                    man_file="$file"
+                    man_type="pod"
+                    break
+                fi
+            fi
+        done
+    fi
+    if [ ".$man_type" != . ]; then
+        break
+    fi
+done
+IFS="$OIFS"
+if [ ".$man_type" != . ]; then
+    #   determine POD to Roff converter
+    pod2roff=""
+    if [ ".$man_type" = .pod ]; then
+        pod2roff=`$prefix/lib/openpkg/shtool path -p "$prefix/bin:$PATH" pod2man`
+        if [ ".$pod2roff" = . ]; then
+            echo "openpkg:man:ERROR: unable to find POD to Roff converter (pod2man)" 1>&2
+            exit 1
+        fi
+        pod2roff="$pod2roff --section=${man_sect-1}"
+        pod2roff="$pod2roff --release=\"$man_page(${man_sect-1})\""
+        pod2roff="$pod2roff --center=OpenPKG --date=OpenPKG"
+        pod2roff="$pod2roff --quotes=none"
+    fi
+
+    #   determine Roff to ASCII converter
+    roff2ascii=`$prefix/lib/openpkg/shtool path -p "$prefix/bin:$PATH" nroff groff`
+    if [ ".$roff2ascii" = . ]; then
+        echo "openpkg:man:ERROR: unable to find Roff to ASCII converter (nroff, groff)" 1>&2
+        exit 1
+    fi
+    roff2ascii="$roff2ascii -man"
+    case "$roff2ascii" in
+        */groff ) roff2ascii="$roff2ascii -Tascii" ;;
+    esac
+
+    #   determine pager
+    pager="$PAGER"
+    if [ ".$pager" = . ]; then
+        pager=`$prefix/lib/openpkg/shtool path -p "$prefix/bin:$PATH" less more cat`
+    fi
+    if [ ".$pager" = . ]; then
+        echo "openpkg:man:ERROR: unable to find text viewer ($PAGER, less, more, cat)" 1>&2
+        exit 1
+    fi
+
+    #   render the manual page to the TTY
+    if [ ".$man_type" = .roff ]; then
+        eval "$roff2ascii $man_file | $pager"
+    elif [ ".$man_type" = .pod ]; then
+        eval "$pod2roff $man_file | $roff2ascii | $pager"
+    fi
+    exit 0
+fi
+
+#   fallback to the man(1) command
+MANPATH="$prefix/man:$prefix/local/man:${MANPATH-/usr/man}:/usr/man:/usr/share/man"
+export MANPATH
+eval "exec man $man_sect $man_page"
 

openpkg/openpkg.spec

@@ -39,7 +39,7 @@
 #   o any cc(1)
 
 #   the package version/release
-%define       V_openpkg  20040220
+%define       V_openpkg  20040221
 
 #   the used software versions
 %define       V_rpm      4.2.1
@@ -131,6 +131,8 @@ Source59:     openpkg.pod
 Source60:     openpkg.1
 Source61:     install.sh
 Source62:     man.sh
+Source63:     uuid.pod
+Source64:     uuid.8
 
 #   build information
 Prefix:       %{l_prefix}
@@ -934,6 +936,8 @@ Provides:     openpkg = 1.3.1-1.3.1
         -e "s;@l_mgrp@;%{l_mgrp};g" \
         <`SOURCE uuid.sh` >$RPM_BUILD_ROOT%{l_prefix}/libexec/openpkg/uuid
     chmod a+x $RPM_BUILD_ROOT%{l_prefix}/libexec/openpkg/uuid
+    sed -e "s;@l_prefix@;%{l_prefix};g" \
+        <`SOURCE uuid.8` >$RPM_BUILD_ROOT%{l_prefix}/libexec/openpkg/uuid.8
     sed -e "s;@l_prefix@;%{l_prefix};g" \
         -e "s;@l_musr@;%{l_musr};g" \
         -e "s;@l_mgrp@;%{l_mgrp};g" \
@@ -1173,6 +1177,7 @@ Provides:     openpkg = 1.3.1-1.3.1
     %dir %{l_prefix}/libexec
     %dir %{l_prefix}/libexec/openpkg
     %{l_prefix}/libexec/openpkg/uuid
+    %{l_prefix}/libexec/openpkg/uuid.8
     %{l_prefix}/libexec/openpkg/man
     %{l_prefix}/libexec/openpkg/install
     %{l_prefix}/libexec/openpkg/lsync

openpkg/pod2man.sh

@@ -4,3 +4,4 @@ pod2man --section=8 --center="OpenPKG" --release="RC(8)"         --date="OpenPKG
 pod2man --section=8 --center="OpenPKG" --release="RPMTOOL(8)"    --date="OpenPKG" --quotes=none rpmtool.pod    >rpmtool.8
 pod2man --section=8 --center="OpenPKG" --release="LSYNC(8)"      --date="OpenPKG" --quotes=none lsync.pod      >lsync.8
 pod2man --section=8 --center="OpenPKG" --release="RPM-CONFIG(8)" --date="OpenPKG" --quotes=none rpm-config.pod >rpm-config.8
+pod2man --section=8 --center="OpenPKG" --release="UUID(8)"       --date="OpenPKG" --quotes=none uuid.pod       >uuid.8

openpkg/rc.8

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
 .\"
 .\" Standard preamble:
 .\" ========================================================================

openpkg/rpm-config.8

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
 .\"
 .\" Standard preamble:
 .\" ========================================================================

openpkg/rpmtool.8

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
 .\"
 .\" Standard preamble:
 .\" ========================================================================

openpkg/uuid.8

@@ -0,0 +1,252 @@
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  | will give a
+.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` 
+.    ds C' 
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+.    de IX
+.    tm Index:\\$1\t\\n%\t"\\$2"
+..
+.    nr % 0
+.    rr F
+.\}
+.\"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
+.    \" fudge factors for nroff and troff
+.if n \{\
+.    ds #H 0
+.    ds #V .8m
+.    ds #F .3m
+.    ds #[ \f1
+.    ds #] \fP
+.\}
+.if t \{\
+.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+.    ds #V .6m
+.    ds #F 0
+.    ds #[ \&
+.    ds #] \&
+.\}
+.    \" simple accents for nroff and troff
+.if n \{\
+.    ds ' \&
+.    ds ` \&
+.    ds ^ \&
+.    ds , \&
+.    ds ~ ~
+.    ds /
+.\}
+.if t \{\
+.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+.    \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+.    \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+.    \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+.    ds : e
+.    ds 8 ss
+.    ds o a
+.    ds d- d\h'-1'\(ga
+.    ds D- D\h'-1'\(hy
+.    ds th \o'bp'
+.    ds Th \o'LP'
+.    ds ae ae
+.    ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "UUID 8"
+.TH UUID 8 "OpenPKG" "UUID(8)" "OpenPKG"
+.SH "NAME"
+\&\fBopenpkg uuid\fR \- OpenPKG UUID Update Utility
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+\&\fBopenpkg uuid\fR [\fB\-\-verbose\fR] [\fB\-\-multicast\fR] \fBreset\fR|\fBupdate\fR|\fBinfo\fR
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+The \fBopenpkg uuid\fR command is the maintenance utility for the \s-1DCE\s0 1.1
+and \s-1ISO/IEC\s0 11578:1996 compliant \fIUniversally Unique Identifiers\fR
+(\s-1UUID\s0) of an \fBOpenPKG\fR instance. It is internally based on \fB\s-1OSSP\s0
+uuid\fR.
+.PP
+UUIDs are 128 bit numbers which are intended to have a high likelihood
+of uniqueness over space and time and are computationally difficult
+to guess. They are globally unique identifiers which can be locally
+generated without contacting a global registration authority. UUIDs are
+intended as unique identifiers for both mass tagging objects with an
+extremely short lifetime and to reliably identifying very persistent
+objects across a network. The three classical \s-1UUID\s0 variants are \s-1DCE\s0 1.1
+UUIDs of version 1 (time and node based), version 3 (name based) and
+version 4 (random number based).
+.PP
+For an \fBOpenPKG\fR instance, three different UUIDs are used:
+.ie n .IP "1. \fBOpenPKG Registry\fR (\*(C`UUID_REGISTRY\*(C')" 3
+.el .IP "1. \fBOpenPKG Registry\fR (\f(CW\*(C`UUID_REGISTRY\*(C'\fR)" 3
+.IX Item "1. OpenPKG Registry (UUID_REGISTRY)"
+This is a version 1 \s-1UUID\s0 which uniquely identifiers the \fBOpenPKG\fR
+instance for global registration purposes. It is generated just once in
+the lifetime of the \fBOpenPKG\fR instance. The value of this \s-1UUID\s0 cannot
+be recalculated deterministically.
+.ie n .IP "2. \fBOpenPKG Instance\fR (\*(C`UUID_INSTANCE\*(C')" 3
+.el .IP "2. \fBOpenPKG Instance\fR (\f(CW\*(C`UUID_INSTANCE\*(C'\fR)" 3
+.IX Item "2. OpenPKG Instance (UUID_INSTANCE)"
+This is a version 3 \s-1UUID\s0 which summarizes the \fBOpenPKG\fR
+instance parameters. Currently the values of the following
+particular OpenPKG \s-1RPM\s0 macros are uses as input:
+.Sp
+.Vb 5
+\& %{l_openpkg_release} %{l_prefix}
+\& %{l_susr} %{l_suid} %{l_sgrp} %{l_sgid}
+\& %{l_musr} %{l_muid} %{l_mgrp} %{l_mgid}
+\& %{l_rusr} %{l_ruid} %{l_rgrp} %{l_rgid}
+\& %{l_nusr} %{l_nuid} %{l_ngrp} %{l_ngid}
+.Ve
+.Sp
+The value of this \s-1UUID\s0 can be recalculated deterministically and will
+not chance as long as none of the values of the above macro do not
+change. This \s-1UUID\s0 can be used for detecting OpenPKG release upgrades,
+accidentally changed UIDs or GIDs, etc. Notice that version 3 UUIDs are
+message digests (actually \s-1MD5\s0 based) and so are one-way functions which do
+not allow one to recalculate the input values from the \s-1UUID\s0.
+.ie n .IP "3. \fBOpenPKG Platform\fR (\*(C`UUID_PLATFORM\*(C')" 3
+.el .IP "3. \fBOpenPKG Platform\fR (\f(CW\*(C`UUID_PLATFORM\*(C'\fR)" 3
+.IX Item "3. OpenPKG Platform (UUID_PLATFORM)"
+This is a version 3 \s-1UUID\s0 which summarizes the \fBOpenPKG\fR platform
+parameters. Currently the OpenPKG \s-1RPM\s0 platform id plus the \s-1FQDN\s0 and \s-1IP\s0
+address of the underlying host are used as input. This \s-1UUID\s0 can be used
+for detecting operating system and host changes. Notice that version
+3 UUIDs are message digests (actually \s-1MD5\s0 based) and so are one-way
+functions which do not allow one to recalculate the input values from
+the \s-1UUID\s0.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+.IP "\fB\-\-verbose\fR" 4
+.IX Item "--verbose"
+Print verbose messages during operation.
+.IP "\fB\-\-multicast\fR" 4
+.IX Item "--multicast"
+Generate a random multicast \s-1MAC\s0 address instead of using the real \s-1IEEE\s0
+802 \s-1MAC\s0 address of the underlying host when generating the version 1
+\&\s-1UUID\s0 \f(CW\*(C`UUID_REGISTRY\*(C'\fR.
+.SH "COMMANDS"
+.IX Header "COMMANDS"
+.IP "\fBreset\fR" 4
+.IX Item "reset"
+This resets the three UUIDs \f(CW\*(C`UUID_REGISTRY\*(C'\fR, \f(CW\*(C`UUID_INSTANCE\*(C'\fR and
+\&\f(CW\*(C`UUID_PLATFORM\*(C'\fR to the \*(L"Nil \s-1UUID\s0\*(R". They are then automatically
+regenerated within one day if already done explicitly afterward with
+"\f(CW\*(C`openpkg uuid update\*(C'\fR".
+.IP "\fBupdate\fR" 4
+.IX Item "update"
+This updates the three UUIDs \f(CW\*(C`UUID_REGISTRY\*(C'\fR, \f(CW\*(C`UUID_INSTANCE\*(C'\fR and
+\&\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
+is the \*(L"Nil \s-1UUID\s0\*(R" (see "\f(CW\*(C`openpkg uuid reset\*(C'\fR" command above). The UUIDs
+\&\f(CW\*(C`UUID_INSTANCE\*(C'\fR and \f(CW\*(C`UUID_PLATFORM\*(C'\fR are updated only if their input
+values (and this way the resulting UUIDs) have changed. This operation
+is performed daily automatically.
+.IP "\fBinfo\fR" 4
+.IX Item "info"
+This print summary page of identification information, including all
+UUIDs and all of their calculation inputs.
+.SH "FILES"
+.IX Header "FILES"
+The three UUIDs of the \fBOpenPKG\fR instance are stored in the file
+\&\f(CW\*(C`@l_prefix@/etc/openpkg/uuid\*(C'\fR in Bourne-Shell syntax. An example
+content is:
+.PP
+.Vb 3
+\& UUID_REGISTRY="81eca44e-4d18-11d8-a837-0090272ff725"
+\& UUID_INSTANCE="c55a8d2d-31bb-3ae0-9edb-68337af61acc"
+\& UUID_PLATFORM="05ec2532-9e3f-37dc-a7ed-b291c2c463ed"
+.Ve
+.SH "CAVEATS"
+.IX Header "CAVEATS"
+By default and in full compliance with \s-1DCE\s0 1.1 and \s-1ISO/IEC\s0 11578:1996,
+the OpenPKG Registry \s-1UUID\s0 (\f(CW\*(C`UUID_REGISTRY\*(C'\fR) contains the \s-1IEEE\s0 802 \s-1MAC\s0
+address of the underlying host. If this is not acceptable by local
+security policies you can easily at any time generate a new OpenPKG
+Registry \s-1UUID\s0 with a random multicast \s-1MAC\s0 address instead by running:
+.PP
+.Vb 2
+\& $ openpkg uuid reset
+\& $ openpkg uuid --multicast update
+.Ve
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fB\s-1OSSP\s0 uuid\fR <http://www.ossp.org/pkg/lib/uuid/>.
+.SH "HISTORY"
+.IX Header "HISTORY"
+The \fBopenpkg uuid\fR command first appeared in \fBOpenPKG 2.0\fR.

openpkg/uuid.pod

@@ -0,0 +1,168 @@
+##
+##  uuid -- OpenPKG UUID Update Utility
+##  Copyright (c) 2000-2004 The OpenPKG Project <http://www.openpkg.org/>
+##  Copyright (c) 2000-2004 Ralf S. Engelschall <rse@engelschall.com>
+##  Copyright (c) 2000-2004 Cable & Wireless <http://www.cw.com/>
+##
+##  Permission to use, copy, modify, and distribute this software for
+##  any purpose with or without fee is hereby granted, provided that
+##  the above copyright notice and this permission notice appear in all
+##  copies.
+##
+##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+##  SUCH DAMAGE.
+##
+
+=pod
+
+=head1 NAME
+
+B<openpkg uuid> - OpenPKG UUID Update Utility
+
+=head1 SYNOPSIS
+
+B<openpkg uuid> [B<--verbose>] [B<--multicast>] B<reset>|B<update>|B<info>
+
+=head1 DESCRIPTION
+
+The B<openpkg uuid> command is the maintenance utility for the DCE 1.1
+and ISO/IEC 11578:1996 compliant I<Universally Unique Identifiers>
+(UUID) of an B<OpenPKG> instance. It is internally based on B<OSSP
+uuid>.
+
+UUIDs are 128 bit numbers which are intended to have a high likelihood
+of uniqueness over space and time and are computationally difficult
+to guess. They are globally unique identifiers which can be locally
+generated without contacting a global registration authority. UUIDs are
+intended as unique identifiers for both mass tagging objects with an
+extremely short lifetime and to reliably identifying very persistent
+objects across a network. The three classical UUID variants are DCE 1.1
+UUIDs of version 1 (time and node based), version 3 (name based) and
+version 4 (random number based).
+
+For an B<OpenPKG> instance, three different UUIDs are used:
+
+=over 3
+
+=item 1. B<OpenPKG Registry> (C<UUID_REGISTRY>)
+
+This is a version 1 UUID which uniquely identifiers the B<OpenPKG>
+instance for global registration purposes. It is generated just once in
+the lifetime of the B<OpenPKG> instance. The value of this UUID cannot
+be recalculated deterministically.
+
+=item 2. B<OpenPKG Instance> (C<UUID_INSTANCE>)
+
+This is a version 3 UUID which summarizes the B<OpenPKG>
+instance parameters. Currently the values of the following
+particular OpenPKG RPM macros are uses as input:
+
+ %{l_openpkg_release} %{l_prefix}
+ %{l_susr} %{l_suid} %{l_sgrp} %{l_sgid}
+ %{l_musr} %{l_muid} %{l_mgrp} %{l_mgid}
+ %{l_rusr} %{l_ruid} %{l_rgrp} %{l_rgid}
+ %{l_nusr} %{l_nuid} %{l_ngrp} %{l_ngid}
+
+The value of this UUID can be recalculated deterministically and will
+not chance as long as none of the values of the above macro do not
+change. This UUID can be used for detecting OpenPKG release upgrades,
+accidentally changed UIDs or GIDs, etc. Notice that version 3 UUIDs are
+message digests (actually MD5 based) and so are one-way functions which do
+not allow one to recalculate the input values from the UUID.
+
+=item 3. B<OpenPKG Platform> (C<UUID_PLATFORM>)
+
+This is a version 3 UUID which summarizes the B<OpenPKG> platform
+parameters. Currently the OpenPKG RPM platform id plus the FQDN and IP
+address of the underlying host are used as input. This UUID can be used
+for detecting operating system and host changes. Notice that version
+3 UUIDs are message digests (actually MD5 based) and so are one-way
+functions which do not allow one to recalculate the input values from
+the UUID.
+
+=back
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--verbose>
+
+Print verbose messages during operation.
+
+=item B<--multicast>
+
+Generate a random multicast MAC address instead of using the real IEEE
+802 MAC address of the underlying host when generating the version 1
+UUID C<UUID_REGISTRY>.
+
+=back
+
+=head1 COMMANDS
+
+=over 4
+
+=item B<reset>
+
+This resets the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and
+C<UUID_PLATFORM> to the "Nil UUID". They are then automatically
+regenerated within one day if already done explicitly afterward with
+"C<openpkg uuid update>".
+
+=item B<update>
+
+This updates the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and
+C<UUID_PLATFORM> to the "Nil UUID". C<UUID_REGISTRY> is kept unless it
+is the "Nil UUID" (see "C<openpkg uuid reset>" command above). The UUIDs
+C<UUID_INSTANCE> and C<UUID_PLATFORM> are updated only if their input
+values (and this way the resulting UUIDs) have changed. This operation
+is performed daily automatically.
+
+=item B<info>
+
+This print summary page of identification information, including all
+UUIDs and all of their calculation inputs.
+
+=back
+
+=head1 FILES
+
+The three UUIDs of the B<OpenPKG> instance are stored in the file
+C<@l_prefix@/etc/openpkg/uuid> in Bourne-Shell syntax. An example
+content is:
+
+ UUID_REGISTRY="81eca44e-4d18-11d8-a837-0090272ff725"
+ UUID_INSTANCE="c55a8d2d-31bb-3ae0-9edb-68337af61acc"
+ UUID_PLATFORM="05ec2532-9e3f-37dc-a7ed-b291c2c463ed"
+
+=head1 CAVEATS
+
+By default and in full compliance with DCE 1.1 and ISO/IEC 11578:1996,
+the OpenPKG Registry UUID (C<UUID_REGISTRY>) contains the IEEE 802 MAC
+address of the underlying host. If this is not acceptable by local
+security policies you can easily at any time generate a new OpenPKG
+Registry UUID with a random multicast MAC address instead by running:
+
+ $ openpkg uuid reset
+ $ openpkg uuid --multicast update
+
+=head1 SEE ALSO
+
+B<OSSP uuid> E<lt>http://www.ossp.org/pkg/lib/uuid/E<gt>.
+
+=head1 HISTORY
+
+The B<openpkg uuid> command first appeared in B<OpenPKG 2.0>.
+
+=cut
+