man/man5/vdev_id.conf.5

   1 .TH vdev_id.conf 5
   2 .SH NAME
   3 vdev_id.conf \- Configuration file for vdev_id
   4 .SH DESCRIPTION
   5 .I vdev_id.conf
   6 is the configuration file for
   7 .BR vdev_id (8).
   8 It controls the default behavior of
   9 .BR vdev_id (8)
  10 while it is mapping a disk device name to an alias.
  11 .PP
  12 The
  13 .I vdev_id.conf
  14 file uses a simple format consisting of a keyword followed by one or
  15 more values on a single line.  Any line not beginning with a recognized
  16 keyword is ignored.  Comments may optionally begin with a hash
  17 character.
  18
  19 The following keywords and values are used.
  20 .TP
  21 \fIalias\fR <name> <devlink>
  22 Maps a device link in the /dev directory hierarchy to a new device
  23 name.  The udev rule defining the device link must have run prior to
  24 .BR vdev_id (8).
  25 A defined alias takes precedence over a topology-derived name, but the
  26 two naming methods can otherwise coexist.  For example, one might name
  27 drives in a JBOD with the sas_direct topology while naming an internal
  28 L2ARC device with an alias.
  29
  30 \fIname\fR - the name of the link to the device that will by created in
  31 /dev/disk/by-vdev.
  32
  33 \fIdevlink\fR - the name of the device link that has already been
  34 defined by udev.  This may be an absolute path or the base filename.
  35
  36 .TP
  37 \fIchannel\fR [pci_slot] <port> <name>
  38 Maps a physical path to a channel name (typically representing a single
  39 disk enclosure).
  40
  41 \fIpci_slot\fR - specifies the PCI SLOT of the HBA
  42 hosting the disk enclosure being mapped, as found in the output of
  43 .BR lspci (8).
  44 This argument is not used in sas_switch mode.
  45
  46 \fIport\fR - specifies the numeric identifier of the HBA or SAS switch port
  47 connected to the disk enclosure being mapped.
  48
  49 \fIname\fR - specifies the name of the channel.
  50
  51 .TP
  52 \fIslot\fR <old> <new> [channel]
  53 Maps a disk slot number as reported by the operating system to an
  54 alternative slot number.  If the \fIchannel\fR parameter is specified
  55 then the mapping is only applied to slots in the named channel,
  56 otherwise the mapping is applied to all channels. The first-specified
  57 \fIslot\fR rule that can match a slot takes precedence.  Therefore a
  58 channel-specific mapping for a given slot should generally appear before
  59 a generic mapping for the same slot.  In this way a custom mapping may
  60 be applied to a particular channel and a default mapping applied to the
  61 others.
  62
  63 .TP
  64 \fImultipath\fR <yes|no>
  65 Specifies whether
  66 .BR vdev_id (8)
  67 will handle only dm-multipath devices.  If set to "yes" then
  68 .BR vdev_id (8)
  69 will examine the first running component disk of a dm-multipath
  70 device as listed by the
  71 .BR multipath (8)
  72 command to determine the physical path.
  73 .TP
  74 \fItopology\fR <sas_direct|sas_switch>
  75 Identifies a physical topology that governs how physical paths are
  76 mapped to channels.
  77
  78 \fIsas_direct\fR - in this mode a channel is uniquely identified by
  79 a PCI slot and a HBA port number
  80
  81 \fIsas_switch\fR - in this mode a channel is uniquely identified by
  82 a SAS switch port number
  83
  84 .TP
  85 \fIphys_per_port\fR <num>
  86 Specifies the number of PHY devices associated with a SAS HBA port or SAS
  87 switch port.
  88 .BR vdev_id (8)
  89 internally uses this value to determine which HBA or switch port a
  90 device is connected to.  The default is 4.
  91
  92 .TP
  93 \fIslot\fR <bay|phy|port|id|lun|ses>
  94 Specifies from which element of a SAS identifier the slot number is
  95 taken.  The default is bay.
  96
  97 \fIbay\fR - read the slot number from the bay identifier.
  98
  99 \fIphy\fR - read the slot number from the phy identifier.
 100
 101 \fIport\fR - use the SAS port as the slot number.
 102
 103 \fIid\fR - use the scsi id as the slot number.
 104
 105 \fIlun\fR - use the scsi lun as the slot number.
 106
 107 \fIses\fR - use the SCSI Enclosure Services (SES) enclosure device slot number,
 108 as reported by
 109 .BR sg_ses (8).
 110 This is intended for use only on systems where \fIbay\fR is unsupported,
 111 noting that \fIport\fR and \fIid\fR may be unstable across disk replacement.
 112 .SH EXAMPLES
 113 A non-multipath configuration with direct-attached SAS enclosures and an
 114 arbitrary slot re-mapping.
 115 .P
 116 .nf
 117         multipath     no
 118         topology      sas_direct
 119         phys_per_port 4
 120         slot          bay
 121
 122         #       PCI_SLOT HBA PORT  CHANNEL NAME
 123         channel 85:00.0  1         A
 124         channel 85:00.0  0         B
 125         channel 86:00.0  1         C
 126         channel 86:00.0  0         D
 127
 128         # Custom mapping for Channel A
 129
 130         #    Linux      Mapped
 131         #    Slot       Slot      Channel
 132         slot 1          7         A
 133         slot 2          10        A
 134         slot 3          3         A
 135         slot 4          6         A
 136
 137         # Default mapping for B, C, and D
 138
 139         slot 1          4
 140         slot 2          2
 141         slot 3          1
 142         slot 4          3
 143 .fi
 144 .P
 145 A SAS-switch topology.  Note that the
 146 .I channel
 147 keyword takes only two arguments in this example.
 148 .P
 149 .nf
 150         topology      sas_switch
 151
 152         #       SWITCH PORT  CHANNEL NAME
 153         channel 1            A
 154         channel 2            B
 155         channel 3            C
 156         channel 4            D
 157 .fi
 158 .P
 159 A multipath configuration.  Note that channel names have multiple
 160 definitions - one per physical path.
 161 .P
 162 .nf
 163         multipath yes
 164
 165         #       PCI_SLOT HBA PORT  CHANNEL NAME
 166         channel 85:00.0  1         A
 167         channel 85:00.0  0         B
 168         channel 86:00.0  1         A
 169         channel 86:00.0  0         B
 170 .fi
 171 .P
 172 A configuration using device link aliases.
 173 .P
 174 .nf
 175         #     by-vdev
 176         #     name     fully qualified or base name of device link
 177         alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
 178         alias d2       wwn-0x5000c5002def789e
 179 .fi
 180 .P
 181
 182 .SH FILES
 183 .TP
 184 .I /etc/zfs/vdev_id.conf
 185 The configuration file for
 186 .BR vdev_id (8).
 187 .SH SEE ALSO
 188 .BR vdev_id (8)