c/mirror_zfs
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_zfs.git synced 2024-12-27 11:29:36 +03:00
Code Issues Packages Projects Releases Wiki Activity

vdev_id.conf.5: modernise

Browse Source 
Also yeet pci_slot since it doesn't seem to exist?

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Closes #12125
This commit is contained in:
наб 2021-05-26 19:12:48 +02:00 committed by Brian Behlendorf
parent 56454b0391
commit c3fb6653b5
1 changed files with 231 additions and 202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

433
man/man5/vdev_id.conf.5
View File

@ -1,222 +1,251 @@
.TH VDEV_ID.CONF 5 "Aug 24, 2020" OpenZFS .\"
.SH NAME .\" This file and its contents are supplied under the terms of the
vdev_id.conf \- Configuration file for vdev_id .\" Common Development and Distribution License ("CDDL"), version 1.0.
.SH DESCRIPTION .\" You may only use this file in accordance with the terms of version
.I vdev_id.conf .\" 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
.Sh DESCRIPTION
.Nm
is the configuration file for is the configuration file for
.BR vdev_id (8). .Nm vdev_id Ns Sy (8) .
It controls the default behavior of It controls the default behavior of
.BR vdev_id (8) .Nm vdev_id Ns Sy (8)
while it is mapping a disk device name to an alias. while it is mapping a disk device name to an alias.
.PP .Pp
The The
.I vdev_id.conf .Nm
file uses a simple format consisting of a keyword followed by one or 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 more values on a single line.
keyword is ignored. Comments may optionally begin with a hash Any line not beginning with a recognized keyword is ignored.
character. Comments may optionally begin with a hash character.
.Pp
The following keywords and values are used. The following keywords and values are used.
.TP .Bl -tag -width "-h"
\fIalias\fR <name> <devlink> .It Sy alias Ar name Ar devlink
Maps a device link in the /dev directory hierarchy to a new device Maps a device link in the
name. The udev rule defining the device link must have run prior to .Pa /dev
.BR vdev_id (8). directory hierarchy to a new device name.
The udev rule defining the device link must have run prior to
.Nm vdev_id Ns Sy (8) .
A defined alias takes precedence over a topology-derived name, but the A defined alias takes precedence over a topology-derived name, but the
two naming methods can otherwise coexist. For example, one might name two naming methods can otherwise coexist.
drives in a JBOD with the sas_direct topology while naming an internal For example, one might name drives in a JBOD with the
L2ARC device with an alias. .Sy sas_direct
topology while naming an internal L2ARC device with an alias.
\fIname\fR - the name of the link to the device that will by created in .Pp
/dev/disk/by-vdev. .Ar name
is the name of the link to the device that will by created under
\fIdevlink\fR - the name of the device link that has already been .Pa /dev/disk/by-vdev .
defined by udev. This may be an absolute path or the base filename. .Pp
.Ar devlink
.TP is the name of the device link that has already been
\fIchannel\fR [pci_slot] <port> <name> 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 Maps a physical path to a channel name (typically representing a single
disk enclosure). disk enclosure).
.
.TP .It Sy enclosure_symlinks Sy yes Ns | Ns Sy no
\fIenclosure_symlinks\fR <yes|no> Additionally create
Additionally create /dev/by-enclosure symlinks to the disk enclosure .Pa /dev/by-enclosure
sg devices using the naming scheme from vdev_id.conf. symlinks to the disk enclosure
\fIenclosure_symlinks\fR is only allowed for sas_direct mode. .Em sg
.TP devices using the naming scheme from
\fIenclosure_symlinks_prefix\fR <prefix> .Pa vdev_id.conf .
Specify the prefix for the enclosure symlinks in the form of: .Sy enclosure_symlinks
is only allowed for
/dev/by-enclosure/<prefix>-<channel><num> .Sy sas_direct
mode.
Defaults to "enc" if not specified. .
.TP .It Sy enclosure_symlinks_prefix Ar prefix
\fIpci_slot\fR - specifies the PCI SLOT of the HBA Specify the prefix for the enclosure symlinks in the form
hosting the disk enclosure being mapped, as found in the output of .Pa /dev/by-enclosure/ Ns Ao Ar prefix Ac Ns - Ns Ao Ar channel Ac Ns Aq Ar num
.BR lspci (8). .Pp
This argument is not used in sas_switch mode. Defaults to
.Dq Em enc .
\fIport\fR - specifies the numeric identifier of the HBA or SAS switch port .
connected to the disk enclosure being mapped. .It Sy slot Ar prefix Ar new Op Ar channel
\fIname\fR - specifies the name of the channel.
.TP
\fIslot\fR <old> <new> [channel]
Maps a disk slot number as reported by the operating system to an Maps a disk slot number as reported by the operating system to an
alternative slot number. If the \fIchannel\fR parameter is specified alternative slot number.
If the
.Ar channel
parameter is specified
then the mapping is only applied to slots in the named channel, then the mapping is only applied to slots in the named channel,
otherwise the mapping is applied to all channels. The first-specified otherwise the mapping is applied to all channels.
\fIslot\fR rule that can match a slot takes precedence. Therefore a The first-specified
channel-specific mapping for a given slot should generally appear before .Ar slot
a generic mapping for the same slot. In this way a custom mapping may rule that can match a slot takes precedence.
be applied to a particular channel and a default mapping applied to the Therefore a channel-specific mapping for a given slot should generally appear
others. before a generic mapping for the same slot.
In this way a custom mapping may be applied to a particular channel
.TP and a default mapping applied to the others.
\fImultipath\fR <yes|no> .
.It Sy multipath Sy yes Ns | Ns Sy no
Specifies whether Specifies whether
.BR vdev_id (8) .Nm vdev_id Ns Sy (8)
will handle only dm-multipath devices. If set to "yes" then will handle only dm-multipath devices.
.BR vdev_id (8) If set to
.Sy yes
then
.Nm vdev_id Ns Sy (8)
will examine the first running component disk of a dm-multipath will examine the first running component disk of a dm-multipath
device as listed by the device as provided by the driver command to determine the physical path.
.BR multipath (8) .
command to determine the physical path. .It Sy topology Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
.TP
\fItopology\fR <sas_direct|sas_switch>
Identifies a physical topology that governs how physical paths are Identifies a physical topology that governs how physical paths are
mapped to channels. mapped to channels:
.Bl -tag -compact -width "sas_direct and scsi"
\fIsas_direct\fR - in this mode a channel is uniquely identified by .It Sy sas_direct No and Sy scsi
a PCI slot and a HBA port number channels are uniquely identified by a PCI slot and HBA port number
.It Sy sas_switch
\fIsas_switch\fR - in this mode a channel is uniquely identified by channels are uniquely identified by a SAS switch port number
a SAS switch port number .El
.
.TP .It Sy phys_per_port Ar num
\fIphys_per_port\fR <num>
Specifies the number of PHY devices associated with a SAS HBA port or SAS Specifies the number of PHY devices associated with a SAS HBA port or SAS
switch port. switch port.
.BR vdev_id (8) .Nm vdev_id Ns Sy (8)
internally uses this value to determine which HBA or switch port a internally uses this value to determine which HBA or switch port a
device is connected to. The default is 4. device is connected to.
The default is
.TP .Sy 4 .
\fIslot\fR <bay|phy|port|id|lun|ses> .
.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 Specifies from which element of a SAS identifier the slot number is
taken. The default is bay. taken.
The default is
\fIbay\fR - read the slot number from the bay identifier. .Sy bay :
.Bl -tag -compact -width "port"
\fIphy\fR - read the slot number from the phy identifier. .It Sy bay
read the slot number from the bay identifier.
\fIport\fR - use the SAS port as the slot number. .It Sy phy
read the slot number from the phy identifier.
\fIid\fR - use the scsi id as the slot number. .It Sy port
use the SAS port as the slot number.
\fIlun\fR - use the scsi lun as the slot number. .It Sy id
use the scsi id as the slot number.
\fIses\fR - use the SCSI Enclosure Services (SES) enclosure device 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 as reported by
.BR sg_ses (8). .Xr sg_ses 8 .
This is intended for use only on systems where \fIbay\fR is unsupported, Intended for use only on systems where
noting that \fIport\fR and \fIid\fR may be unstable across disk replacement. .Sy bay
.SH EXAMPLES is unsupported,
A non-multipath configuration with direct-attached SAS enclosures and an noting that
arbitrary slot re-mapping. .Sy port
.P and
.nf .Sy id
multipath no may be unstable across disk replacement.
topology sas_direct .El
phys_per_port 4 .El
slot bay .
.Sh FILES
# PCI_SLOT HBA PORT CHANNEL NAME .Bl -tag -width "-v v"
channel 85:00.0 1 A .It Pa /etc/zfs/vdev_id.conf
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
.fi
.P
A SAS-switch topology. Note that the
.I channel
keyword takes only two arguments in this example.
.P
.nf
topology sas_switch
# SWITCH PORT CHANNEL NAME
channel 1 A
channel 2 B
channel 3 C
channel 4 D
.fi
.P
A multipath configuration. Note that channel names have multiple
definitions - one per physical path.
.P
.nf
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
.fi
.P
A configuration with enclosure_symlinks enabled.
.P
.nf
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
.fi
In addition to the disks symlinks, this configuration will create:
.P
.nf
/dev/by-enclosure/enc-L0
/dev/by-enclosure/enc-L1
/dev/by-enclosure/enc-U0
/dev/by-enclosure/enc-U1
.fi
.P
A configuration using device link aliases.
.P
.nf
# by-vdev
# name fully qualified or base name of device link
alias d1 /dev/disk/by-id/wwn-0x5000c5002de3b9ca
alias d2 wwn-0x5000c5002def789e
.fi
.P
.SH FILES
.TP
.I /etc/zfs/vdev_id.conf
The configuration file for The configuration file for
.BR vdev_id (8). .Nm vdev_id Ns Sy (8) .
.SH SEE ALSO .El
.BR vdev_id (8) .
.Sh EXAMPLES
A non-multipath configuration with direct-attached SAS enclosures and an
arbitrary slot re-mapping:
.Bd -literal -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 -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 -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 -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
.Pp
In addition to the disks symlinks, this configuration will create:
.Bd -literal -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 -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