Provided by: zfsutils-linux_0.7.5-1ubuntu16.12_amd64 bug

NAME

       vdev_id.conf - Configuration file for vdev_id

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.  Comments 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  precedence  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 - the name of the link to the device that will by created in /dev/disk/by-vdev.

              devlink  -  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).

              pci_slot - specifies the PCI SLOT of the HBA hosting the disk enclosure being mapped, as found  in
              the output of lspci(8).  This argument is not used in sas_switch mode.

              port  -  specifies  the  numeric  identifier  of  the HBA or SAS switch port connected to the disk
              enclosure being mapped.

              name - specifies the name of the channel.

       slot <old> <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.

       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 listed by the
              multipath(8) command to determine the physical path.

       topology <sas_direct|sas_switch>
              Identifies a physical topology that governs how physical paths are mapped to channels.

              sas_direct - in this mode a channel is uniquely identified by a PCI slot and a HBA port number

              sas_switch - in this mode a channel is 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>
              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.

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 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

FILES

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

SEE ALSO

       vdev_id(8)

                                                                                                 vdev_id.conf(5)