man/man8/vdev_id.8

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .Dd May 26, 2021
  12 .Dt VDEV_ID 8
  13 .Os
  14 .
  15 .Sh NAME
  16 .Nm vdev_id
  17 .Nd generate user-friendly names for JBOD disks
  18 .Sh SYNOPSIS
  19 .Nm
  20 .Fl d Ar dev
  21 .Fl c Ar config_file
  22 .Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
  23 .Fl m
  24 .Fl p Ar phys_per_port
  25 .
  26 .Sh DESCRIPTION
  27 .Nm
  28 is an udev helper which parses
  29 .Xr vdev_id.conf 5
  30 to map a physical path in a storage topology to a channel name.
  31 The channel name is combined with a disk enclosure slot number to create
  32 an alias that reflects the physical location of the drive.
  33 This is particularly helpful when it comes to tasks like replacing failed
  34 drives.
  35 Slot numbers may also be remapped in case the default numbering is
  36 unsatisfactory.
  37 The drive aliases will be created as symbolic links in
  38 .Pa /dev/disk/by-vdev .
  39 .Pp
  40 The currently supported topologies are
  41 .Sy sas_direct ,
  42 .Sy sas_switch ,
  43 and
  44 .Sy scsi .
  45 A multipath mode is supported in which dm-mpath devices are handled by
  46 examining the first running component disk as reported by the driver.
  47 In multipath mode the configuration file should contain a
  48 channel definition with the same name for each path to a given
  49 enclosure.
  50 .Pp
  51 .Nm
  52 also supports creating aliases based on existing udev links in the /dev
  53 hierarchy using the
  54 .Sy alias
  55 configuration file keyword.
  56 See
  57 .Xr vdev_id.conf 5
  58 for details.
  59 .
  60 .Sh OPTIONS
  61 .Bl -tag -width "-m"
  62 .It Fl d Ar device
  63 The device node to classify, like
  64 .Pa /dev/sda .
  65 .It Fl c Ar config_file
  66 Specifies the path to an alternate configuration file.
  67 The default is
  68 .Pa /etc/zfs/vdev_id.conf .
  69 .It Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
  70 Identifies a physical topology that governs how physical paths are
  71 mapped to channels:
  72 .Bl -tag -compact -width "sas_direct and scsi"
  73 .It Sy sas_direct No and Sy scsi
  74 channels are uniquely identified by a PCI slot and HBA port number
  75 .It Sy sas_switch
  76 channels are uniquely identified by a SAS switch port number
  77 .El
  78 .It Fl m
  79 Only handle dm-multipath devices.
  80 If specified, examine the first running component disk of a dm-multipath
  81 device as provided by the driver to determine the physical path.
  82 .It Fl p Ar phys_per_port
  83 Specifies the number of PHY devices associated with a SAS HBA port or SAS
  84 switch port.
  85 .Nm
  86 internally uses this value to determine which HBA or switch port a
  87 device is connected to.
  88 The default is
  89 .Sy 4 .
  90 .It Fl h
  91 Print a usage summary.
  92 .El
  93 .
  94 .Sh SEE ALSO
  95 .Xr vdev_id.conf 5