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