Add vdev_id for JBOD-friendly udev aliases

vdev_id parses the file /etc/zfs/vdev_id.conf to map a physical path
in a storage topology to a channel name.  The channel name is combined
with a disk enclosure slot number to create an alias that reflects the
physical location of the drive.  This is particularly helpful when it
comes to tasks like replacing failed drives.  Slot numbers may also be
re-mapped in case the default numbering is unsatisfactory.  The drive
aliases will be created as symbolic links in /dev/disk/by-vdev.

The only currently supported topologies are sas_direct and sas_switch:

o  sas_direct - a channel is uniquely identified by a PCI slot and a
   HBA port

o  sas_switch - a channel is uniquely identified by a SAS switch port

A multipath mode is supported in which dm-mpath devices are handled by
examining the first running component disk, as reported by 'multipath
-l'.  In multipath mode the configuration file should contain a
channel definition with the same name for each path to a given
enclosure.

vdev_id can replace the existing zpool_id script on systems where the
storage topology conforms to sas_direct or sas_switch.  The script
could be extended to support other topologies as well.  The advantage
of vdev_id is that it is driven by a single static input file that can
be shared across multiple nodes having a common storage toplogy.
zpool_id, on the other hand, requires a unique /etc/zfs/zdev.conf per
node and a separate slot-mapping file.  However, zpool_id provides the
flexibility of using any device names that show up in
/dev/disk/by-path, so it may still be needed on some systems.

vdev_id's functionality subsumes that of the sas_switch_id script, and
it is unlikely that anyone is using it, so sas_switch_id is removed.

Finally, /dev/disk/by-vdev is added to the list of directories that
'zpool import' will scan.

Signed-off-by: Brian Behlendorf <[email protected]>
Closes #713

3 files changed, 74 insertions, 2 deletions

diff --git a/man/man8/Makefile.am b/man/man8/Makefile.am
index 8f0227f88..619d74fc3 100644
--- a/man/man8/Makefile.am
+++ b/man/man8/Makefile.am
@@ -1,4 +1,4 @@
-man_MANS = zdb.8 zfs.8 zpool.8
+man_MANS = vdev_id.8 zdb.8 zfs.8 zpool.8
 EXTRA_DIST = $(man_MANS)
 
 install-data-local:
diff --git a/man/man8/Makefile.in b/man/man8/Makefile.in
index e50bb5a0e..feac99675 100644
--- a/man/man8/Makefile.in
+++ b/man/man8/Makefile.in
@@ -313,7 +313,7 @@ top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 udevdir = @udevdir@
 udevruledir = @udevruledir@
-man_MANS = zdb.8 zfs.8 zpool.8
+man_MANS = vdev_id.8 zdb.8 zfs.8 zpool.8
 EXTRA_DIST = $(man_MANS)
 all: all-am
 
diff --git a/man/man8/vdev_id.8 b/man/man8/vdev_id.8
new file mode 100644
index 000000000..612a50bbe
--- /dev/null
+++ b/man/man8/vdev_id.8
@@ -0,0 +1,72 @@
+.TH vdev_id 8
+.SH NAME
+vdev_id \- generate user-friendly names for JBOD disks
+.SH SYNOPSIS
+.LP
+.nf
+\fBvdev_id\fR <-d dev> [-c config_file] [-g sas_direct|sas_switch]
+                 [-m] [-p phys_per_port]
+\fBvdev_id\fR -h
+.fi
+.SH DESCRIPTION
+The \fBvdev_id\fR command is a udev helper which parses the file
+.BR /etc/zfs/vdev_id.conf (5)
+to map a physical path in a storage topology to a channel name.  The
+channel name is combined with a disk enclosure slot number to create an
+alias that reflects the physical location of the drive.  This is
+particularly helpful when it comes to tasks like replacing failed
+drives.  Slot numbers may also be re-mapped in case the default
+numbering is unsatisfactory.  The drive aliases will be created as
+symbolic links in /dev/disk/by-vdev.
+
+The only currently supported topologies are sas_direct and
+sas_switch.  A multipath mode is supported in which dm-mpath
+devices are handled by examining the first-listed running
+component disk as reported by the
+.BR multipath (8)
+command.  In multipath mode the configuration file should contain a
+channel definition with the same name for each path to a given
+enclosure.
+
+.SH OPTIONS
+.TP
+\fB\-c\fR <config_file>
+Specifies the path to an alternate configuration file.  The default is
+/etc/zfs/vdev_id.conf.
+.TP
+\fB\-d\fR <device>
+This is the only mandatory argument.  Specifies the name of a device
+in /dev, i.e. "sda".
+.TP
+\fB\-g\fR <sas_direct|sas_switch>
+Identifies a physical topology that governs how physical paths are
+mapped to channels.
+
+\fIsas_direct\fR - in this mode a channel is uniquely identified by
+a PCI slot and a HBA port number
+
+\fIsas_switch\fR - in this mode a channel is uniquely identified by
+a SAS switch port number
+.TP
+\fB\-m\fR
+Specifies that
+.BR vdev_id (8)
+will handle only dm-multipath devices.  If set to "yes" then
+.BR vdev_id (8)
+will examine the first running component disk of a dm-multipath
+device as listed by the
+.BR multipath (8)
+command to determine the physical path.
+.TP
+\fB\-p\fR <phys_per_port>
+Specifies the number of PHY devices associated with a SAS HBA port or SAS
+switch port.
+.BR vdev_id (8)
+internally uses this value to determine which HBA or switch port a
+device is connected to.  The default is 4.
+.TP
+\fB\-h\fR
+Print a usage summary.
+.SH SEE ALSO
+.LP
+\fBvdev_id.conf\fR(5)