diff options
Diffstat (limited to 'static/freebsd/man5/vdev_id.conf.5')
| -rw-r--r-- | static/freebsd/man5/vdev_id.conf.5 | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/static/freebsd/man5/vdev_id.conf.5 b/static/freebsd/man5/vdev_id.conf.5 new file mode 100644 index 00000000..299a2372 --- /dev/null +++ b/static/freebsd/man5/vdev_id.conf.5 @@ -0,0 +1,258 @@ +.\" SPDX-License-Identifier: CDDL-1.0 +.\" +.\" 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 October 8, 2024 +.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 zpad_slot Ar digits +Pad slot numbers with zeros to make them +.Ar digits +long, which can help to make disk names a consistent length and easier to sort. +. +.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 bay_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 bay_lun +read the slot number from the bay identifier and append the lun number. +Useful for multi-lun multi-actuator hard drives. +.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 |