comparison: openpkg/uuid.pod
openpkg/uuid.pod
- changeset 107
- 2f8ffdf7658b
- child 428
- f880f219c566
equal
deleted
inserted
replaced
| -1:000000000000 | 0:1fb357e4122c |
|---|---|
| 1 ## | |
| 2 ## uuid -- OpenPKG UUID Update Utility | |
| 3 ## Copyright (c) 2000-2007 OpenPKG Foundation e.V. <http://openpkg.net/> | |
| 4 ## Copyright (c) 2000-2007 Ralf S. Engelschall <http://engelschall.com/> | |
| 5 ## | |
| 6 ## Permission to use, copy, modify, and distribute this software for | |
| 7 ## any purpose with or without fee is hereby granted, provided that | |
| 8 ## the above copyright notice and this permission notice appear in all | |
| 9 ## copies. | |
| 10 ## | |
| 11 ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED | |
| 12 ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
| 13 ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | |
| 14 ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR | |
| 15 ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| 16 ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
| 17 ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF | |
| 18 ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND | |
| 19 ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | |
| 20 ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT | |
| 21 ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
| 22 ## SUCH DAMAGE. | |
| 23 ## | |
| 24 | |
| 25 =pod | |
| 26 | |
| 27 =head1 NAME | |
| 28 | |
| 29 B<openpkg uuid> - OpenPKG UUID Update Utility | |
| 30 | |
| 31 =head1 SYNOPSIS | |
| 32 | |
| 33 B<openpkg uuid> [B<--verbose>] [B<--multicast>] B<reset>|B<update>|B<info> | |
| 34 | |
| 35 =head1 DESCRIPTION | |
| 36 | |
| 37 The B<openpkg uuid> command is the maintenance utility for the DCE 1.1 | |
| 38 and ISO/IEC 11578:1996 compliant I<Universally Unique Identifiers> | |
| 39 (UUID) of an B<OpenPKG> instance. It is internally based on B<OSSP | |
| 40 uuid>. | |
| 41 | |
| 42 UUIDs are 128 bit numbers which are intended to have a high likelihood | |
| 43 of uniqueness over space and time and are computationally difficult | |
| 44 to guess. They are globally unique identifiers which can be locally | |
| 45 generated without contacting a global registration authority. UUIDs are | |
| 46 intended as unique identifiers for both mass tagging objects with an | |
| 47 extremely short lifetime and to reliably identifying very persistent | |
| 48 objects across a network. The three classical UUID variants are DCE 1.1 | |
| 49 UUIDs of version 1 (time and node based), version 3 (name based) and | |
| 50 version 4 (random number based). | |
| 51 | |
| 52 For an B<OpenPKG> instance, three different UUIDs are used: | |
| 53 | |
| 54 =over 3 | |
| 55 | |
| 56 =item 1. B<OpenPKG Registry> (C<UUID_REGISTRY>) | |
| 57 | |
| 58 This is a version 1 UUID which uniquely identifiers the B<OpenPKG> | |
| 59 instance for global registration purposes. It is generated just once in | |
| 60 the lifetime of the B<OpenPKG> instance. The value of this UUID cannot | |
| 61 be recalculated deterministically. | |
| 62 | |
| 63 =item 2. B<OpenPKG Instance> (C<UUID_INSTANCE>) | |
| 64 | |
| 65 This is a version 3 UUID which summarizes the B<OpenPKG> | |
| 66 instance parameters. Currently the values of the following | |
| 67 particular OpenPKG RPM macros are uses as input: | |
| 68 | |
| 69 %{l_openpkg_release} %{l_prefix} | |
| 70 %{l_susr} %{l_suid} %{l_sgrp} %{l_sgid} | |
| 71 %{l_musr} %{l_muid} %{l_mgrp} %{l_mgid} | |
| 72 %{l_rusr} %{l_ruid} %{l_rgrp} %{l_rgid} | |
| 73 %{l_nusr} %{l_nuid} %{l_ngrp} %{l_ngid} | |
| 74 | |
| 75 The value of this UUID can be recalculated deterministically and will | |
| 76 not chance as long as none of the values of the above macro do not | |
| 77 change. This UUID can be used for detecting OpenPKG release upgrades, | |
| 78 accidentally changed UIDs or GIDs, etc. Notice that version 3 UUIDs are | |
| 79 message digests (actually MD5 based) and so are one-way functions which do | |
| 80 not allow one to recalculate the input values from the UUID. | |
| 81 | |
| 82 =item 3. B<OpenPKG Platform> (C<UUID_PLATFORM>) | |
| 83 | |
| 84 This is a version 3 UUID which summarizes the B<OpenPKG> platform | |
| 85 parameters. Currently the OpenPKG RPM platform id plus the FQDN and IP | |
| 86 address of the underlying host are used as input. This UUID can be used | |
| 87 for detecting operating system and host changes. Notice that version | |
| 88 3 UUIDs are message digests (actually MD5 based) and so are one-way | |
| 89 functions which do not allow one to recalculate the input values from | |
| 90 the UUID. | |
| 91 | |
| 92 =back | |
| 93 | |
| 94 =head1 OPTIONS | |
| 95 | |
| 96 =over 4 | |
| 97 | |
| 98 =item B<--verbose> | |
| 99 | |
| 100 Print verbose messages during operation. | |
| 101 | |
| 102 =item B<--multicast> | |
| 103 | |
| 104 Generate a random multicast MAC address instead of using the real IEEE | |
| 105 802 MAC address of the underlying host when generating the version 1 | |
| 106 UUID C<UUID_REGISTRY>. | |
| 107 | |
| 108 =back | |
| 109 | |
| 110 =head1 COMMANDS | |
| 111 | |
| 112 =over 4 | |
| 113 | |
| 114 =item B<reset> | |
| 115 | |
| 116 This resets the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and | |
| 117 C<UUID_PLATFORM> to the "Nil UUID". They are then automatically | |
| 118 regenerated within one day if already done explicitly afterward with | |
| 119 "C<openpkg uuid update>". | |
| 120 | |
| 121 =item B<update> | |
| 122 | |
| 123 This updates the three UUIDs C<UUID_REGISTRY>, C<UUID_INSTANCE> and | |
| 124 C<UUID_PLATFORM> to the "Nil UUID". C<UUID_REGISTRY> is kept unless it | |
| 125 is the "Nil UUID" (see "C<openpkg uuid reset>" command above). The UUIDs | |
| 126 C<UUID_INSTANCE> and C<UUID_PLATFORM> are updated only if their input | |
| 127 values (and this way the resulting UUIDs) have changed. This operation | |
| 128 is performed daily automatically. | |
| 129 | |
| 130 =item B<info> | |
| 131 | |
| 132 This print summary page of identification information, including all | |
| 133 UUIDs and all of their calculation inputs. | |
| 134 | |
| 135 =back | |
| 136 | |
| 137 =head1 FILES | |
| 138 | |
| 139 The three UUIDs of the B<OpenPKG> instance are stored in the file | |
| 140 C<@l_prefix@/etc/openpkg/uuid> in Bourne-Shell syntax. An example | |
| 141 content is: | |
| 142 | |
| 143 UUID_REGISTRY="81eca44e-4d18-11d8-a837-0090272ff725" | |
| 144 UUID_INSTANCE="c55a8d2d-31bb-3ae0-9edb-68337af61acc" | |
| 145 UUID_PLATFORM="05ec2532-9e3f-37dc-a7ed-b291c2c463ed" | |
| 146 | |
| 147 =head1 CAVEATS | |
| 148 | |
| 149 By default and in full compliance with DCE 1.1 and ISO/IEC 11578:1996, | |
| 150 the OpenPKG Registry UUID (C<UUID_REGISTRY>) contains the IEEE 802 MAC | |
| 151 address of the underlying host. If this is not acceptable by local | |
| 152 security policies you can easily at any time generate a new OpenPKG | |
| 153 Registry UUID with a random multicast MAC address instead by running: | |
| 154 | |
| 155 $ openpkg uuid reset | |
| 156 $ openpkg uuid --multicast update | |
| 157 | |
| 158 =head1 SEE ALSO | |
| 159 | |
| 160 B<OSSP uuid> E<lt>http://www.ossp.org/pkg/lib/uuid/E<gt>. | |
| 161 | |
| 162 =head1 HISTORY | |
| 163 | |
| 164 The B<openpkg uuid> command first appeared in B<OpenPKG 2.0>. | |
| 165 | |
| 166 =cut | |
| 167 |
