sys/contrib/openzfs/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 drives.
  34 Slot numbers may also be remapped in case the default numbering is unsatisfactory.
  35 The drive aliases will be created as symbolic links in
  36 .Pa /dev/disk/by-vdev .
  37 .Pp
  38 The currently supported topologies are
  39 .Sy sas_direct ,
  40 .Sy sas_switch ,
  41 and
  42 .Sy scsi .
  43 A multipath mode is supported in which dm-mpath devices are handled by
  44 examining the first running component disk as reported by the driver.
  45 In multipath mode the configuration file should contain a
  46 channel definition with the same name for each path to a given
  47 enclosure.
  48 .Pp
  49 .Nm
  50 also supports creating aliases based on existing udev links in the /dev
  51 hierarchy using the
  52 .Sy alias
  53 configuration file keyword.
  54 See
  55 .Xr vdev_id.conf 5
  56 for details.
  57 .
  58 .Sh OPTIONS
  59 .Bl -tag -width "-m"
  60 .It Fl d Ar device
  61 The device node to classify, like
  62 .Pa /dev/sda .
  63 .It Fl c Ar config_file
  64 Specifies the path to an alternate configuration file.
  65 The default is
  66 .Pa /etc/zfs/vdev_id.conf .
  67 .It Fl g Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
  68 Identifies a physical topology that governs how physical paths are
  69 mapped to channels:
  70 .Bl -tag -compact -width "sas_direct and scsi"
  71 .It Sy sas_direct No and Sy scsi
  72 channels are uniquely identified by a PCI slot and HBA port number
  73 .It Sy sas_switch
  74 channels are uniquely identified by a SAS switch port number
  75 .El
  76 .It Fl m
  77 Only handle dm-multipath devices.
  78 If specified, examine the first running component disk of a dm-multipath
  79 device as provided by the driver to determine the physical path.
  80 .It Fl p Ar phys_per_port
  81 Specifies the number of PHY devices associated with a SAS HBA port or SAS
  82 switch port.
  83 .Nm
  84 internally uses this value to determine which HBA or switch port a
  85 device is connected to.
  86 The default is
  87 .Sy 4 .
  88 .It Fl h
  89 Print a usage summary.
  90 .El
  91 .
  92 .Sh SEE ALSO
  93 .Xr vdev_id.conf 5