223 lines
6.2 KiB
Groff
223 lines
6.2 KiB
Groff
|
.TH VDEV_ID.CONF 5 "Aug 24, 2020" OpenZFS
|
||
|
|
.SH NAME
|
||
|
|
vdev_id.conf \- Configuration file for vdev_id
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.I vdev_id.conf
|
||
|
|
is the configuration file for
|
||
|
|
.BR vdev_id (8).
|
||
|
|
It controls the default behavior of
|
||
|
|
.BR vdev_id (8)
|
||
|
|
while it is mapping a disk device name to an alias.
|
||
|
|
.PP
|
||
|
|
The
|
||
|
|
.I vdev_id.conf
|
||
|
|
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.
|
||
|
|
|
||
|
|
The following keywords and values are used.
|
||
|
|
.TP
|
||
|
|
\fIalias\fR <name> <devlink>
|
||
|
|
Maps a device link in the /dev directory hierarchy to a new device
|
||
|
|
name. The udev rule defining the device link must have run prior to
|
||
|
|
.BR 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 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
|
||
|
|
/dev/disk/by-vdev.
|
||
|
|
|
||
|
|
\fIdevlink\fR - the name of the device link that has already been
|
||
|
|
defined by udev. This may be an absolute path or the base filename.
|
||
|
|
|
||
|
|
.TP
|
||
|
|
\fIchannel\fR [pci_slot] <port> <name>
|
||
|
|
Maps a physical path to a channel name (typically representing a single
|
||
|
|
disk enclosure).
|
||
|
|
|
||
|
|
.TP
|
||
|
|
\fIenclosure_symlinks\fR <yes|no>
|
||
|
|
Additionally create /dev/by-enclosure symlinks to the disk enclosure
|
||
|
|
sg devices using the naming scheme from vdev_id.conf.
|
||
|
|
\fIenclosure_symlinks\fR is only allowed for sas_direct mode.
|
||
|
|
.TP
|
||
|
|
\fIenclosure_symlinks_prefix\fR <prefix>
|
||
|
|
Specify the prefix for the enclosure symlinks in the form of:
|
||
|
|
|
||
|
|
/dev/by-enclosure/<prefix>-<channel><num>
|
||
|
|
|
||
|
|
Defaults to "enc" if not specified.
|
||
|
|
.TP
|
||
|
|
\fIpci_slot\fR - specifies the PCI SLOT of the HBA
|
||
|
|
hosting the disk enclosure being mapped, as found in the output of
|
||
|
|
.BR lspci (8).
|
||
|
|
This argument is not used in sas_switch mode.
|
||
|
|
|
||
|
|
\fIport\fR - specifies the numeric identifier of the HBA or SAS switch port
|
||
|
|
connected to the disk enclosure being mapped.
|
||
|
|
|
||
|
|
\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
|
||
|
|
alternative slot number. If the \fIchannel\fR 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
|
||
|
|
\fIslot\fR 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.
|
||
|
|
|
||
|
|
.TP
|
||
|
|
\fImultipath\fR <yes|no>
|
||
|
|
Specifies whether
|
||
|
|
.BR vdev_id (8)
|
||
|
|
will handle only dm-multipath devices. If set to "yes" then
|
||
|
|
.BR vdev_id (8)
|
||
|
|
will examine the first running component disk of a dm-multipath
|
||
|
|
device as listed by the
|
||
|
|
.BR multipath (8)
|
||
|
|
command to determine the physical path.
|
||
|
|
.TP
|
||
|
|
\fItopology\fR <sas_direct|sas_switch>
|
||
|
|
Identifies a physical topology that governs how physical paths are
|
||
|
|
mapped to channels.
|
||
|
|
|
||
|
|
\fIsas_direct\fR - in this mode a channel is uniquely identified by
|
||
|
|
a PCI slot and a HBA port number
|
||
|
|
|
||
|
|
\fIsas_switch\fR - in this mode a channel is uniquely identified by
|
||
|
|
a SAS switch port number
|
||
|
|
|
||
|
|
.TP
|
||
|
|
\fIphys_per_port\fR <num>
|
||
|
|
Specifies the number of PHY devices associated with a SAS HBA port or SAS
|
||
|
|
switch port.
|
||
|
|
.BR vdev_id (8)
|
||
|
|
internally uses this value to determine which HBA or switch port a
|
||
|
|
device is connected to. The default is 4.
|
||
|
|
|
||
|
|
.TP
|
||
|
|
\fIslot\fR <bay|phy|port|id|lun|ses>
|
||
|
|
Specifies from which element of a SAS identifier the slot number is
|
||
|
|
taken. The default is bay.
|
||
|
|
|
||
|
|
\fIbay\fR - read the slot number from the bay identifier.
|
||
|
|
|
||
|
|
\fIphy\fR - read the slot number from the phy identifier.
|
||
|
|
|
||
|
|
\fIport\fR - use the SAS port as the slot number.
|
||
|
|
|
||
|
|
\fIid\fR - use the scsi id as the slot number.
|
||
|
|
|
||
|
|
\fIlun\fR - use the scsi lun as the slot number.
|
||
|
|
|
||
|
|
\fIses\fR - use the SCSI Enclosure Services (SES) enclosure device slot number,
|
||
|
|
as reported by
|
||
|
|
.BR sg_ses (8).
|
||
|
|
This is intended for use only on systems where \fIbay\fR is unsupported,
|
||
|
|
noting that \fIport\fR and \fIid\fR may be unstable across disk replacement.
|
||
|
|
.SH EXAMPLES
|
||
|
|
A non-multipath configuration with direct-attached SAS enclosures and an
|
||
|
|
arbitrary slot re-mapping.
|
||
|
|
.P
|
||
|
|
.nf
|
||
|
|
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
|
||
|
|
.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
|
||
|
|
.BR vdev_id (8).
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR vdev_id (8)
|