OpenPKG Specs: openpkg/uuid.pod@a2c6460cfb16 (annotated)

openpkg/uuid.pod@a2c6460cfb16 (annotated)

openpkg/uuid.pod

Mon, 28 Jan 2013 17:37:18 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Mon, 28 Jan 2013 17:37:18 +0100
changeset 758: a2c6460cfb16
parent 13: cb59d6afeb61
permissions: -rw-r--r--

Correct socket error reporting improvement with IPv6 portable code,
after helpful recommendation by Saúl Ibarra Corretgé on OSips devlist.

 ##
 ##  uuid -- OpenPKG UUID Update Utility
 ##  Copyright (c) 2000-2012 OpenPKG GmbH <http://openpkg.com/>
 ##
 ##  This software is property of the OpenPKG GmbH, DE MUC HRB 160208.
 ##  All rights reserved. Licenses which grant limited permission to use,
 ##  copy, modify and distribute this software are available from the
 ##  OpenPKG GmbH.
 ##
 ##  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
 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
 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

OpenPKG Specs / annotate

openpkg/uuid.pod@a2c6460cfb16 (annotated)

openpkg/uuid.pod