]>
Commit | Line | Data |
---|---|---|
821b6834 NB |
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. | |
2957f38d NB |
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 | ||
821b6834 NB |
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 | ||
c66401fa TH |
41 | .TP |
42 | \fIenclosure_symlinks\fR <yes|no> | |
43 | Additionally create /dev/by-enclosure symlinks to the disk enclosure | |
44 | sg devices using the naming scheme from from vdev_id.conf. | |
45 | \fIenclosure_symlinks\fR is only allowed for sas_direct mode. | |
46 | .TP | |
47 | \fIenclosure_symlinks_prefix\fR <prefix> | |
48 | Specify the prefix for the enclosure symlinks in the form of: | |
49 | ||
50 | /dev/by-enclosure/<prefix>-<channel><num> | |
51 | ||
52 | Defaults to "enc" if not specified. | |
53 | .TP | |
821b6834 NB |
54 | \fIpci_slot\fR - specifies the PCI SLOT of the HBA |
55 | hosting the disk enclosure being mapped, as found in the output of | |
56 | .BR lspci (8). | |
57 | This argument is not used in sas_switch mode. | |
58 | ||
59 | \fIport\fR - specifies the numeric identifier of the HBA or SAS switch port | |
60 | connected to the disk enclosure being mapped. | |
61 | ||
62 | \fIname\fR - specifies the name of the channel. | |
63 | ||
64 | .TP | |
09d0b30f NB |
65 | \fIslot\fR <old> <new> [channel] |
66 | Maps a disk slot number as reported by the operating system to an | |
67 | alternative slot number. If the \fIchannel\fR parameter is specified | |
68 | then the mapping is only applied to slots in the named channel, | |
69 | otherwise the mapping is applied to all channels. The first-specified | |
70 | \fIslot\fR rule that can match a slot takes precedence. Therefore a | |
71 | channel-specific mapping for a given slot should generally appear before | |
72 | a generic mapping for the same slot. In this way a custom mapping may | |
73 | be applied to a particular channel and a default mapping applied to the | |
74 | others. | |
75 | ||
821b6834 NB |
76 | .TP |
77 | \fImultipath\fR <yes|no> | |
78 | Specifies whether | |
79 | .BR vdev_id (8) | |
80 | will handle only dm-multipath devices. If set to "yes" then | |
81 | .BR vdev_id (8) | |
82 | will examine the first running component disk of a dm-multipath | |
83 | device as listed by the | |
84 | .BR multipath (8) | |
85 | command to determine the physical path. | |
86 | .TP | |
87 | \fItopology\fR <sas_direct|sas_switch> | |
88 | Identifies a physical topology that governs how physical paths are | |
89 | mapped to channels. | |
90 | ||
91 | \fIsas_direct\fR - in this mode a channel is uniquely identified by | |
92 | a PCI slot and a HBA port number | |
93 | ||
94 | \fIsas_switch\fR - in this mode a channel is uniquely identified by | |
95 | a SAS switch port number | |
96 | ||
97 | .TP | |
98 | \fIphys_per_port\fR <num> | |
2957f38d | 99 | Specifies the number of PHY devices associated with a SAS HBA port or SAS |
821b6834 NB |
100 | switch port. |
101 | .BR vdev_id (8) | |
102 | internally uses this value to determine which HBA or switch port a | |
103 | device is connected to. The default is 4. | |
bba365cf AB |
104 | |
105 | .TP | |
993669a7 | 106 | \fIslot\fR <bay|phy|port|id|lun|ses> |
bba365cf AB |
107 | Specifies from which element of a SAS identifier the slot number is |
108 | taken. The default is bay. | |
109 | ||
110 | \fIbay\fR - read the slot number from the bay identifier. | |
111 | ||
112 | \fIphy\fR - read the slot number from the phy identifier. | |
113 | ||
d49d9c2b DK |
114 | \fIport\fR - use the SAS port as the slot number. |
115 | ||
bba365cf AB |
116 | \fIid\fR - use the scsi id as the slot number. |
117 | ||
118 | \fIlun\fR - use the scsi lun as the slot number. | |
993669a7 SG |
119 | |
120 | \fIses\fR - use the SCSI Enclosure Services (SES) enclosure device slot number, | |
121 | as reported by | |
122 | .BR sg_ses (8). | |
123 | This is intended for use only on systems where \fIbay\fR is unsupported, | |
124 | noting that \fIport\fR and \fIid\fR may be unstable across disk replacement. | |
821b6834 NB |
125 | .SH EXAMPLES |
126 | A non-multipath configuration with direct-attached SAS enclosures and an | |
127 | arbitrary slot re-mapping. | |
128 | .P | |
09d0b30f | 129 | .nf |
821b6834 | 130 | multipath no |
821b6834 | 131 | topology sas_direct |
821b6834 | 132 | phys_per_port 4 |
bba365cf | 133 | slot bay |
821b6834 | 134 | |
821b6834 | 135 | # PCI_SLOT HBA PORT CHANNEL NAME |
821b6834 | 136 | channel 85:00.0 1 A |
821b6834 | 137 | channel 85:00.0 0 B |
821b6834 | 138 | channel 86:00.0 1 C |
821b6834 | 139 | channel 86:00.0 0 D |
821b6834 | 140 | |
09d0b30f NB |
141 | # Custom mapping for Channel A |
142 | ||
821b6834 | 143 | # Linux Mapped |
09d0b30f NB |
144 | # Slot Slot Channel |
145 | slot 1 7 A | |
146 | slot 2 10 A | |
147 | slot 3 3 A | |
148 | slot 4 6 A | |
149 | ||
150 | # Default mapping for B, C, and D | |
151 | ||
152 | slot 1 4 | |
153 | slot 2 2 | |
154 | slot 3 1 | |
155 | slot 4 3 | |
156 | .fi | |
821b6834 NB |
157 | .P |
158 | A SAS-switch topology. Note that the | |
159 | .I channel | |
160 | keyword takes only two arguments in this example. | |
161 | .P | |
09d0b30f | 162 | .nf |
821b6834 | 163 | topology sas_switch |
821b6834 | 164 | |
821b6834 | 165 | # SWITCH PORT CHANNEL NAME |
821b6834 | 166 | channel 1 A |
821b6834 | 167 | channel 2 B |
821b6834 | 168 | channel 3 C |
821b6834 | 169 | channel 4 D |
09d0b30f | 170 | .fi |
821b6834 NB |
171 | .P |
172 | A multipath configuration. Note that channel names have multiple | |
173 | definitions - one per physical path. | |
174 | .P | |
09d0b30f | 175 | .nf |
821b6834 | 176 | multipath yes |
821b6834 | 177 | |
821b6834 | 178 | # PCI_SLOT HBA PORT CHANNEL NAME |
821b6834 | 179 | channel 85:00.0 1 A |
821b6834 | 180 | channel 85:00.0 0 B |
821b6834 | 181 | channel 86:00.0 1 A |
821b6834 | 182 | channel 86:00.0 0 B |
09d0b30f | 183 | .fi |
821b6834 | 184 | .P |
c66401fa TH |
185 | A configuration with enclosure_symlinks enabled. |
186 | .P | |
187 | .nf | |
188 | multipath yes | |
189 | enclosure_symlinks yes | |
190 | ||
191 | # PCI_ID HBA PORT CHANNEL NAME | |
192 | channel 05:00.0 1 U | |
193 | channel 05:00.0 0 L | |
194 | channel 06:00.0 1 U | |
195 | channel 06:00.0 0 L | |
196 | .fi | |
197 | In addition to the disks symlinks, this configuration will create: | |
198 | .P | |
199 | .nf | |
200 | /dev/by-enclosure/enc-L0 | |
201 | /dev/by-enclosure/enc-L1 | |
202 | /dev/by-enclosure/enc-U0 | |
203 | /dev/by-enclosure/enc-U1 | |
204 | .fi | |
205 | .P | |
2957f38d NB |
206 | A configuration using device link aliases. |
207 | .P | |
09d0b30f | 208 | .nf |
2957f38d | 209 | # by-vdev |
2957f38d | 210 | # name fully qualified or base name of device link |
2957f38d | 211 | alias d1 /dev/disk/by-id/wwn-0x5000c5002de3b9ca |
2957f38d | 212 | alias d2 wwn-0x5000c5002def789e |
09d0b30f | 213 | .fi |
2957f38d | 214 | .P |
821b6834 NB |
215 | |
216 | .SH FILES | |
217 | .TP | |
218 | .I /etc/zfs/vdev_id.conf | |
219 | The configuration file for | |
220 | .BR vdev_id (8). | |
221 | .SH SEE ALSO | |
222 | .BR vdev_id (8) |