diff -r 333964c621f1 -r cb59d6afeb61 openpkg/uuid.pod
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/openpkg/uuid.pod	Tue Jan 06 23:40:39 2009 +0100
@@ -0,0 +1,167 @@
+##
+##  uuid -- OpenPKG UUID Update Utility
+##  Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
+##  Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.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
+