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
 =========================================================================
 
 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.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
 3. Configuration files
 4. Bugs and limitations
 5. Troubleshooting
@@ -134,14 +138,26 @@ host.
 
 Aliases may be removed with the 'deletedisk' command:
 
 
 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
 -------------------
 
   [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
 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
 
   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
 ----------------------
 
 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
 .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
 .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
 .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
 .TP
-\fBlistdisks\fP [OPTION] \(em List currently assigned block device aliases.
+.B listdisks
+List currently assigned block device aliases.
 .TP
 .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
 .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
 .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
 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
 .SH ENVIRONMENT VARIABLES
 .TP
 .B BA_DEBUG