16.6 Creating or Modifying the /etc/multipath.conf File

The /etc/multipath.conf file does not exist unless you create it. Default multipath device settings are applied automatically when the multipathd daemon runs unless you create the multipath configuration file and personalize the settings.

IMPORTANT: Testing and Permanently Applying Changes from /etc/multipath.conf

Whenever you create or modify the /etc/multipath.conf file, the changes are not automatically applied when you save the file. This allows you to perform a dry run to verify your changes before they are committed. When you are satisfied with the revised settings, you can update the multipath maps as described in Section 16.6.4, Applying the /etc/multipath.conf File Changes to Update the Multipath Maps.

16.6.1 Creating the /etc/multipath.conf File

  1. Create an empty /etc/multipath.conf file with an editor of your choice.

  2. Make sure to add an appropriate device section for your SAN. Most vendors provide documentation on the proper setup of the device section. Note that different SANs require individual device sections.

    If you are using a storage subsystem that is automatically detected (see Storage Arrays That Are Automatically Detected for Multipathing), adding a device is not required—the default settings for this device will be applied in this case.

  3. Create a blacklist section containing all non-multipath devices of your machine. Refer to Section 16.8, Blacklisting Non-Multipath Devices for details.

  4. If required, add more sections to the configuration file. Refer to Section 16.6.2, Sections in the /etc/multipath.conf File for a brief introduction. More details are available when running man 5 multipath.conf.

  5. When finished, save /etc/multipath.conf and test your settings as described in Section 16.6.3, Verifying the Multipath Setup in the /etc/multipath.conf File.

  6. When you have successfully verified the configuration, apply it as described in Section 16.6.4, Applying the /etc/multipath.conf File Changes to Update the Multipath Maps.

16.6.2 Sections in the /etc/multipath.conf File

The /etc/multipath.conf file is organized into the following sections. See man 5 multipath.conf for details.

defaults

General default settings for multipath I/0. These values are used if no values are given in the appropriate device or multipath sections. For information, see Section 16.7, Configuring Default Policies for Polling, Queuing, and Failback.

blacklist

Lists the device names to discard as not multipath candidates. Devices can be identified by their device node name (devnode), their WWID (wwid), or their vendor or product strings (device). You can typically ignore non-multipathed devices, such as hpsa, fd, hd, md, dm, sr, scd, st, ram, raw, loop. For more information and examples, see Blacklisting Non-Multipath Devices.

blacklist_exceptions

Lists the device names of devices to be treated as multipath candidates even if they are on the blacklist. Devices can be identified by their device node name (devnode), their WWID (wwid), or their vendor or product strings (device). You must specify the excepted devices by using the same keyword that you used in the blacklist. For example, if you used the devnode keyword for devices in the blacklist, you use the devnode keyword to exclude some devices in the blacklist exceptions. It is not possible to blacklist devices by using the devnode keyword and to exclude some of them by using the wwid keyword. For more information and examples, see Blacklisting Non-Multipath Devices.

multipaths

Specifies settings for individual multipath devices. Except for settings that do not support individual settings, these values overwrite what is specified in the defaults and devices sections of the configuration file.

devices

Specifies settings for individual storage controllers. These values overwrite values specified in the defaults section of the configuration file. If you use a storage array that is not supported by default, you can create a devices subsection to specify the default settings for it. These values can be overwritten by settings for individual multipath devices if the keyword allows it.

For information, see the following:

16.6.3 Verifying the Multipath Setup in the /etc/multipath.conf File

Whenever you create or modify the /etc/multipath.conf file, the changes are not automatically applied when you save the file. You can perform a dry run of the setup to verify the multipath setup before you update the multipath maps.

At the server command prompt, enter

sudo multipath -v2 -d

This command scans the devices, then displays what the setup would look like if you commit the changes. It is assumed that the multipathd daemon is already running with the old (or default) multipath settings when you modify the /etc/multipath.conf file and perform the dry run. If the changes are acceptable, continue with the next step.

The output is similar to the following:

