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