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