| Emeric Vigier | 2f62582 | 2012-08-06 11:09:52 -0400 | [diff] [blame] | 1 | .\" |
| 2 | .\" dbus-uuidgen manual page. |
| 3 | .\" Copyright (C) 2006 Red Hat, Inc. |
| 4 | .\" |
| 5 | .TH dbus-uuidgen 1 |
| 6 | .SH NAME |
| 7 | dbus-uuidgen \- Utility to generate UUIDs |
| 8 | .SH SYNOPSIS |
| 9 | .PP |
| 10 | .B dbus-uuidgen [\-\-version] [\-\-ensure[=FILENAME]] [\-\-get[=FILENAME]] |
| 11 | |
| 12 | .SH DESCRIPTION |
| 13 | |
| 14 | The \fIdbus-uuidgen\fP command generates or reads a universally unique ID. |
| 15 | |
| 16 | .PP |
| 17 | Note that the D-Bus UUID has no relationship to RFC 4122 and does not generate |
| 18 | UUIDs compatible with that spec. Many systems have a separate command |
| 19 | for that (often called "uuidgen"). |
| 20 | |
| 21 | .PP |
| 22 | See http://www.freedesktop.org/software/dbus/ for more information |
| 23 | about D-Bus. |
| 24 | |
| 25 | .PP |
| 26 | The primary usage of \fIdbus-uuidgen\fP is to run in the post-install |
| 27 | script of a D-Bus package like this: |
| 28 | .nf |
| 29 | dbus-uuidgen --ensure |
| 30 | .fi |
| 31 | |
| 32 | .PP |
| 33 | This will ensure that /var/lib/dbus/machine-id exists and has the uuid in it. |
| 34 | It won't overwrite an existing uuid, since this id should remain fixed |
| 35 | for a single machine until the next reboot at least. |
| 36 | |
| 37 | .PP |
| 38 | The important properties of the machine UUID are that 1) it remains |
| 39 | unchanged until the next reboot and 2) it is different for any two |
| 40 | running instances of the OS kernel. That is, if two processes see the |
| 41 | same UUID, they should also see the same shared memory, UNIX domain |
| 42 | sockets, local X displays, localhost.localdomain resolution, process |
| 43 | IDs, and so forth. |
| 44 | |
| 45 | .PP |
| 46 | If you run \fIdbus-uuidgen\fP with no options it just prints a new uuid made |
| 47 | up out of thin air. |
| 48 | |
| 49 | .PP |
| 50 | If you run it with --get, it prints the machine UUID by default, or |
| 51 | the UUID in the specified file if you specify a file. |
| 52 | |
| 53 | .PP |
| 54 | If you try to change an existing machine-id on a running system, it will |
| 55 | probably result in bad things happening. Don't try to change this file. Also, |
| 56 | don't make it the same on two different systems; it needs to be different |
| 57 | anytime there are two different kernels running. |
| 58 | |
| 59 | .PP |
| 60 | The UUID should be different on two different virtual machines, |
| 61 | because there are two different kernels. |
| 62 | |
| 63 | .SH OPTIONS |
| 64 | The following options are supported: |
| 65 | .TP |
| 66 | .I "--get[=FILENAME]" |
| 67 | If a filename is not given, defaults to localstatedir/lib/dbus/machine-id |
| 68 | (localstatedir is usually /var). If this file exists and is valid, the |
| 69 | uuid in the file is printed on stdout. Otherwise, the command exits |
| 70 | with a nonzero status. |
| 71 | |
| 72 | .TP |
| 73 | .I "--ensure[=FILENAME]" |
| 74 | If a filename is not given, defaults to localstatedir/lib/dbus/machine-id |
| 75 | (localstatedir is usually /var). If this file exists then it will be |
| 76 | validated, and a failure code returned if it contains the wrong thing. |
| 77 | If the file does not exist, it will be created with a new uuid in it. |
| 78 | On success, prints no output. |
| 79 | |
| 80 | .TP |
| 81 | .I "--version" |
| 82 | Print the version of dbus-uuidgen |
| 83 | |
| 84 | .SH AUTHOR |
| 85 | See http://www.freedesktop.org/software/dbus/doc/AUTHORS |
| 86 | |
| 87 | .SH BUGS |
| 88 | Please send bug reports to the D-Bus mailing list or bug tracker, |
| 89 | see http://www.freedesktop.org/software/dbus/ |