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 zpad_slot Ar digits 96Pad slot numbers with zeros to make them 97.Ar digits 98long, which can help to make disk names a consistent length and easier to sort. 99. 100.It Sy multipath Sy yes Ns | Ns Sy no 101Specifies whether 102.Xr vdev_id 8 103will handle only dm-multipath devices. 104If set to 105.Sy yes 106then 107.Xr vdev_id 8 108will examine the first running component disk of a dm-multipath 109device as provided by the driver command to determine the physical path. 110. 111.It Sy topology Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi 112Identifies a physical topology that governs how physical paths are 113mapped to channels: 114.Bl -tag -compact -width "sas_direct and scsi" 115.It Sy sas_direct No and Sy scsi 116channels are uniquely identified by a PCI slot and HBA port number 117.It Sy sas_switch 118channels are uniquely identified by a SAS switch port number 119.El 120. 121.It Sy phys_per_port Ar num 122Specifies the number of PHY devices associated with a SAS HBA port or SAS 123switch port. 124.Xr vdev_id 8 125internally uses this value to determine which HBA or switch port a 126device is connected to. 127The default is 128.Sy 4 . 129. 130.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 131Specifies from which element of a SAS identifier the slot number is 132taken. 133The default is 134.Sy bay : 135.Bl -tag -compact -width "port" 136.It Sy bay 137read the slot number from the bay identifier. 138.It Sy phy 139read the slot number from the phy identifier. 140.It Sy port 141use the SAS port as the slot number. 142.It Sy id 143use the scsi id as the slot number. 144.It Sy lun 145use the scsi lun as the slot number. 146.It Sy bay_lun 147read the slot number from the bay identifier and append the lun number. 148Useful for multi-lun multi-actuator hard drives. 149.It Sy ses 150use the SCSI Enclosure Services (SES) enclosure device slot number, 151as reported by 152.Xr sg_ses 8 . 153Intended for use only on systems where 154.Sy bay 155is unsupported, 156noting that 157.Sy port 158and 159.Sy id 160may be unstable across disk replacement. 161.El 162.El 163. 164.Sh FILES 165.Bl -tag -width "-v v" 166.It Pa /etc/zfs/vdev_id.conf 167The configuration file for 168.Xr vdev_id 8 . 169.El 170. 171.Sh EXAMPLES 172A non-multipath configuration with direct-attached SAS enclosures and an 173arbitrary slot re-mapping: 174.Bd -literal -compact -offset Ds 175multipath no 176topology sas_direct 177phys_per_port 4 178slot bay 179 180# PCI_SLOT HBA PORT CHANNEL NAME 181channel 85:00.0 1 A 182channel 85:00.0 0 B 183channel 86:00.0 1 C 184channel 86:00.0 0 D 185 186# Custom mapping for Channel A 187 188# Linux Mapped 189# Slot Slot Channel 190slot 1 7 A 191slot 2 10 A 192slot 3 3 A 193slot 4 6 A 194 195# Default mapping for B, C, and D 196 197slot 1 4 198slot 2 2 199slot 3 1 200slot 4 3 201.Ed 202.Pp 203A SAS-switch topology. 204Note, that the 205.Ar channel 206keyword takes only two arguments in this example: 207.Bd -literal -compact -offset Ds 208topology sas_switch 209 210# SWITCH PORT CHANNEL NAME 211channel 1 A 212channel 2 B 213channel 3 C 214channel 4 D 215.Ed 216.Pp 217A multipath configuration. 218Note that channel names have multiple definitions - one per physical path: 219.Bd -literal -compact -offset Ds 220multipath yes 221 222# PCI_SLOT HBA PORT CHANNEL NAME 223channel 85:00.0 1 A 224channel 85:00.0 0 B 225channel 86:00.0 1 A 226channel 86:00.0 0 B 227.Ed 228.Pp 229A configuration with enclosure_symlinks enabled: 230.Bd -literal -compact -offset Ds 231multipath yes 232enclosure_symlinks yes 233 234# PCI_ID HBA PORT CHANNEL NAME 235channel 05:00.0 1 U 236channel 05:00.0 0 L 237channel 06:00.0 1 U 238channel 06:00.0 0 L 239.Ed 240In addition to the disks symlinks, this configuration will create: 241.Bd -literal -compact -offset Ds 242/dev/by-enclosure/enc-L0 243/dev/by-enclosure/enc-L1 244/dev/by-enclosure/enc-U0 245/dev/by-enclosure/enc-U1 246.Ed 247.Pp 248A configuration using device link aliases: 249.Bd -literal -compact -offset Ds 250# by-vdev 251# name fully qualified or base name of device link 252alias d1 /dev/disk/by-id/wwn-0x5000c5002de3b9ca 253alias d2 wwn-0x5000c5002def789e 254.Ed 255. 256.Sh SEE ALSO 257.Xr vdev_id 8 258