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