zfs/man/man5/vdev_id.conf.5 - backupdr - Git at Google

 .\"
 .\" 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
	.\"
	.\" 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