Imported Upstream version 0.6.2+git20140204

[mirror_zfs-debian.git] / man / man5 / vdev_id.conf.5

.TH vdev_id.conf 5
.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).

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

	#       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 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)