Document scan and refresh commands
authorBryn M. Reeves <bmr@redhat.com>
Tue, 22 Jan 2013 13:20:49 +0000 (13:20 +0000)
committerBryn M. Reeves <bmr@redhat.com>
Tue, 22 Jan 2013 13:20:49 +0000 (13:20 +0000)
Add mention of the scandisks and refresh commands to the README
file and man page.

README
blkdevalias.8

diff --git a/README b/README
index a0f8bc4..685cee6 100644 (file)
--- a/README
+++ b/README
@@ -6,12 +6,16 @@ blkdevalias - a tool for managing persistent udev aliases and permissions
 =========================================================================
 
 1. Introduction
-2. Configuring blkdevalias
+2. Configuring and using blkdevalias
  2.1. Configure default ownership and device path
  2.2. Creating aliases
   2.2.1. Updating the active device aliases
  2.3. Removing aliases
- 2.4. Listing aliases
+ 2.4. Listing and scanning aliases
+  2.4.1 Listing aliases
+  2.4.2 Scanning active aliases
+  2.4.3 Refreshing all active aliases
+ 2.5 Command abbreviations
 3. Configuration files
 4. Bugs and limitations
 5. Troubleshooting
@@ -134,14 +138,26 @@ host.
 
 Aliases may be removed with the 'deletedisk' command:
 
-  [root@rhel6-vm1 ~]# blkdevalias delete DSK1
+  [root@rhel6-vm1 ~]# blkdevalias deletedisk DSK1
   [root@rhel6-vm1 ~]# 
 
 
 2.4 Listing aliases
 -------------------
 
-The current set of assigned aliases is displayed by the 'listdisks'
+The current set of assigned or active aliases is displayed by the
+'listdisks' and 'scandisks' commands.
+
+The 'listdisks' command displays each configured alias present in the
+map file. This may include devices that are not currently registered
+with the system. The 'scandisks' command scans the set of currently
+active aliases and can optionally refresh these devices to update
+names, ownership, and permissions.
+
+2.4.1 Listing aliases
+---------------------
+
+To list the currently configured aliases issue the 'listdisks'
 command:
 
   [root@rhel6-vm1 ~]# blkdevalias listdisks
@@ -150,6 +166,70 @@ command:
   DSK3  /dev/oracleasm/disks/DSK3 -> ../../dm-1
   DSK4  /dev/oracleasm/disks/DSK4 -> ../../dm-4
 
