Add vdev_id for JBOD-friendly udev aliases

[zfs.git] / man / man8 / vdev_id.8

diff --git a/man/man8/vdev_id.8 b/man/man8/vdev_id.8
new file mode 100644 (file)
index 0000000..612a50b
--- /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)