Update README
authorBryn M. Reeves <bmr@redhat.com>
Fri, 18 Jan 2013 16:31:32 +0000 (16:31 +0000)
committerBryn M. Reeves <bmr@redhat.com>
Fri, 18 Jan 2013 16:31:32 +0000 (16:31 +0000)
README

diff --git a/README b/README
index 3429cad..a0f8bc4 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,217 @@
-blkdevalias is a tool to manage persistent storage device aliases and permissions
+blkdevalias 0.08                           Bryn M. Reeves <bmr@redhat.com> 
+
+                               README
+
+blkdevalias - a tool for managing persistent udev aliases and permissions
+=========================================================================
+
+1. Introduction
+2. Configuring 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
+3. Configuration files
+4. Bugs and limitations
+5. Troubleshooting
+6. Internals
+
+1. Introduction
+---------------
+
+blkdevalias is a tool to manage persistent storage device aliases and
+permissions. The blkdevalias script provides commands to allow the
+user to create, remove and list the set of aliases and to control the
+default user and group ownership and mode (permissions) of managed
+devices.
+
+Aliases are created as symbolic links within the /dev directory using the
+standard Linux 2.6 udev dynamic device management infrastructure[1].
+The administrator may specify an arbitrary directory under /dev in
+which to create the links.
+
+The current version of blkdevalias uses SCSI device identifiers
+(WWIDs) to identify and assign aliases to devices. This guarantees
+persistence even if storage is assigned a different identifier by the
+operating system. Configuration may be copied between host systems
+using shared storage to provide consistent mappings on each system.
+
+When run with no arguments or command the script outputs a brief usage
+message:
+
+  [root@rhel6-vm1 ~]# blkdevalias
+  Usage: /sbin/blkdevalias
+  {configure|createdisk|deletedisk|scandisks|querydisk|map}
+
+
+2. Configuring blkdevalias
+--------------------------
+
+The blkdevalias package ships with default user, group and
+permission settings for newly-created devices. Alternately the
+administrator can specify values for these settings while configuring
+the system.
+
+2.1 Configuring default ownership and device path
+-------------------------------------------------
+
+To set the user, group and device directory for bldevalias manged
+devices use the configure command:
+
+  [root@rhel6-vm1 ~]# blkdevalias configure
+  Configuring the blkdevalias map.
+  
+  This will configure persistent aliases and permissions for storage
+  devices. The current values will be shown in brackets ('[]'). Hitting
+  <ENTER> without typing an answer will keep the current value.
+  
+  Ctrl-C will abort.
+  
+  Default user to own device nodes [oracle]: dba
+  Default group to own device nodes [oracle]: dba
+  Default device directory [oracleasm/disks]:    
+
+Alternately, edit the file /etc/blkdevalias/blkdevalis.conf directly:
+
+  [root@rhel6-vm1 ~]# cat /etc/blkdevalias/blkdevalias.conf 
+  BA_DEV_PATH="oracleasm/disks"
+  BA_USER="dba"
+  BA_GROUP="dba"
+
+  BA_DEV_PATH
+  -----------
+
+  BA_DEV_PATH contains the directory (relative to /dev) in which to
+  create symbolic links for managed devices. If the directory does not
+  exist it will be automatically created by udev.
+
+
+  BA_USER
+  -------
+  BA_USER specifies the UNIX user account that will own managed device
+  nodes.
+
+  BA_GROUP
+  --------
+  BA_GROUP specifies the UNIX group account that will own managed
+  device nodes.
+
+  BA_MODE
+  -------
+  BA_MODE specifies the UNIX file mode (permissions flags) to be
+  applied to managed device nodes.
+
+
+2.2 Creating aliases
+--------------------
+
+The createdisk command is used to assign an alias:
+
+  [root@rhel6-vm1 ~]# blkdevalias createdisk DSK1 /dev/sda
+  [root@rhel6-vm1 ~]# 
+
+
+2.2.1. Updating the active device aliases
+-----------------------------------------
+
+Devices are automatically refreshed following creation or deletion.
+Device symlinks may be manually refreshed (for instance following a
+manual edit to the device table or copying an existing device table
+from another host) by issuing the refresh command:
+
+  [root@rhel6-vm1 ~]# blkdevalias refresh DSK1
+  [root@rhel6-vm1 ~]#
+
+Note that refreshing active devices currently requires that the user
+running blkdevalias have either root privileges or sudo access on the
+host.
+
+
+2.3 Removing aliases
+--------------------
+
+Aliases may be removed with the 'deletedisk' command:
+
+  [root@rhel6-vm1 ~]# blkdevalias delete DSK1
+  [root@rhel6-vm1 ~]# 
+
+
+2.4 Listing aliases
+-------------------
+
+The current set of assigned aliases is displayed by the 'listdisks'
+command:
+
+  [root@rhel6-vm1 ~]# blkdevalias listdisks
+  DSK1  /dev/oracleasm/disks/DSK1 -> ../../sda1
+  DSK2  /dev/oracleasm/disks/DSK2 -> ../../dm-5
+  DSK3  /dev/oracleasm/disks/DSK3 -> ../../dm-1
+  DSK4  /dev/oracleasm/disks/DSK4 -> ../../dm-4
+
+
+3. Configuration files
+----------------------
+
+Two configuration files exist in the /etc/blkdevalias directory:
+
+  [root@rhel6-vm1 ~]# ls -l /etc/blkdevalias/
+  total 8
+  -rw-------. 1 root root  59 Jan 17 18:49 blkdevalias.conf
+  -rw-------. 1 root root 193 Jan 17 18:52 blkdevalias.map
+
+The first contains configuration options in shell variable format as
+described in section 2.1.
+
+The blkdevalias.map file contains a table of the current assigned
+aliases; it is not typically necessary to edit this file directly and
+the format and content of the file is subject to change in future
+versions of the tool.
+
+
+4. Bugs and limitations
+-----------------------
+
+The WWIDs used by blkdevalias are a property of the underlying
+storage. This means that devices are assigned aliases by their
+identity rather than their content so that if the content of a device
+is moved from one disk to another the mapping must be updated.
+
+Systems that use labels to identify the devices do not suffer this
+limitation.
+
+Root privileges or sudo(8) are currently required to immediately apply
+changes to the active set of devices using the tool.
+
+
+5. Troubleshooting
+------------------
+
+All commands will produce verbose output when the BA_DEBUG environment
+variable is set to "yes":
+
+[root@rhel6-vm1 ~]# BA_DEBUG="yes" blkdevalias createdisk DSK4
+/dev/mapper/mpathdp1 
+ba_createdisk: DEV="/dev/mapper/mpathdp1" ALIAS="DSK4"
+ba_scsi_id: getting ID for device /dev/mapper/mpathdp1
+ba_scsi_id: calling "/sbin/scsi_id -g -u /dev/mapper/mpathd"
+ba_createdisk: WWID="0QEMU_QEMU_HARDDISK_drive-scsi0-0-3"
+ba_get_partnum: /dev/mapper/mpathdp1
+ba_createdisk: PART="1"
+ba_add_wwid_mapping: WWID="0QEMU_QEMU_HARDDISK_drive-scsi0-0-3"
+ALIAS="DSK4" TYPE="mpath" PART="1"
+
+Please include verbose output for failing commands when making bug
+reports.
+
+Reports of bugs or other problems using the tool may be sent to:
+
+  Bryn M. Reeves <bmr+blkdevalias@redhat.com>
+
+
+6. Internals
+------------
 
 The blkdevalias stuff is currently organised like this:
 
