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