FreeBSD/Linux Kernel Cross Reference
sys/contrib/openzfs/man/man5/vdev_id.conf.5

     .\"
     .\" This file and its contents are supplied under the terms of the
     .\" Common Development and Distribution License ("CDDL"), version 1.0.
     .\" You may only use this file in accordance with the terms of version
     .\" 1.0 of the CDDL.
     .\"
     .\" A full copy of the text of the CDDL should have accompanied this
     .\" source.  A copy of the CDDL is also available via the Internet at
     .\" http://www.illumos.org/license/CDDL.
    .\"
    .Dd May 26, 2021
    .Dt VDEV_ID.CONF 5
    .Os
    .
    .Sh NAME
    .Nm vdev_id.conf
    .Nd configuration file for vdev_id(8)
    .Sh DESCRIPTION
    .Nm
    is the configuration file for
    .Xr vdev_id 8 .
    It controls the default behavior of
    .Xr vdev_id 8
    while it is mapping a disk device name to an alias.
    .Pp
    The
    .Nm
    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.
    .Pp
    The following keywords and values are used.
    .Bl -tag -width "-h"
    .It Sy alias Ar name Ar devlink
    Maps a device link in the
    .Pa /dev
    directory hierarchy to a new device name.
    The udev rule defining the device link must have run prior to
    .Xr 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
    .Sy sas_direct
    topology while naming an internal L2ARC device with an alias.
    .Pp
    .Ar name
    is the name of the link to the device that will by created under
    .Pa /dev/disk/by-vdev .
    .Pp
    .Ar devlink
    is the name of the device link that has already been
    defined by udev.
    This may be an absolute path or the base filename.
    .
    .It Sy channel [ Ns Ar pci_slot ] Ar port Ar name
    Maps a physical path to a channel name (typically representing a single
    disk enclosure).
    .
    .It Sy enclosure_symlinks Sy yes Ns | Ns Sy no
    Additionally create
    .Pa /dev/by-enclosure
    symlinks to the disk enclosure
    .Em sg
    devices using the naming scheme from
    .Pa vdev_id.conf .
    .Sy enclosure_symlinks
    is only allowed for
    .Sy sas_direct
    mode.
    .
    .It Sy enclosure_symlinks_prefix Ar prefix
    Specify the prefix for the enclosure symlinks in the form
    .Pa /dev/by-enclosure/ Ns Ao Ar prefix Ac Ns - Ns Ao Ar channel Ac Ns Aq Ar num
    .Pp
    Defaults to
    .Dq Em enc .
    .
    .It Sy slot Ar prefix Ar new Op Ar channel
    Maps a disk slot number as reported by the operating system to an
    alternative slot number.
    If the
    .Ar channel
    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
    .Ar slot
    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.
    .
    .It Sy multipath Sy yes Ns | Ns Sy no
    Specifies whether
    .Xr vdev_id 8
    will handle only dm-multipath devices.
    If set to
   .Sy yes
   then
   .Xr 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.
   .
   .It Sy topology Sy sas_direct Ns | Ns Sy sas_switch Ns | Ns Sy scsi
   Identifies a physical topology that governs how physical paths are
   mapped to channels:
   .Bl -tag -compact -width "sas_direct and scsi"
   .It Sy sas_direct No and Sy scsi
   channels are uniquely identified by a PCI slot and HBA port number
   .It Sy sas_switch
   channels are uniquely identified by a SAS switch port number
   .El
   .
   .It Sy phys_per_port Ar num
   Specifies the number of PHY devices associated with a SAS HBA port or SAS
   switch port.
   .Xr vdev_id 8
   internally uses this value to determine which HBA or switch port a
   device is connected to.
   The default is
   .Sy 4 .
   .
   .It Sy slot Sy bay Ns | Ns Sy phy Ns | Ns Sy port Ns | Ns Sy id Ns | Ns Sy lun Ns | Ns Sy ses
   Specifies from which element of a SAS identifier the slot number is
   taken.
   The default is
   .Sy bay :
   .Bl -tag -compact -width "port"
   .It Sy bay
   read the slot number from the bay identifier.
   .It Sy phy
   read the slot number from the phy identifier.
   .It Sy port
   use the SAS port as the slot number.
   .It Sy id
   use the scsi id as the slot number.
   .It Sy lun
   use the scsi lun as the slot number.
   .It Sy ses
   use the SCSI Enclosure Services (SES) enclosure device slot number,
   as reported by
   .Xr sg_ses 8 .
   Intended for use only on systems where
   .Sy bay
   is unsupported,
   noting that
   .Sy port
   and
   .Sy id
   may be unstable across disk replacement.
   .El
   .El
   .
   .Sh FILES
   .Bl -tag -width "-v v"
   .It Pa /etc/zfs/vdev_id.conf
   The configuration file for
   .Xr vdev_id 8 .
   .El
   .
   .Sh EXAMPLES
   A non-multipath configuration with direct-attached SAS enclosures and an
   arbitrary slot re-mapping:
   .Bd -literal -compact -offset Ds
   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
   .Ed
   .Pp
   A SAS-switch topology.
   Note, that the
   .Ar channel
   keyword takes only two arguments in this example:
   .Bd -literal -compact -offset Ds
   topology      sas_switch
   
   #       SWITCH PORT  CHANNEL NAME
   channel 1            A
   channel 2            B
   channel 3            C
   channel 4            D
   .Ed
   .Pp
   A multipath configuration.
   Note that channel names have multiple definitions - one per physical path:
   .Bd -literal -compact -offset Ds
   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
   .Ed
   .Pp
   A configuration with enclosure_symlinks enabled:
   .Bd -literal -compact -offset Ds
   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
   .Ed
   In addition to the disks symlinks, this configuration will create:
   .Bd -literal -compact -offset Ds
   /dev/by-enclosure/enc-L0
   /dev/by-enclosure/enc-L1
   /dev/by-enclosure/enc-U0
   /dev/by-enclosure/enc-U1
   .Ed
   .Pp
   A configuration using device link aliases:
   .Bd -literal -compact -offset Ds
   #     by-vdev
   #     name     fully qualified or base name of device link
   alias d1       /dev/disk/by-id/wwn-0x5000c5002de3b9ca
   alias d2       wwn-0x5000c5002def789e
   .Ed
   .
   .Sh SEE ALSO
   .Xr vdev_id 8

Cache object: 2d3b0294254bfcf7c80f7fda1e63ac08