vdev_id.8: modernise, note scsi topology

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125

man/man8/vdev_id.8

@@ -1,77 +1,93 @@
-.TH VDEV_ID 8 "Aug 24, 2020" OpenZFS
+.\"
-.SH NAME
+.\" This file and its contents are supplied under the terms of the
-vdev_id \- generate user-friendly names for JBOD disks
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
-.SH SYNOPSIS
+.\" You may only use this file in accordance with the terms of version
-.LP
+.\" 1.0 of the CDDL.
-.nf
+.\"
-\fBvdev_id\fR <-d dev> [-c config_file] [-g sas_direct|sas_switch]
+.\" A full copy of the text of the CDDL should have accompanied this
-                 [-m] [-p phys_per_port]
+.\" source.  A copy of the CDDL is also available via the Internet at
-\fBvdev_id\fR -h
+.\" http://www.illumos.org/license/CDDL.
-.fi
+.\"
-.SH DESCRIPTION
+.Dd May 26, 2021
-The \fBvdev_id\fR command is a udev helper which parses the file
+.Dt VDEV_ID 8
-.BR /etc/zfs/vdev_id.conf (5)
+.Os
-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
+.Sh NAME
-alias that reflects the physical location of the drive.  This is
+.Nm vdev_id
-particularly helpful when it comes to tasks like replacing failed
+.Nd generate user-friendly names for JBOD disks
-drives.  Slot numbers may also be re-mapped in case the default
+.Sh SYNOPSIS
-numbering is unsatisfactory.  The drive aliases will be created as
+.Nm
-symbolic links in /dev/disk/by-vdev.
+.Fl d Ar dev
-
+.Fl c Ar config_file
-The currently supported topologies are sas_direct and sas_switch.  A
+.Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
-multipath mode is supported in which dm-mpath devices are handled by
+.Fl m
-examining the first-listed running component disk as reported by the
+.Fl p Ar phys_per_port
-.BR multipath (8)
+.
-command.  In multipath mode the configuration file should contain a
+.Sh DESCRIPTION
+.Nm
+is an udev helper which parses
+.Xr 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 remapped in case the default numbering is unsatisfactory.
+The drive aliases will be created as symbolic links in
+.Pa /dev/disk/by-vdev .
+.Pp
+The currently supported topologies are
+.Sy sas_direct ,
+.Sy sas_switch ,
+and
+.Sy scsi .
+A multipath mode is supported in which dm-mpath devices are handled by
+examining the first running component disk as reported by the driver.
+In multipath mode the configuration file should contain a
 channel definition with the same name for each path to a given
 enclosure.
-
+.Pp
-.BR vdev_id
+.Nm
 also supports creating aliases based on existing udev links in the /dev
-hierarchy using the \fIalias\fR configuration file keyword.  See the
+hierarchy using the
-.BR vdev_id.conf (5)
+.Sy alias
-man page for details.
+configuration file keyword.
-
+See
-.SH OPTIONS
+.Xr vdev_id.conf 5
-.TP
+for details.
-\fB\-c\fR <config_file>
+.
-Specifies the path to an alternate configuration file.  The default is
+.Sh OPTIONS
-/etc/zfs/vdev_id.conf.
+.Bl -tag -width "-m"
-.TP
+.It Fl d Ar device
-\fB\-d\fR <device>
+The device node to classify, like
-This is the only mandatory argument.  Specifies the name of a device
+.Pa /dev/sda .
-in /dev, i.e. "sda".
+.It Fl c Ar config_file
-.TP
+Specifies the path to an alternate configuration file.
-\fB\-g\fR <sas_direct|sas_switch>
+The default is
+.Pa /etc/zfs/vdev_id.conf .
+.It Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
 Identifies a physical topology that governs how physical paths are
-mapped to channels.
+mapped to channels:
-
+.Bl -tag -compact -width "sas_direct and scsi"
-\fIsas_direct\fR - in this mode a channel is uniquely identified by
+.It Sy sas_direct No and Sy scsi
-a PCI slot and a HBA port number
+channels are uniquely identified by a PCI slot and HBA port number
-
+.It Sy sas_switch
-\fIsas_switch\fR - in this mode a channel is uniquely identified by
+channels are uniquely identified by a SAS switch port number
-a SAS switch port number
+.El
-.TP
+.It Fl m
-\fB\-m\fR
+Only handle dm-multipath devices.
-Specifies that
+If specified, examine the first running component disk of a dm-multipath
-.BR vdev_id (8)
+device as provided by the driver to determine the physical path.
-will handle only dm-multipath devices.  If set to "yes" then
+.It Fl p Ar phys_per_port
-.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)
+.Nm
 internally uses this value to determine which HBA or switch port a
-device is connected to.  The default is 4.
+device is connected to.
-.TP
+The default is
-\fB\-h\fR
+.Sy 4 .
+.It Fl h
 Print a usage summary.
-.SH SEE ALSO
+.El
-.LP
+.
-\fBvdev_id.conf\fR(5)
+.Sh SEE ALSO
+.Xr vdev_id.conf 5