Add comment headers to configuration and map files
[blkdevalias.git] / blkdevalias.8
1 .TH BLKDEVALIAS 8 "BLKDEVALIAS 0.08" "Red Hat" \" -*- nroff -*-
2 .SH NAME
3 blkdevalias \- a tool for managing persistent udev aliases and permissions
4 .SH SYNOPSIS
5 .B blkdevalias
6 [configure|createdisk|deletedisk|listdisks|scandisks|querydisk|map]
7 .SH DESCRIPTION
8 \fBblkdevalias\fP is a tool to manage persistent storage device aliases and
9 permissions. The \fBblkdevalias\fP script provides commands to allow the
10 user to create, remove and list the set of aliases and to control the
11 default user and group ownership and mode (permissions) of managed
12 devices.
13 .LP
14 Aliases are created as symbolic links within the \fB/dev\fP directory
15 using the standard Linux 2.6 udev dynamic device management
16 infrastructure[1]. The administrator may specify an arbitrary directory
17 under /dev in which to create the links.
18 .SH COMMANDS
19 The \fBblkdevalias\fP program provides the following commands:
20 .TP
21 \fBconfigure\fP \(em Display the configuration information and prompt the user to specify new values to be written to \fBblkdevalias.conf\fP(5).
22 .TP
23 \fBcreatedisk\fP [ALIAS] [DEVICE PATH] \(em Create a new alias for an existing block device.
24 .TP
25 \fBdeletedisk\fP [ALIAS] \(em Delete a previously created block device alias.
26 .TP
27 \fBlistdisks\fP [OPTION] \(em List currently assigned block device aliases.
28 .TP
29 \fBquerydisk\fP [OPTION] [ALIAS] \(em Query an alias to check whether it is valid.
30 .TP
31 \fBscandisks\fP \(em Not used by blkdevalias. Provided for compatibility.
32 .SH OPTIONS
33 The following options are available for some commands.
34 .TP
35 .B \-d ", " \-\-device
36 Causes \fBquerydisk\fP to display major and minor number of a managed device.
37 .LP
38 .SH ENVIRONMENT VARIABLES
39 .TP
40 .B BA_DEBUG
41 When set to the value "yes" causes additional debug messages to be written on stderr.
42 .SH BUGS & KNOWN ISSUES
43 The WWIDs used by \fBblkdevalias\fP are a property of the underlying
44 storage. This means that devices are assigned aliases by their
45 identity rather than their content so that if the content of a device
46 is moved from one disk to another the mapping must be updated.
47
48 Systems that use labels to identify the devices do not suffer this
49 limitation.
50
51 Root privileges or \fBsudo\fP(8) are currently required to immediately apply
52 changes to the active set of devices using the tool.
53 .SH DIAGNOSTICS
54 All tools return a status code of zero on success or non-zero on failure. An
55 exit status of 2 indictates that invalid arguments or options were provided
56 to a command.
57
58 Additional debug output may be obtained by setting the BA_DEBUG environment
59 variable (see \fBENVIRONMENT VARIABLES\fP). Debugging of the udev rules
60 used by blkdevalias may be accomplished by using the udevadm control command
61 to raise the udev log priority (see \fBudevadm\fP(8)).
62 .SH FILES
63 .I /etc/blkdevalias/blkdevalias.conf
64 .br
65 .I /etc/blkdevalias/blkdevalias.map
66 .SH SEE ALSO
67 .BR blkdevalias.conf (5),
68 .BR blkdevalias.map (5),
69 .BR udev (8),
70 .BR udevadm (8),
71 .BR scsi_id (8),
72 .BR blkid (8),
73 .BR multipath (8)
74 .SH HISTORY
75 The blkdevalias user interface mimics that of the oracleasm utility for many
76 common operations.
77 .SH AUTHORS
78 The \fBblkdevalias\fP program was written by Bryn M. Reeves, <bmr@redhat.com>.
79
80 \fBblkdevalias\fP is Copyright © Red Hat, Inc. 2012-2013. It is free
81 software; see the GNU General Public License version 2 for copying conditions.
82
83 There is NO WARRANTY.
84