@@ -7,7 +220,7 @@ Main script. Manages adding/removing/displaying mappings and maintains a
 persistent table used to direct the udev rules.
 
 /etc/blkdevalias/blkdevalias.map:
-The persistent mapping table; currently just "<WWID> <ALIAS> <TYPE>".
+The persistent mapping table; currently just "<WWID> <ALIAS> <TYPE> <PART>".
 
 /etc/blkdevalias/blkdevalias.conf:
 Configuration of user/group, symlink/node directory etc.
@@ -16,55 +229,5 @@ Configuration of user/group, symlink/node directory etc.
 Rules to manage naming and permissions based on the persistent
 configuration stored in the table.
 
-Feedback and testing very much welcome.
-
-[root@rhel6-vm1 ~]# blkdevalias
-Usage: /sbin/blkdevalias
-{configure|createdisk|deletedisk|scandisks|querydisk|map}
-[root@rhel6-vm1 ~]# blkdevalias configure
-Configuring the udev wwid map.
-
-This will configure persistent mappings and permissions for storage
-devices. The current values will be shown in brackets ('[]'). Hitting
-<ENTER> without typing an answer will keep the current value. Ctrl-C
-will abort.
-
-Default user to own device nodes [oracle]:
-Default group to own device nodes [oracle]:
-Default device directory [oracleasm/disks]:
-Writing wwid map configuration: done
-
-[root@rhel6-vm1 ~]# blkdevalias listdisks
-[root@rhel6-vm1 ~]# blkdevalias createdisk DSK1 /dev/sda
-[root@rhel6-vm1 ~]# blkdevalias createdisk DSK2 /dev/sdb
-[root@rhel6-vm1 ~]# blkdevalias createdisk DSK3 /dev/sdc
-[root@rhel6-vm1 ~]# blkdevalias createdisk DSK4 /dev/sdd
-[root@rhel6-vm1 ~]# blkdevalias listdisks
-DSK1
-DSK2
-DSK3
-DSK4
-[root@rhel6-vm1 ~]# blkdevalias querydisk DSK1
-DSK1 is a valid blkdevalias disk
-[root@rhel6-vm1 ~]# blkdevalias querydisk -d DSK4
-DSK4 is a valid blkdevalias diskon device [8, 31]
-[root@rhel6-vm1 ~]#
-[root@rhel6-vm1 ~]# blkdevalias deletedisk DSK4
-Removing wwid map disk "DSK4":                                  [  OK  ]
-[root@rhel6-vm1 ~]# blkdevalias listdisks
-DSK1
-DSK2
-DSK3
-[root@rhel6-vm1 ~]# ls -l /dev/oracleasm/disks/
-total 0
-lrwxrwxrwx. 1 root root 10 Oct 30 11:01 DSK1 -> ../../sda1
-lrwxrwxrwx. 1 root root 10 Oct 30 11:01 DSK2 -> ../../sdb1
-lrwxrwxrwx. 1 root root 10 Oct 30 11:01 DSK3 -> ../../sdc1
-lrwxrwxrwx. 1 root root 10 Oct 30 11:01 DSK4 -> ../../sdd1
-[root@rhel6-vm1 ~]# ls -lL /dev/oracleasm/disks/
-total 0
-brw-rw----. 1 root oracle 8,  1 Oct 30 11:01 DSK1
-brw-rw----. 1 root oracle 8, 17 Oct 30 11:01 DSK2
-brw-rw----. 1 root oracle 8, 33 Oct 30 11:01 DSK3
-brw-rw----. 1 root oracle 8, 49 Oct 30 11:01 DSK4
 
+[1] http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev/udev.html