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