| .\" |
| .\" This file and its contents are supplied under the terms of the |
| .\" Common Development and Distribution License ("CDDL"), version 1.0. |
| .\" You may only use this file in accordance with the terms of version |
| .\" 1.0 of the CDDL. |
| .\" |
| .\" A full copy of the text of the CDDL should have accompanied this |
| .\" source. A copy of the CDDL is also available via the Internet at |
| .\" http://www.illumos.org/license/CDDL. |
| .\" |
| .Dd May 26, 2021 |
| .Dt VDEV_ID 8 |
| .Os |
| . |
| .Sh NAME |
| .Nm vdev_id |
| .Nd generate user-friendly names for JBOD disks |
| .Sh SYNOPSIS |
| .Nm |
| .Fl d Ar dev |
| .Fl c Ar config_file |
| .Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi |
| .Fl m |
| .Fl p Ar phys_per_port |
| . |
| .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 |
| .Nm |
| also supports creating aliases based on existing udev links in the /dev |
| hierarchy using the |
| .Sy alias |
| configuration file keyword. |
| See |
| .Xr vdev_id.conf 5 |
| for details. |
| . |
| .Sh OPTIONS |
| .Bl -tag -width "-m" |
| .It Fl d Ar device |
| The device node to classify, like |
| .Pa /dev/sda . |
| .It Fl c Ar config_file |
| Specifies the path to an alternate configuration file. |
| 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: |
| .Bl -tag -compact -width "sas_direct and scsi" |
| .It Sy sas_direct No and Sy scsi |
| channels are uniquely identified by a PCI slot and HBA port number |
| .It Sy sas_switch |
| channels are uniquely identified by a SAS switch port number |
| .El |
| .It Fl m |
| Only handle dm-multipath devices. |
| If specified, examine the first running component disk of a dm-multipath |
| device as provided by the driver to determine the physical path. |
| .It Fl p Ar phys_per_port |
| Specifies the number of PHY devices associated with a SAS HBA port or SAS |
| switch port. |
| .Nm |
| internally uses this value to determine which HBA or switch port a |
| device is connected to. |
| The default is |
| .Sy 4 . |
| .It Fl h |
| Print a usage summary. |
| .El |
| . |
| .Sh SEE ALSO |
| .Xr vdev_id.conf 5 |