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