+The fields are:
+
+  ALIAS ALIAS PATH                   LINK TARGET
+  DSK1  /dev/oracleasm/disks/DSK1 -> ../../sda1
+
+
+2.4.2 Scanning active aliases
+-----------------------------
+
+To scan the current set of active aliases (as opposed to configured
+but possibly inactive aliases) issue the 'scandisks' command:
+
+  [root@rhel6-vm1 ~]# blkdevalias scandisks
+  /dev/oracleasm/disks/DSK1 0QEMU_QEMU_HARDDISK_drive-scsi0-0-0 sda
+  /dev/oracleasm/disks/DSK2 0QEMU_QEMU_HARDDISK_drive-scsi0-0-1 mpathbp1
+  /dev/oracleasm/disks/DSK3 0QEMU_QEMU_HARDDISK_drive-scsi0-0-2 mpathc
+  /dev/oracleasm/disks/DSK4 0QEMU_QEMU_HARDDISK_drive-scsi0-0-3 mpathdp1
+
+The fields are:
+
+  ALIAS PATH                WWID                                TARGET
+  /dev/oracleasm/disks/DSK1 0QEMU_QEMU_HARDDISK_drive-scsi0-0-0 sda
+
+
+2.4.3 Refreshing all active aliases
+-----------------------------------
+
+To additionally request a refresh of the device configuration, specify
+the '-r' option to the 'scandisks' command. For instance:
+
+  [root@rhel6-vm1 ~]# ll /dev/oracleasm/disks/DSK1
+  lrwxrwxrwx. 1 root root 9 Jan 22 12:26 /dev/../DSK1 -> ../../sda
+  [root@rhel6-vm1 ~]# ll /dev/sda
+  brw-rw----. 1 oracle oracle 8, 0 Jan 21 10:09 /dev/sda
+
+  # Change BA_MODE from 0660 -> 0600
+
+  [root@rhel6-vm1 ~]# blkdevalias scandisks -r
+  /dev/oracleasm/disks/DSK1 0QEMU_QEMU_HARDDISK_drive-scsi0-0-0 sda
+  /dev/oracleasm/disks/DSK2 0QEMU_QEMU_HARDDISK_drive-scsi0-0-1 mpathbp1
+  /dev/oracleasm/disks/DSK3 0QEMU_QEMU_HARDDISK_drive-scsi0-0-2 mpathc
+  /dev/oracleasm/disks/DSK4 0QEMU_QEMU_HARDDISK_drive-scsi0-0-3 mpathdp1
+  [root@rhel6-vm1 ~]# ll /dev/sda
+  brw-------. 1 oracle oracle 8, 0 Jan 21 10:09 /dev/sda
+
+Note that refreshing active devices currently requires that the user
+running blkdevalias have either root privileges or sudo access on the
+host.
+
+
+2.5 Command abbreviations
+-------------------------
+
+All blkdevalias commands may be abbreviated to omit the 'disk' or
+'disks' suffix in the name, for instance the following two command
+sequences produce identical results:
+
+  [root@rhel6-vm1 ~]# blkdevalias deletedisk DSK1
+  Removing wwid map disk "DSK1":                                  [  OK ]
+  [root@rhel6-vm1 ~]# blkdevalias createdisk DSK1 /dev/sda
+  [root@rhel6-vm1 ~]# blkdevalias delete DSK1
+  Removing wwid map disk "DSK1":                                  [  OK ]
+  [root@rhel6-vm1 ~]# blkdevalias create DSK1 /dev/sda
+  
 
 3. Configuration files
 ----------------------
index de5a1b3..56f52d1 100644 (file)
@@ -18,23 +18,37 @@ under /dev in which to create the links.
 .SH COMMANDS
 The \fBblkdevalias\fP program provides the following commands:
 .TP
-\fBconfigure\fP \(em Display the configuration information and prompt the user to specify new values to be written to \fBblkdevalias.conf\fP(5).
+.B configure
+Display the configuration information and prompt the user to specify new
+values to be written to \fBblkdevalias.conf\fP(5).
 .TP
-\fBcreatedisk\fP [ALIAS] [DEVICE PATH] \(em Create a new alias for an existing block device.
+\fBcreatedisk\fP \fI[ALIAS] [DEVICE PATH]\fI
+Create a new alias for an existing block device.
 .TP
-\fBdeletedisk\fP [ALIAS] \(em Delete a previously created block device alias.
+\fBdeletedisk\fP \fI[ALIAS]\fP
+Delete a previously assigned block device alias.
 .TP
-\fBlistdisks\fP [OPTION] \(em List currently assigned block device aliases.
+.B listdisks
+List currently assigned block device aliases.
 .TP
-\fBquerydisk\fP [OPTION] [ALIAS] \(em Query an alias to check whether it is valid.
+\fBquerydisk\fP \fI[-d] [ALIAS]\fP
+Query an alias to check whether it is valid.
 .TP
-\fBscandisks\fP \(em Not used by blkdevalias. Provided for compatibility.
+\fBscandisks\fP \fI[-r]\fP
+Scan all devices in the configured alias directory and print the alias path,
+WWID and target device. If the \fB\-r\fP option is given the command will
+also request udev to update the current device mappings. This may be used to
+update the system configuration after manually editing configuration files.
 .SH OPTIONS
 The following options are available for some commands.
 .TP
-.B \-d ", " \-\-device
+.B \-d
 Causes \fBquerydisk\fP to display major and minor number of a managed device.
 .LP
+.TP
+.B \-r
+Causes \fBscandisks\fP to refresh all discovered aliases.
+.LP
 .SH ENVIRONMENT VARIABLES
 .TP
 .B BA_DEBUG