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