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