26353900f02796769
[size=127 GB]
[features="0"]
[hwhandler="1    emc"]

\_ round-robin 0 [first]
  \_ 1:0:1:2 sdav 66:240  [ready ]
  \_ 0:0:1:2 sdr  65:16   [ready ]

\_ round-robin 0
  \_ 1:0:0:2 sdag 66:0    [ready ]
  \_ 0:0:0:2 sdc   8:32   [ready ]

Paths are grouped into priority groups. Only one priority group is in active use at a time. To model an active/active configuration, all paths end in the same group. To model an active/passive configuration, the paths that should not be active in parallel are placed in several distinct priority groups. This normally happens automatically on device discovery.

The output shows the order, the scheduling policy used to balance I/O within the group, and the paths for each priority group. For each path, its physical address (host:bus:target:lun), device node name, major:minor number, and state is shown.

By using a verbosity level of -v3 in the dry run, you can see all detected paths, multipaths, and device maps. Both WWID and device node blacklisted devices are displayed.

The following is an example of -v3 output on a 64-bit SLES 11 SP2 server with two Qlogic HBAs connected to a Xiotech Magnitude 3000 SAN. Some multiple entries have been omitted to shorten the example.

sudo multipath -v3 d
dm-22: device node name blacklisted
< content omitted >
loop7: device node name blacklisted
< content omitted >
md0: device node name blacklisted
< content omitted >
dm-0: device node name blacklisted
sdf: not found in pathvec
sdf: mask = 0x1f
sdf: dev_t = 8:80
sdf: size = 105005056
sdf: subsystem = scsi
sdf: vendor = XIOtech
sdf: product = Magnitude 3D
sdf: rev = 3.00
sdf: h:b:t:l = 1:0:0:2
sdf: tgt_node_name = 0x202100d0b2028da
sdf: serial = 000028DA0014
sdf: getuid= "/lib/udev/scsi_id --whitelisted --device=/dev/%n" (config file default)
sdf: uid = 200d0b2da28001400 (callout)
sdf: prio = const (config file default)
sdf: const prio = 1
[...]
ram15: device node name blacklisted
[...]
===== paths list =====
uuid              hcil    dev dev_t pri dm_st  chk_st  vend/prod/rev
200d0b2da28001400 1:0:0:2 sdf 8:80  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28005400 1:0:0:1 sde 8:64  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28004d00 1:0:0:0 sdd 8:48  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28001400 0:0:0:2 sdc 8:32  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28005400 0:0:0:1 sdb 8:16  1   [undef][undef] XIOtech,Magnitude 3D
200d0b2da28004d00 0:0:0:0 sda 8:0   1   [undef][undef] XIOtech,Magnitude 3D
params = 0 0 2 1 round-robin 0 1 1 8:80 1000 round-robin 0 1 1 8:32 1000
status = 2 0 0 0 2 1 A 0 1 0 8:80 A 0 E 0 1 0 8:32 A 0
sdf: mask = 0x4
sdf: path checker = directio (config file default)
directio: starting new request
directio: async io getevents returns 1 (errno=Success)
directio: io finished 4096/0
sdf: state = 2
[...]

16.6.4 Applying the /etc/multipath.conf File Changes to Update the Multipath Maps

Changes to the /etc/multipath.conf file cannot take effect when multipathd is running. After you make changes, save and close the file, then do the following to apply the changes and update the multipath maps:

  1. Stop the multipathd service:

    sudo systemctl stop multipathd
  2. Clear old multipath bindings by entering

    sudo /sbin/multipath -F
  3. Create new multipath bindings by entering

    sudo /sbin/multipath -v2 -l
  4. Restart the multipathd service:

    sudo systemctl start multipathd
  5. Run dracut -f to re-create the initrd image on your system, then reboot for the changes to take effect.

16.6.5 Generating a WWID

To identify a device over different paths, multipath uses a World Wide Identification (WWID) for each device. If the WWID is the same for two device paths, they are assumed to represent the same device. We recommend not changing the method of WWID generation, unless there is a compelling reason to do so. For more details, see man multipath.conf.