man/man5/vdev_id.conf.5

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .Dd May 26, 2021
  12 .Dt VDEV_ID.CONF 5
  13 .Os
  14 .
  15 .Sh NAME
  16 .Nm vdev_id.conf
  17 .Nd configuration file for vdev_id(8)
  18 .Sh DESCRIPTION
  19 .Nm
  20 is the configuration file for
  21 .Xr vdev_id 8 .
  22 It controls the default behavior of
  23 .Xr vdev_id 8
  24 while it is mapping a disk device name to an alias.
  25 .Pp
  26 The
  27 .Nm
  28 file uses a simple format consisting of a keyword followed by one or
  29 more values on a single line.
  30 Any line not beginning with a recognized keyword is ignored.
  31 Comments may optionally begin with a hash character.
  32 .Pp
  33 The following keywords and values are used.
  34 .Bl -tag -width "-h"
  35 .It Sy alias Ar name Ar devlink
  36 Maps a device link in the
  37 .Pa /dev
  38 directory hierarchy to a new device name.
  39 The udev rule defining the device link must have run prior to
  40 .Xr vdev_id 8 .
  41 A defined alias takes precedence over a topology-derived name, but the
  42 two naming methods can otherwise coexist.
  43 For example, one might name drives in a JBOD with the
  44 .Sy sas_direct
  45 topology while naming an internal L2ARC device with an alias.
  46 .Pp
  47 .Ar name
  48 is the name of the link to the device that will by created under
  49 .Pa /dev/disk/by-vdev .
  50 .Pp
  51 .Ar devlink
  52 is the name of the device link that has already been
  53 defined by udev.
  54 This may be an absolute path or the base filename.
  55 .
  56 .It Sy channel [ Ns Ar pci_slot ] Ar port Ar name
  57 Maps a physical path to a channel name (typically representing a single
  58 disk enclosure).
  59 .
  60 .It Sy enclosure_symlinks Sy yes Ns | Ns Sy no
  61 Additionally create
  62 .Pa /dev/by-enclosure
  63 symlinks to the disk enclosure
  64 .Em sg
  65 devices using the naming scheme from
  66 .Pa vdev_id.conf .
  67 .Sy enclosure_symlinks
  68 is only allowed for
  69 .Sy sas_direct
  70 mode.
  71 .
  72 .It Sy enclosure_symlinks_prefix Ar prefix
  73 Specify the prefix for the enclosure symlinks in the form
  74 .Pa /dev/by-enclosure/ Ns Ao Ar prefix Ac Ns - Ns Ao Ar channel Ac Ns Aq Ar num
  75 .Pp
  76 Defaults to
  77 .Dq Em enc .
  78 .
  79 .It Sy slot Ar prefix Ar new Op Ar channel
  80 Maps a disk slot number as reported by the operating system to an
  81 alternative slot number.
  82 If the
  83 .Ar channel
  84 parameter is specified
  85 then the mapping is only applied to slots in the named channel,
  86 otherwise the mapping is applied to all channels.
  87 The first-specified
  88 .Ar slot
  89 rule that can match a slot takes precedence.
  90 Therefore a channel-specific mapping for a given slot should generally appear
  91 before a generic mapping for the same slot.
  92 In this way a custom mapping may be applied to a particular channel
  93 and a default mapping applied to the others.
  94 .
  95 .It Sy zpad_slot Ar digits
  96 Pad slot numbers with zeros to make them
  97 .Ar digits
  98 long, which can help to make disk names a consistent length and easier to sort.
  99 .
 100 .It Sy multipath Sy yes Ns | Ns Sy no
 101 Specifies whether
 102 .Xr vdev_id 8
 103 will handle only dm-multipath devices.
 104 If set to
 105 .Sy yes
 106 then
 107 .Xr vdev_id 8
 108 will examine the first running component disk of a dm-multipath
 109 device as provided by the driver command to determine the physical path.
 110 .
 111 .It Sy topology Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
 112 Identifies a physical topology that governs how physical paths are
 113 mapped to channels:
 114 .Bl -tag -compact -width "sas_direct and scsi"
 115 .It Sy sas_direct No and Sy scsi
 116 channels are uniquely identified by a PCI slot and HBA port number
 117 .It Sy sas_switch
 118 channels are uniquely identified by a SAS switch port number
 119 .El
 120 .
 121 .It Sy phys_per_port Ar num
 122 Specifies the number of PHY devices associated with a SAS HBA port or SAS
 123 switch port.
 124 .Xr vdev_id 8
 125 internally uses this value to determine which HBA or switch port a
 126 device is connected to.
 127 The default is
 128 .Sy 4 .
 129 .
 130 .It Sy slot Sy bay Ns | Ns Sy phy Ns | Ns Sy port Ns | Ns Sy id Ns | Ns Sy lun Ns | Ns Sy bay_lun Ns | Ns Sy ses
 131 Specifies from which element of a SAS identifier the slot number is
 132 taken.
 133 The default is
 134 .Sy bay :
 135 .Bl -tag -compact -width "port"
 136 .It Sy bay
 137 read the slot number from the bay identifier.
 138 .It Sy phy
 139 read the slot number from the phy identifier.
 140 .It Sy port
 141 use the SAS port as the slot number.
 142 .It Sy id
 143 use the scsi id as the slot number.
 144 .It Sy lun
 145 use the scsi lun as the slot number.
 146 .It Sy bay_lun
 147 read the slot number from the bay identifier and append the lun number.
 148 Useful for multi-lun multi-actuator hard drives.
 149 .It Sy ses
 150 use the SCSI Enclosure Services (SES) enclosure device slot number,
 151 as reported by
 152 .Xr sg_ses 8 .
 153 Intended for use only on systems where
 154 .Sy bay
 155 is unsupported,
 156 noting that
 157 .Sy port
 158 and
 159 .Sy id
 160 may be unstable across disk replacement.
 161 .El
 162 .El
 163 .
 164 .Sh FILES
 165 .Bl -tag -width "-v v"
 166 .It Pa /etc/zfs/vdev_id.conf
 167 The configuration file for
 168 .Xr vdev_id 8 .
 169 .El
 170 .
 171 .Sh EXAMPLES
 172 A non-multipath configuration with direct-attached SAS enclosures and an
 173 arbitrary slot re-mapping:
 174 .Bd -literal -compact -offset Ds
 175 multipath     no
 176 topology      sas_direct
 177 phys_per_port 4
 178 slot          bay
 179
 180 #       PCI_SLOT HBA PORT  CHANNEL NAME
 181 channel 85:00.0  1         A
 182 channel 85:00.0  0         B
 183 channel 86:00.0  1         C
 184 channel 86:00.0  0         D
 185
 186 # Custom mapping for Channel A
 187
 188 #    Linux      Mapped
 189 #    Slot       Slot      Channel
 190 slot 1          7         A
 191 slot 2          10        A
 192 slot 3          3         A
 193 slot 4          6         A
 194
 195 # Default mapping for B, C, and D
 196
 197 slot 1          4
 198 slot 2          2
 199 slot 3          1
 200 slot 4          3
 201 .Ed
 202 .Pp
 203 A SAS-switch topology.
 204 Note, that the
 205 .Ar channel
 206 keyword takes only two arguments in this example:
 207 .Bd -literal -compact -offset Ds
 208 topology      sas_switch
 209
 210 #       SWITCH PORT  CHANNEL NAME
 211 channel 1            A
 212 channel 2            B
 213 channel 3            C
 214 channel 4            D
 215 .Ed
 216 .Pp
 217 A multipath configuration.
 218 Note that channel names have multiple definitions - one per physical path:
 219 .Bd -literal -compact -offset Ds
 220 multipath yes
 221
 222 #       PCI_SLOT HBA PORT  CHANNEL NAME
 223 channel 85:00.0  1         A
 224 channel 85:00.0  0         B
 225 channel 86:00.0  1         A
 226 channel 86:00.0  0         B
 227 .Ed
 228 .Pp
 229 A configuration with enclosure_symlinks enabled:
 230 .Bd -literal -compact -offset Ds
 231 multipath yes
 232 enclosure_symlinks yes
 233
 234 #          PCI_ID      HBA PORT     CHANNEL NAME
 235 channel    05:00.0     1            U
 236 channel    05:00.0     0            L
 237 channel    06:00.0     1            U
 238 channel    06:00.0     0            L
 239 .Ed
 240 In addition to the disks symlinks, this configuration will create:
 241 .Bd -literal -compact -offset Ds
 242 /dev/by-enclosure/enc-L0
 243 /dev/by-enclosure/enc-L1
 244 /dev/by-enclosure/enc-U0
 245 /dev/by-enclosure/enc-U1
 246 .Ed
 247 .Pp
 248 A configuration using device link aliases:
 249 .Bd -literal -compact -offset Ds
 250 #     by-vdev
 251 #     name     fully qualified or base name of device link
 252 alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
 253 alias d2       wwn-0x5000c5002def789e
 254 .Ed
 255 .
 256 .Sh SEE ALSO
 257 .Xr vdev_id 8