1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/openpkg/uuid.pod Tue Jan 06 23:40:39 2009 +0100
1.3 @@ -0,0 +1,167 @@
1.4 +##
1.5 +## uuid -- OpenPKG UUID Update Utility
1.6 +## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/>
1.7 +## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/>
1.8 +##
1.9 +## Permission to use, copy, modify, and distribute this software for
1.10 +## any purpose with or without fee is hereby granted, provided that
1.11 +## the above copyright notice and this permission notice appear in all
1.12 +## copies.
1.13 +##
1.14 +## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
1.15 +## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1.16 +## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
1.17 +## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
1.18 +## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
1.19 +## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
1.20 +## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
1.21 +## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
1.22 +## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
1.23 +## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
1.24 +## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
1.25 +## SUCH DAMAGE.
1.26 +##
1.27 +
1.28 +=pod
1.29 +
1.30 +=head1 NAME
1.31 +
1.32 +B<openpkg uuid> - OpenPKG UUID Update Utility
1.33 +
1.34 +=head1 SYNOPSIS
1.35 +
1.36 +B<openpkg uuid> [B<--verbose>] [B<--multicast>] B<reset>|B<update>|B<info>
1.37 +
1.38 +=head1 DESCRIPTION
1.39 +
1.40 +The B<openpkg uuid> command is the maintenance utility for the DCE 1.1
1.41 +and ISO/IEC 11578:1996 compliant I<Universally Unique Identifiers>
1.42 +(UUID) of an B<OpenPKG> instance. It is internally based on B<OSSP
1.43 +uuid>.
1.44 +
1.45 +UUIDs are 128 bit numbers which are intended to have a high likelihood
1.46 +of uniqueness over space and time and are computationally difficult
1.47 +to guess. They are globally unique identifiers which can be locally
1.48 +generated without contacting a global registration authority. UUIDs are
1.49 +intended as unique identifiers for both mass tagging objects with an
1.50 +extremely short lifetime and to reliably identifying very persistent
1.51 +objects across a network. The three classical UUID variants are DCE 1.1
1.52 +UUIDs of version 1 (time and node based), version 3 (name based) and
1.53 +version 4 (random number based).
1.54 +
1.55 +For an B<OpenPKG> instance, three different UUIDs are used:
1.56 +
1.57 +=over 3
1.58 +
1.59 +=item 1. B<OpenPKG Registry> (C<UUID_REGISTRY>)
1.60 +
1.61 +This is a version 1 UUID which uniquely identifiers the B<OpenPKG>
1.62 +instance for global registration purposes. It is generated just once in
1.63 +the lifetime of the B<OpenPKG> instance. The value of this UUID cannot
1.64 +be recalculated deterministically.
1.65 +
1.66 +=item 2. B<OpenPKG Instance> (C<UUID_INSTANCE>)
1.67 +
1.68 +This is a version 3 UUID which summarizes the B<OpenPKG>
1.69 +instance parameters. Currently the values of the following
1.70 +particular OpenPKG RPM macros are uses as input:
1.71 +
1.72 + %{l_openpkg_release} %{l_prefix}
1.73 + %{l_susr} %{l_suid} %{l_sgrp} %{l_sgid}
1.74 + %{l_musr} %{l_muid} %{l_mgrp} %{l_mgid}
1.75 + %{l_rusr} %{l_ruid} %{l_rgrp} %{l_rgid}
1.76 + %{l_nusr} %{l_nuid} %{l_ngrp} %{l_ngid}
1.77 +
1.78 +The value of this UUID can be recalculated deterministically and will
1.79 +not chance as long as none of the values of the above macro do not
1.80 +change. This UUID can be used for detecting OpenPKG release upgrades,
1.81 +accidentally changed UIDs or GIDs, etc. Notice that version 3 UUIDs are
1.82 +message digests (actually MD5 based) and so are one-way functions which do
1.83 +not allow one to recalculate the input values from the UUID.
1.84 +
1.85 +=item 3. B<OpenPKG Platform> (C<UUID_PLATFORM>)
1.86 +
1.87 +This is a version 3 UUID which summarizes the B<OpenPKG> platform
1.88 +parameters. Currently the OpenPKG RPM platform id plus the FQDN and IP
1.89 +address of the underlying host are used as input. This UUID can be used
1.90 +for detecting operating system and host changes. Notice that version
1.91 +3 UUIDs are message digests (actually MD5 based) and so are one-way
1.92 +functions which do not allow one to recalculate the input values from
1.93 +the UUID.
1.94 +
1.95 +=back
1.96 +
1.97 +=head1 OPTIONS
1.98 +
1.99 +=over 4
1.100 +
1.101 +=item B<--verbose>
1.102 +
1.103 +Print verbose messages during operation.
1.104 +
1.105 +=item B<--multicast>
1.106 +
1.107 +Generate a random multicast MAC address instead of using the real IEEE
1.108 +802 MAC address of the underlying host when generating the version 1
1.109 +UUID C<UUID_REGISTRY>.
1.110 +
1.111 +=back
1.112 +
1.113 +=head1 COMMANDS
1.114 +
1.115 +=over 4
1.116 +
1.117 +=item B<reset>
1.118 +
1.119 +This resets the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and
1.120 +C<UUID_PLATFORM> to the "Nil UUID". They are then automatically
1.121 +regenerated within one day if already done explicitly afterward with
1.122 +"C<openpkg uuid update>".
1.123 +
1.124 +=item B<update>
1.125 +
1.126 +This updates the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and
1.127 +C<UUID_PLATFORM> to the "Nil UUID". C<UUID_REGISTRY> is kept unless it
1.128 +is the "Nil UUID" (see "C<openpkg uuid reset>" command above). The UUIDs
1.129 +C<UUID_INSTANCE> and C<UUID_PLATFORM> are updated only if their input
1.130 +values (and this way the resulting UUIDs) have changed. This operation
1.131 +is performed daily automatically.
1.132 +
1.133 +=item B<info>
1.134 +
1.135 +This print summary page of identification information, including all
1.136 +UUIDs and all of their calculation inputs.
1.137 +
1.138 +=back
1.139 +
1.140 +=head1 FILES
1.141 +
1.142 +The three UUIDs of the B<OpenPKG> instance are stored in the file
1.143 +C<@l_prefix@/etc/openpkg/uuid> in Bourne-Shell syntax. An example
1.144 +content is:
1.145 +
1.146 + UUID_REGISTRY="81eca44e-4d18-11d8-a837-0090272ff725"
1.147 + UUID_INSTANCE="c55a8d2d-31bb-3ae0-9edb-68337af61acc"
1.148 + UUID_PLATFORM="05ec2532-9e3f-37dc-a7ed-b291c2c463ed"
1.149 +
1.150 +=head1 CAVEATS
1.151 +
1.152 +By default and in full compliance with DCE 1.1 and ISO/IEC 11578:1996,
1.153 +the OpenPKG Registry UUID (C<UUID_REGISTRY>) contains the IEEE 802 MAC
1.154 +address of the underlying host. If this is not acceptable by local
1.155 +security policies you can easily at any time generate a new OpenPKG
1.156 +Registry UUID with a random multicast MAC address instead by running:
1.157 +
1.158 + $ openpkg uuid reset
1.159 + $ openpkg uuid --multicast update
1.160 +
1.161 +=head1 SEE ALSO
1.162 +
1.163 +B<OSSP uuid> E<lt>http://www.ossp.org/pkg/lib/uuid/E<gt>.
1.164 +
1.165 +=head1 HISTORY
1.166 +
1.167 +The B<openpkg uuid> command first appeared in B<OpenPKG 2.0>.
1.168 +
1.169 +=cut
1.170 +
