Add comment headers to configuration and map files
[blkdevalias.git] / README
1 blkdevalias 0.08                           Bryn M. Reeves <bmr@redhat.com> 
2
3                                README
4
5 blkdevalias - a tool for managing persistent udev aliases and permissions
6 =========================================================================
7
8 1. Introduction
9 2. Configuring blkdevalias
10  2.1. Configure default ownership and device path
11  2.2. Creating aliases
12   2.2.1. Updating the active device aliases
13  2.3. Removing aliases
14  2.4. Listing aliases
15 3. Configuration files
16 4. Bugs and limitations
17 5. Troubleshooting
18 6. Internals
19  
20
21 1. Introduction
22 ---------------
23
24 blkdevalias is a tool to manage persistent storage device aliases and
25 permissions. The blkdevalias script provides commands to allow the
26 user to create, remove and list the set of aliases and to control the
27 default user and group ownership and mode (permissions) of managed
28 devices.
29
30 Aliases are created as symbolic links within the /dev directory using the
31 standard Linux 2.6 udev dynamic device management infrastructure[1].
32 The administrator may specify an arbitrary directory under /dev in
33 which to create the links.
34
35 The current version of blkdevalias uses SCSI device identifiers
36 (WWIDs) to identify and assign aliases to devices. This guarantees
37 persistence even if storage is assigned a different identifier by the
38 operating system. Configuration may be copied between host systems
39 using shared storage to provide consistent mappings on each system.
40
41 When run with no arguments or command the script outputs a brief usage
42 message:
43
44   [root@rhel6-vm1 ~]# blkdevalias
45   Usage: /sbin/blkdevalias
46   {configure|createdisk|deletedisk|scandisks|querydisk|map}
47
48
49 2. Configuring blkdevalias
50 --------------------------
51
52 The blkdevalias package ships with default user, group and
53 permission settings for newly-created devices. Alternately the
54 administrator can specify values for these settings while configuring
55 the system.
56
57 2.1 Configuring default ownership and device path
58 -------------------------------------------------
59
60 To set the user, group and device directory for bldevalias manged
61 devices use the configure command:
62
63   [root@rhel6-vm1 ~]# blkdevalias configure
64   Configuring the blkdevalias map.
65   
66   This will configure persistent aliases and permissions for storage
67   devices. The current values will be shown in brackets ('[]'). Hitting
68   <ENTER> without typing an answer will keep the current value.
69   
70   Ctrl-C will abort.
71   
72   Default user to own device nodes [oracle]: dba
73   Default group to own device nodes [oracle]: dba
74   Default device directory [oracleasm/disks]:    
75
76 Alternately, edit the file /etc/blkdevalias/blkdevalis.conf directly:
77
78   [root@rhel6-vm1 ~]# cat /etc/blkdevalias/blkdevalias.conf 
79   BA_DEV_PATH="oracleasm/disks"
80   BA_USER="dba"
81   BA_GROUP="dba"
82
83   BA_DEV_PATH
84   -----------
85
86   BA_DEV_PATH contains the directory (relative to /dev) in which to
87   create symbolic links for managed devices. If the directory does not
88   exist it will be automatically created by udev.
89
90
91   BA_USER
92   -------
93   BA_USER specifies the UNIX user account that will own managed device
94   nodes.
95
96   BA_GROUP
97   --------
98   BA_GROUP specifies the UNIX group account that will own managed
99   device nodes.
100
101   BA_MODE
102   -------
103   BA_MODE specifies the UNIX file mode (permissions flags) to be
104   applied to managed device nodes.
105
106
107 2.2 Creating aliases
108 --------------------
109
110 The createdisk command is used to assign an alias:
111
112   [root@rhel6-vm1 ~]# blkdevalias createdisk DSK1 /dev/sda
113   [root@rhel6-vm1 ~]# 
114
115
116 2.2.1. Updating the active device aliases
117 -----------------------------------------
118
119 Devices are automatically refreshed following creation or deletion.
120 Device symlinks may be manually refreshed (for instance following a
121 manual edit to the device table or copying an existing device table
122 from another host) by issuing the refresh command:
123
124   [root@rhel6-vm1 ~]# blkdevalias refresh DSK1
125   [root@rhel6-vm1 ~]#
126
127 Note that refreshing active devices currently requires that the user
128 running blkdevalias have either root privileges or sudo access on the
129 host.
130
131
132 2.3 Removing aliases
133 --------------------
134
135 Aliases may be removed with the 'deletedisk' command:
136
137   [root@rhel6-vm1 ~]# blkdevalias delete DSK1
138   [root@rhel6-vm1 ~]# 
139
140
141 2.4 Listing aliases
142 -------------------
143
144 The current set of assigned aliases is displayed by the 'listdisks'
145 command:
146
147   [root@rhel6-vm1 ~]# blkdevalias listdisks
148   DSK1  /dev/oracleasm/disks/DSK1 -> ../../sda1
149   DSK2  /dev/oracleasm/disks/DSK2 -> ../../dm-5
150   DSK3  /dev/oracleasm/disks/DSK3 -> ../../dm-1
151   DSK4  /dev/oracleasm/disks/DSK4 -> ../../dm-4
152
153
154 3. Configuration files
155 ----------------------
156
157 Two configuration files exist in the /etc/blkdevalias directory:
158
159   [root@rhel6-vm1 ~]# ls -l /etc/blkdevalias/
160   total 8
161   -rw-------. 1 root root  59 Jan 17 18:49 blkdevalias.conf
162   -rw-------. 1 root root 193 Jan 17 18:52 blkdevalias.map
163
164 The first contains configuration options in shell variable format as
165 described in section 2.1.
166
167 The blkdevalias.map file contains a table of the current assigned
168 aliases; it is not typically necessary to edit this file directly and
169 the format and content of the file is subject to change in future
170 versions of the tool.
171
172
173 4. Bugs and limitations
174 -----------------------
175
176 The WWIDs used by blkdevalias are a property of the underlying
177 storage. This means that devices are assigned aliases by their
178 identity rather than their content so that if the content of a device
179 is moved from one disk to another the mapping must be updated.
180
181 Systems that use labels to identify the devices do not suffer this
182 limitation.
183
184 Root privileges or sudo(8) are currently required to immediately apply
185 changes to the active set of devices using the tool.
186
187
188 5. Troubleshooting
189 ------------------
190
191 All commands will produce verbose output when the BA_DEBUG environment
192 variable is set to "yes":
193
194 [root@rhel6-vm1 ~]# BA_DEBUG="yes" blkdevalias createdisk DSK4
195 /dev/mapper/mpathdp1 
196 ba_createdisk: DEV="/dev/mapper/mpathdp1" ALIAS="DSK4"
197 ba_scsi_id: getting ID for device /dev/mapper/mpathdp1
198 ba_scsi_id: calling "/sbin/scsi_id -g -u /dev/mapper/mpathd"
199 ba_createdisk: WWID="0QEMU_QEMU_HARDDISK_drive-scsi0-0-3"
200 ba_get_partnum: /dev/mapper/mpathdp1
201 ba_createdisk: PART="1"
202 ba_add_wwid_mapping: WWID="0QEMU_QEMU_HARDDISK_drive-scsi0-0-3"
203 ALIAS="DSK4" TYPE="mpath" PART="1"
204
205 Please include verbose output for failing commands when making bug
206 reports.
207
208 Reports of bugs or other problems using the tool may be sent to:
209
210   Bryn M. Reeves <bmr+blkdevalias@redhat.com>
211
212
213 6. Internals
214 ------------
215
216 The blkdevalias stuff is currently organised like this:
217
218 /sbin/blkdevalias:
219 Main script. Manages adding/removing/displaying mappings and maintains a
220 persistent table used to direct the udev rules.
221
222 /etc/blkdevalias/blkdevalias.map:
223 The persistent mapping table; currently just "<WWID> <ALIAS> <TYPE> <PART>".
224
225 /etc/blkdevalias/blkdevalias.conf:
226 Configuration of user/group, symlink/node directory etc.
227
228 /etc/udev/rules.d/99-blkdevalias.rules:
229 Rules to manage naming and permissions based on the persistent
230 configuration stored in the table.
231
232
233 [1] http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html