VDEV_ID.CONF(5)

💖 VDEV_ID.CONF(5) — the File Formats Manual page, bestie edition 💖

okay so bestie, welcome to vdev_id.conf ✨ this one lives in the File Formats Manual section, and it's literally the config file for vdev_id(8). let's get into it 🫶

---

🌸 NAME 🌸

vdev_id.conf — the configuration file for vdev_id(8) 💅

---

✨ DESCRIPTION ✨

So vdev_id.conf is the config file for vdev_id(8). It controls what vdev_id(8) does by default while it's out here mapping a disk device name to an alias. main character behavior honestly 💅

The vdev_id.conf file uses a super simple format: a keyword, then one or more values, all on a single line. Any line that doesn't start with a recognized keyword? Ignored, not even looked at, ghosted 💀. Comments can optionally start with a hash character #.

Here are the keywords and values you get to play with 👇

• alias name devlink — maps a device link in the /dev directory hierarchy to a new device name. The udev rule that defines the device link has to have already run before vdev_id(8) does its thing, no cap. A defined alias takes precedence over a topology-derived name, but other than that the two naming methods can coexist like besties 🫶. For example, you could name drives in a JBOD with the sas_direct topology while naming an internal L2ARC device with an alias. iconic.

name is the name of the link to the device that will be created under /dev/disk/by-vdev.

devlink is the name of the device link that's already been defined by udev. This can be an absolute path or the base filename.

• channel [pci_slot] port name — maps a physical path to a channel name (typically representing a single disk enclosure). 🎀
• enclosure_symlinks yes|no — additionally creates /dev/by-enclosure symlinks to the disk enclosure sg devices using the naming scheme from vdev_id.conf. enclosure_symlinks is only allowed for sas_direct mode, so don't try it anywhere else, bestie.
• enclosure_symlinks_prefix prefix — specify the prefix for the enclosure symlinks in the form /dev/by-enclosure/⟨prefix⟩-⟨channel⟩⟨num⟩

Defaults to “enc”. 🌸

• slot prefix new [channel] — maps a disk slot number as reported by the operating system to an alternative slot number. If the channel parameter is specified, the mapping is only applied to slots in the named channel; otherwise it applies to all channels. The first-specified slot rule that can match a slot takes precedence — so a channel-specific mapping for a given slot should generally show up before a generic mapping for that same slot. That way you can apply a custom mapping to one particular channel and a default mapping to all the others. order matters, periodt 💅
• zpad_slot digits — pads slot numbers with zeros to make them digits long, which can help make disk names a consistent length and easier to sort. lowkey so satisfying ✨
• multipath yes|no — specifies whether vdev_id(8) will handle only dm-multipath devices. If set to yes, then 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.
• topology sas_direct|sas_switch|scsi — identifies a physical topology that governs how physical paths get mapped to channels:
  • sas_direct and scsi — channels are uniquely identified by a PCI slot and HBA port number
  • sas_switch — channels are uniquely identified by a SAS switch port number
• phys_per_port num — specifies the number of PHY devices associated with a SAS HBA port or SAS switch port. vdev_id(8) internally uses this value to figure out which HBA or switch port a device is connected to. The default is 4. 🍓
• slot bay|phy|port|id|lun|bay_lun|ses — specifies from which element of a SAS identifier the slot number is taken. The default is bay:
  • bay — read the slot number from the bay identifier.
  • phy — read the slot number from the phy identifier.
  • port — use the SAS port as the slot number.
  • id — use the scsi id as the slot number.
  • lun — use the scsi lun as the slot number.
  • bay_lun — read the slot number from the bay identifier and append the lun number. Useful for multi-lun multi-actuator hard drives. 🦋
  • ses — use the SCSI Enclosure Services (SES) enclosure device slot number, as reported by sg_ses(8). Intended for use only on systems where bay is unsupported, and heads up: port and id may be unstable across disk replacement 😭

---

🎀 FILES 🎀

• /etc/zfs/vdev_id.conf — the configuration file for vdev_id(8). that's the one, bestie 💖

---

👑 EXAMPLES 👑

A non-multipath configuration with direct-attached SAS enclosures and an arbitrary slot re-mapping:

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

A SAS-switch topology. Note that the channel keyword takes only two arguments in this example:

topology      sas_switch

#       SWITCH PORT  CHANNEL NAME
channel 1            A
channel 2            B
channel 3            C
channel 4            D

A multipath configuration. Note that channel names have multiple definitions — one per physical path:

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

A configuration with enclosure_symlinks enabled:

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

In addition to the disks symlinks, this configuration will create:

/dev/by-enclosure/enc-L0
/dev/by-enclosure/enc-L1
/dev/by-enclosure/enc-U0
/dev/by-enclosure/enc-U1

A configuration using device link aliases:

#     by-vdev
#     name     fully qualified or base name of device link
alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
alias d2       wwn-0x5000c5002def789e

---

🌈 SEE ALSO 🌈

vdev_id(8) — go read it, iykyk 💜

---

and that's the whole page, bestie!! this one came from the OpenZFS crew and it's dated October 8, 2024 — go forth and name your vdevs, you absolute icon 👑✨💅