Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
vdev_id.conf(5)		      File Formats Manual	       vdev_id.conf(5)

NAME
       vdev_id.conf - Configuration file for vdev_id

DESCRIPTION
       vdev_id.conf is the configuration file for vdev_id(8).  It controls the
       default behavior	of vdev_id(8) while it is mapping a disk  device  name
       to an alias.

       The vdev_id.conf	file uses a simple format consisting of	a keyword fol-
       lowed 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.

       The following keywords and values are used.

       alias <name> <devlink>
	      Maps a device link in the	/dev directory hierarchy to a new  de-
	      vice name.  The udev rule	defining the device link must have run
	      prior to 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
	      sas_direct  topology  while naming an internal L2ARC device with
	      an alias.

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

	      devlink  - the name of the device	link that has already been de-
	      fined by udev.  This may be an absolute path or the  base	 file-
	      name.

       channel [pci_slot] <port> <name>
	      Maps a physical path to a	channel	name (typically	representing a
	      single disk enclosure).

       enclosure_symlinks <yes|no>
	      Additionally create /dev/by-enclosure symlinks to	the  disk  en-
	      closure  sg  devices  using the naming scheme from vdev_id.conf.
	      enclosure_symlinks is only allowed for sas_direct	mode.

       enclosure_symlinks_prefix <prefix>
	      Specify the prefix for the enclosure symlinks in the form	of:

	      /dev/by-enclosure/<prefix>-<channel><num>

	      Defaults to "enc"	if not specified.

       pci_slot	- specifies the	PCI SLOT of the	HBA
	      hosting the disk enclosure being mapped, as found	in the	output
	      of lspci(8).  This argument is not used in sas_switch mode.

	      port - specifies the numeric identifier of the HBA or SAS	switch
	      port connected to	the disk enclosure being mapped.

	      name - specifies the name	of the channel.

       slot <old> <new>	[channel]
	      Maps a disk slot number as reported by the operating  system  to
	      an  alternative slot number.  If the channel parameter is	speci-
	      fied then	the mapping is only applied  to	 slots	in  the	 named
	      channel,	otherwise  the mapping is applied to all channels. The
	      first-specified slot rule	that can match	a  slot	 takes	prece-
	      dence.   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 particu-
	      lar channel and a	default	mapping	applied	to the others.

       multipath <yes|no>
	      Specifies	whether	vdev_id(8) will	handle only  dm-multipath  de-
	      vices.   If  set to "yes"	then vdev_id(8)	will examine the first
	      running component	disk of	a dm-multipath device as listed	by the
	      multipath(8) command to determine	the physical path.

       topology	<sas_direct|sas_switch>
	      Identifies  a  physical topology that governs how	physical paths
	      are mapped to channels.

	      sas_direct - in this mode	a channel is uniquely identified by  a
	      PCI slot and a HBA port number

	      sas_switch  - in this mode a channel is 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 determine which HBA or	switch port a device is	connected  to.
	      The default is 4.

       slot <bay|phy|port|id|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.

	      ses - use	the SCSI Enclosure  Services  (SES)  enclosure	device
	      slot number, as reported by sg_ses(8).  This is intended for use
	      only on systems where bay	is unsupported,	noting that  port  and
	      id may be	unstable across	disk replacement.

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 defi-
       nitions - 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

FILES
       /etc/zfs/vdev_id.conf
	      The configuration	file for vdev_id(8).

SEE ALSO
       vdev_id(8)

							       vdev_id.conf(5)

NAME | DESCRIPTION | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vdev_id.conf&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help