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>
  53 Maps a disk slot number as reported by the operating system
  54 to an alternative slot number.
  55 .TP
  56 \fImultipath\fR <yes|no>
  57 Specifies whether
  58 .BR vdev_id (8)
  59 will handle only dm-multipath devices.  If set to "yes" then
  60 .BR vdev_id (8)
  61 will examine the first running component disk of a dm-multipath
  62 device as listed by the
  63 .BR multipath (8)
  64 command to determine the physical path.
  65 .TP
  66 \fItopology\fR <sas_direct|sas_switch>
  67 Identifies a physical topology that governs how physical paths are
  68 mapped to channels.
  69
  70 \fIsas_direct\fR - in this mode a channel is uniquely identified by
  71 a PCI slot and a HBA port number
  72
  73 \fIsas_switch\fR - in this mode a channel is uniquely identified by
  74 a SAS switch port number
  75
  76 .TP
  77 \fIphys_per_port\fR <num>
  78 Specifies the number of PHY devices associated with a SAS HBA port or SAS
  79 switch port.
  80 .BR vdev_id (8)
  81 internally uses this value to determine which HBA or switch port a
  82 device is connected to.  The default is 4.
  83 .SH EXAMPLES
  84 A non-multipath configuration with direct-attached SAS enclosures and an
  85 arbitrary slot re-mapping.
  86 .P
  87         multipath     no
  88 .br
  89         topology      sas_direct
  90 .br
  91         phys_per_port 4
  92 .br
  93
  94 .br
  95         #       PCI_SLOT HBA PORT  CHANNEL NAME
  96 .br
  97         channel 85:00.0  1         A
  98 .br
  99         channel 85:00.0  0         B
 100 .br
 101         channel 86:00.0  1         C
 102 .br
 103         channel 86:00.0  0         D
 104 .br
 105
 106 .br
 107         #    Linux      Mapped
 108 .br
 109         #    Slot       Slot
 110 .br
 111         slot 1          7
 112 .br
 113         slot 2          10
 114 .br
 115         slot 3          3
 116 .br
 117         slot 4          6
 118 .br
 119         slot 5          2
 120 .br
 121         slot 6          8
 122 .br
 123         slot 7          1
 124 .br
 125         slot 8          4
 126 .br
 127         slot 9          9
 128 .br
 129         slot 10         5
 130 .br
 131 .P
 132 A SAS-switch topology.  Note that the
 133 .I channel
 134 keyword takes only two arguments in this example.
 135 .P
 136         topology      sas_switch
 137 .br
 138
 139 .br
 140         #       SWITCH PORT  CHANNEL NAME
 141 .br
 142         channel 1            A
 143 .br
 144         channel 2            B
 145 .br
 146         channel 3            C
 147 .br
 148         channel 4            D
 149 .br
 150 .P
 151 A multipath configuration.  Note that channel names have multiple
 152 definitions - one per physical path.
 153 .P
 154         multipath yes
 155 .br
 156
 157 .br
 158         #       PCI_SLOT HBA PORT  CHANNEL NAME
 159 .br
 160         channel 85:00.0  1         A
 161 .br
 162         channel 85:00.0  0         B
 163 .br
 164         channel 86:00.0  1         A
 165 .br
 166         channel 86:00.0  0         B
 167 .br
 168 .P
 169 A configuration using device link aliases.
 170 .P
 171 .br
 172         #     by-vdev
 173 .br
 174         #     name     fully qualified or base name of device link
 175 .br
 176         alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
 177 .br
 178         alias d2       wwn-0x5000c5002def789e
 179 .br
 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)