vdev_id.conf

VDEV_ID.CONF(5) File Formats Manual VDEV_ID.CONF(5)

NAME

   vdev_id.conf  configuration file for vdev_id(8)

DESCRIPTION

   vdev_id.conf is the configuration file for vdev_id(8).  It controls the default behavior of vdev_id(8) while it is mapping a disk device name to an alias.

   The vdev_id.conf file uses a simple format consisting of a keyword followed by one or more values on a single line.  Any line not beginning with a recognized keyword is ignored.  Com
   ments may optionally begin with a hash character.

   The following keywords and values are used.

   alias name devlink
       Maps  a  device link in the /dev directory hierarchy to a new device name.  The udev rule defining the device link must have run prior to vdev_id(8).  A defined alias takes prece
       dence over a topology-derived name, but the two naming methods can otherwise coexist.  For example, one might name drives in a JBOD with the sas_direct topology  while  naming  an
       internal L2ARC device with an alias.

       name is the name of the link to the device that will by created under /dev/disk/by-vdev.

       devlink is the name of the device link that has already been defined by udev.  This may be an absolute path or the base filename.

   channel [pci_slot] port name
       Maps a physical path to a channel name (typically representing a single disk enclosure).

   enclosure_symlinks yes|no
       Additionally create /dev/by-enclosure symlinks to the disk enclosure sg devices using the naming scheme from vdev_id.conf.  enclosure_symlinks is only allowed for sas_direct mode.

   enclosure_symlinks_prefix prefix
       Specify the prefix for the enclosure symlinks in the form /dev/by-enclosure/prefix-channelnum

       Defaults to enc.

   slot prefix new [channel]
       Maps  a disk slot number as reported by the operating system to an alternative slot number.  If the channel parameter is specified then the mapping is only applied to slots in the
       named channel, otherwise the mapping is applied to all channels.  The first-specified slot rule that can match a slot takes precedence.  Therefore a channel-specific mapping for a
       given slot should generally appear before a generic mapping for the same slot.  In this way a custom mapping may be applied to a particular channel and a default  mapping  applied
       to the others.

   zpad_slot digits
       Pad slot numbers with zeros to make them digits long, which can help to make disk names a consistent length and easier to sort.

   multipath yes|no
       Specifies  whether  vdev_id(8) will handle only dm-multipath devices.  If set to yes then vdev_id(8) will examine the first running component disk of a dm-multipath device as pro
       vided by the driver command to determine the physical path.

   topology sas_direct|sas_switch|scsi
       Identifies a physical topology that governs how physical paths are mapped to channels:
       sas_direct and scsi  channels are uniquely identified by a PCI slot and HBA port number
       sas_switch           channels are uniquely identified by a SAS switch port number

   phys_per_port num
       Specifies the number of PHY devices associated with a SAS HBA port or SAS switch port.  vdev_id(8) internally uses this value to determine which HBA or switch  port  a  device  is
       connected to.  The default is 4.

   slot bay|phy|port|id|lun|bay_lun|ses
       Specifies from which element of a SAS identifier the slot number is taken.  The default is bay:
       bay   read the slot number from the bay identifier.
       phy   read the slot number from the phy identifier.
       port  use the SAS port as the slot number.
       id    use the scsi id as the slot number.
       lun   use the scsi lun as the slot number.
       bay_lun
             read the slot number from the bay identifier and append the lun number.  Useful for multi-lun multi-actuator hard drives.
       ses   use  the  SCSI  Enclosure Services (SES) enclosure device slot number, as reported by sg_ses(8).  Intended for use only on systems where bay is unsupported, noting that port
             and id may be unstable across disk replacement.

FILES

   /etc/zfs/vdev_id.conf
         The configuration file for vdev_id(8).

EXAMPLES

   A non-multipath configuration with direct-attached SAS enclosures and an arbitrary slot re-mapping:
         multipath     no
         topology      sas_direct
         phys_per_port 4
         slot          bay

         #       PCI_SLOT HBA PORT  CHANNEL NAME
         channel 85:00.0  1         A
         channel 85:00.0  0         B
         channel 86:00.0  1         C
         channel 86:00.0  0         D

         # Custom mapping for Channel A

         #    Linux      Mapped
         #    Slot       Slot      Channel
         slot 1          7         A
         slot 2          10        A
         slot 3          3         A
         slot 4          6         A

         # Default mapping for B, C, and D

         slot 1          4
         slot 2          2
         slot 3          1
         slot 4          3

   A SAS-switch topology.  Note, that the channel keyword takes only two arguments in this example:
         topology      sas_switch

         #       SWITCH PORT  CHANNEL NAME
         channel 1            A
         channel 2            B
         channel 3            C
         channel 4            D

   A multipath configuration.  Note that channel names have multiple definitions - one per physical path:
         multipath yes

         #       PCI_SLOT HBA PORT  CHANNEL NAME
         channel 85:00.0  1         A
         channel 85:00.0  0         B
         channel 86:00.0  1         A
         channel 86:00.0  0         B

   A configuration with enclosure_symlinks enabled:
         multipath yes
         enclosure_symlinks yes

         #          PCI_ID      HBA PORT     CHANNEL NAME
         channel    05:00.0     1            U
         channel    05:00.0     0            L
         channel    06:00.0     1            U
         channel    06:00.0     0            L
   In addition to the disks symlinks, this configuration will create:
         /dev/by-enclosure/enc-L0
         /dev/by-enclosure/enc-L1
         /dev/by-enclosure/enc-U0
         /dev/by-enclosure/enc-U1

   A configuration using device link aliases:
         #     by-vdev
         #     name     fully qualified or base name of device link
         alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
         alias d2       wwn-0x5000c5002def789e

SEE ALSO

   vdev_id(8)

OpenZFS May 26, 2021 VDEV_ID.CONF(5)