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>
  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 .SH EXAMPLES
 107 A non-multipath configuration with direct-attached SAS enclosures and an
 108 arbitrary slot re-mapping.
 109 .P
 110 .nf
 111         multipath     no
 112         topology      sas_direct
 113         phys_per_port 4
 114         slot          bay
 115
 116         #       PCI_SLOT HBA PORT  CHANNEL NAME
 117         channel 85:00.0  1         A
 118         channel 85:00.0  0         B
 119         channel 86:00.0  1         C
 120         channel 86:00.0  0         D
 121
 122         # Custom mapping for Channel A
 123
 124         #    Linux      Mapped
 125         #    Slot       Slot      Channel
 126         slot 1          7         A
 127         slot 2          10        A
 128         slot 3          3         A
 129         slot 4          6         A
 130
 131         # Default mapping for B, C, and D
 132
 133         slot 1          4
 134         slot 2          2
 135         slot 3          1
 136         slot 4          3
 137 .fi
 138 .P
 139 A SAS-switch topology.  Note that the
 140 .I channel
 141 keyword takes only two arguments in this example.
 142 .P
 143 .nf
 144         topology      sas_switch
 145
 146         #       SWITCH PORT  CHANNEL NAME
 147         channel 1            A
 148         channel 2            B
 149         channel 3            C
 150         channel 4            D
 151 .fi
 152 .P
 153 A multipath configuration.  Note that channel names have multiple
 154 definitions - one per physical path.
 155 .P
 156 .nf
 157         multipath yes
 158
 159         #       PCI_SLOT HBA PORT  CHANNEL NAME
 160         channel 85:00.0  1         A
 161         channel 85:00.0  0         B
 162         channel 86:00.0  1         A
 163         channel 86:00.0  0         B
 164 .fi
 165 .P
 166 A configuration using device link aliases.
 167 .P
 168 .nf
 169         #     by-vdev
 170         #     name     fully qualified or base name of device link
 171         alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
 172         alias d2       wwn-0x5000c5002def789e
 173 .fi
 174 .P
 175
 176 .SH FILES
 177 .TP
 178 .I /etc/zfs/vdev_id.conf
 179 The configuration file for
 180 .BR vdev_id (8).
 181 .SH SEE ALSO
 182 .BR vdev_id (8)