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