Understanding the dm-multipath Configuration file /etc/multipath.conf

The main configuration file for DM-Multipath is /etc/multipath.conf. This file is not created by the initial installation of the RPM package. However, the following file is installed in the /usr/share/doc/device-mapper-multipath-[version] directory:

• multipath.conf – Basic configuration file with some examples for DM-Multipath. This file is used to create the /etc/multipath.conf file.

The multipath.conf file contains the following sections, and each section contains one or more attributes or subsections.

defaults Attributes in /etc/multipath.conf

Below is a sample defaults section from /etc/multipath.conf file.

defaults {
	polling_interval 	10
	path_selector		"round-robin 0"
	path_grouping_policy	multibus
	uid_attribute		ID_SERIAL
	prio			alua
	path_checker		readsector0
	rr_min_io		100
	max_fds			8192
	rr_weight		priorities
	failback		immediate
	no_path_retry		fail
	user_friendly_names	yes
}

A partial list of attributes defined in the defaults section of the configuration file is as follows:

• udev_dir – Directory where udev creates device nodes. The default is /dev.
• polling_interval – Interval in seconds that paths are checked. The default is 5 seconds.
• path_selector – One of the following path selector algorithms to use:
  • round-robin 0: Loop through every path sending the same amount of I/O to each. This is the default.
  • queue-length 0: Send I/O down a path with the least amount of outstanding I/O.
  • service-time 0: Send I/O down a path based on the amount of outstanding I/O and relative throughput.
• path_grouping_policy – Paths are grouped into path groups. The policy determines how path groups are formed. There are five different policies.
  • failover: One path per priority group
  • multibus: All paths in one priority group. This is the default.
  • group_by_serial: One priority group per storage controller (serial number)
  • group_by_prio: One priority group per priority value
  • group_by_node_name: One priority group per target node name
• prio – One of the following methods is used to obtain a path priority value:
  • const – Set a priority of one to all paths. This is the default.
  • emc – Generate the path priority for EMC storage arrays.
  • alua – Generate the path priority based on the SCSI-3 Asymmetric Logical Unit Access (ALUA) settings. ALUA allows a device to report the state of its ports to hosts. This state is used by hosts to prioritize paths and make failover and load- balancing decisions.
  • tpg_pref – Generate the path priority based on the SCSI-3 ALUA settings, using the preferred port bit.
  • ontap – Generate the path priority for NetApp storage arrays.
  • rdac – Generate the path priority for LSI/Engenio/NetApp E-Series Redundant Disk Array Controller (RDAC).
  • hp_sw – Generate the path priority for Compaq/HP controller in Active/Standby mode.
  • hds – Generate the path priority for Hitachi HDS Compaq/HP controller in active/standby mode.
• path_checker – One of the following is methods used to determine the paths’ state:
  • readsector0 – Read the first sector of the device. This is the default.
  • tur – Issue a Test Unit Ready (TUR) command to the device.
  • emc_clarrion – Query the EMC CLARiiON-specific EVPD page 0xC0 to determine the path state.
  • hp_sw – Check the path state for HP storage arrays with the Active/Standby firmware.
  • rdac – Check the path state for the LSI/Engenio/NetApp E-Series RDAC.
  • directio – Read the first sector with direct I/O.
• rr_min_io – The number of I/O to route to a path before switching to the next path in the same path group. This is for systems running kernels older than 2.6.31. Newer systems use rr_min_io_rq. The default is 1000.
• max_fds – The maximum number of file descriptors that can be opened by multipath and multipathd
• rr_weight – The path weight. Possible values are priorities or uniform.
• failback – One of the following methods is used to manage path group failback:
  • immediate – Fail back immediately to the highest priority path group that contains active paths.
  • manual – Do not perform automatic failback.
  • followover – Perform automatic failback only when the first path of a path group becomes active.
  • values > 0 – This indicates the time to defer failback in seconds.

blacklist Section in /etc/multipath.conf

blacklist section from /etc/multipath.conf file.

blacklist {
        wwid 26353900f02796769                   ### blacklist using WWID
	devnode "^sd[a-z]"                       ### blacklist all scsi Devices
	device {                                 ### blacklist by device type
	      vendor               "COMPAQ"
	      product              "HSV110  (C)COMPAQ"
	      }
}

Use the blacklist section in the /etc/multipath.conf file to exclude devices from being grouped into a multipath device. You can blacklist devices using any of the following identifiers. Use the same identifiers in the blacklist_exceptions section.

• WWID
• Device Name: Use the devnode keyword.
• Device Type: Use the device subsection.

multipaths Section in /etc/multipath.conf

Below is a sample multipaths section from /etc/multipath.conf file.

multipaths {
	multipath {
		wwid			3600508b4000156d700012000000b0000
		alias			yellow
		path_grouping_policy	multibus
		path_selector		"round-robin 0"
		failback		manual
		rr_weight		priorities
		no_path_retry		5
	}
	multipath {
		wwid			1DEC_____321816758474
		alias			red
	}
}

Set attributes in the multipaths section of the configuration file for each individual multipath device. These attributes apply to a specified multipath and override the attributes set in the defaults and devices sections.

The above sample multipaths section shows the settings that override the failback and no_path_retry default settings for the first WWID and set aliases for both WWIDs. Valid values for the no_path_retry attribute are:

• [n] – The number of retries until multipath stops the queueing and fails the path
• fail – Specifies immediate failure (no queueing)
• queue – Never stop queueing (queue forever until the path comes alive)

devices Section in /etc/multipath.conf

Below is a sample devices section from /etc/multipath.conf file.

devices {
	device {
		vendor			"COMPAQ  "
		product			"HSV110 (C)COMPAQ"
		path_grouping_policy	multibus
		path_checker		readsector0
		path_selector		"round-robin 0"
		hardware_handler	"0"
		failback		15
		rr_weight		priorities
		no_path_retry		queue
	}
	device {
		vendor			"COMPAQ  "
		product			"MSA1000         "
		path_grouping_policy	multibus
	}
}

DM-Multipath includes support for the most common storage arrays. Run either of the following commands to view information on supported devices:

# multipathd show config
# multipath –t

To add a storage device that is not supported by default, obtain the vendor, product, and revision information from the sysfs file system for the storage device and add this to the /etc/multipath.conf file. View the following files to obtain this information:

• /sys/block/device_name/device/vendor – Vendor information
• /sys/block/device_name/device/model – Product information
• /sys/block/device_name/device/rev – Revision information