---
name: "vdev_id"
section: "8"
platform: "linux"
package: "zfsutils-linux"
version: "2.3.9-0+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/vdev_id"
---

# vdev\_id(8)

generate user-friendly names for JBOD disks

## NAME

**vdev\_id** – generate user-friendly names for JBOD disks

## SYNOPSIS

**vdev\_id** **-d** *dev* **-c** *config\_file* **-g** **sas\_direct**\|**sas\_switch**\|**scsi** **-m** **-p** *phys\_per\_port*

## DESCRIPTION

**vdev\_id** is an udev helper which parses [vdev\_id.conf(5)](/vdev_id.conf/5.md) to map a physical path in a storage topology to a channel name. The channel name is combined with a disk enclosure slot number to create an alias that reflects the physical location of the drive. This is particularly helpful when it comes to tasks like replacing failed drives. Slot numbers may also be remapped in case the default numbering is unsatisfactory. The drive aliases will be created as symbolic links in */dev/disk/by-vdev*.

The currently supported topologies are **sas\_direct**, **sas\_switch**, and **scsi**. A multipath mode is supported in which dm-mpath devices are handled by examining the first running component disk as reported by the driver. In multipath mode the configuration file should contain a channel definition with the same name for each path to a given enclosure.

**vdev\_id** also supports creating aliases based on existing udev links in the /dev hierarchy using the **alias** configuration file keyword. See [vdev\_id.conf(5)](/vdev_id.conf/5.md) for details.

## OPTIONS

- **-d** *device*

  The device node to classify, like */dev/sda*.

- **-c** *config\_file*

  Specifies the path to an alternate configuration file. The default is */etc/zfs/vdev\_id.conf*.

- **-g** **sas\_direct**\|**sas\_switch**\|**scsi**

  Identifies a physical topology that governs how physical paths are 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

- **-m**

  Only handle dm-multipath devices. If specified, examine the first running component disk of a dm-multipath device as provided by the driver to determine the physical path.

- **-p** *phys\_per\_port*

  Specifies the number of PHY devices associated with a SAS HBA port or SAS switch port. **vdev\_id** internally uses this value to determine which HBA or switch port a device is connected to. The default is **4**.

- **-h**

  Print a usage summary.

## SEE ALSO

[vdev\_id.conf(5)](/vdev_id.conf/5.md)