OpenPKG Specs / file revision

 ##

 ##  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