Chapter 3. Configuring DM Multipath

You can set up DM Multipath with the mpathconf utility. This utility creates or edits the /etc/multipath.conf multipath configuration file based on the following scenarios:

  • If the /etc/multipath.conf file already exists, the mpathconf utility will edit it.
  • If the /etc/multipath.conf file does not exist, the mpathconf utility will create the /etc/multipath.conf file from scratch.

3.1. Checking for the device-mapper-multipath package

Before setting up DM Multipath on your system, ensure that your system is up-to-date and includes the device-mapper-multipath package.

Procedure

  1. Check if your system includes the device-mapper-multipath package: 

    # rpm -q device-mapper-multipath
device-mapper-multipath-current-package-version

    If your system does not include the package, it prints the following: 

    package device-mapper-multipath is not installed

  2. If your system does not include the package, install it by running the following command: 

    # dnf install device-mapper-multipath

3.2. Setting up DM Multipath for a basic failover configuration

Use the following procedure to set up DM Multipath for a basic failover configuration if you need to edit the /etc/multipath.conf file before starting the multipathd daemon.

Procedure

  1. Enable the multipath configuration file: 

    # mpathconf --enable

  2. Edit the /etc/multipath.conf file if necessary. The default settings for DM Multipath are compiled into the system and do not need to be explicitly set in the /etc/multipath.conf file.

    The default value of path_grouping_policy is set to failover, so in this example you do not need to edit the /etc/multipath.conf file.

    The initial defaults section of the configuration file configures your system so that the names of the multipath devices are of the form /dev/mapper/mpathn; without this setting, the names of the multipath devices would be aliased to the WWID of the device. If you do not want to use user friendly names, you can enter the following command: 

    # mpathconf --enable --user_friendly_names n

    If you need to edit the multipath configuration file after you have started the multipath daemon, you must execute the systemctl reload multipathd.service command for the changes to take effect.

  3. Save the configuration file and exit the editor, if necessary.

  4. Start the multipath daemon and create the multipath devices: 

    # systemctl start multipathd.service
Note

If you remove the device-mapper-multipath package, this does not remove the /etc/multipath.conf file, or any files in the /etc/multipath directory, since that directory can contain more that just the files listed currently. You might need to remove those files manually on subsequent installations of the device-mapper-multipath package.

3.3. Ignoring local disks when generating multipath devices

Some machines have local SCSI cards for their internal disks and DM Multipath is not recommended for these devices. If you set the find_multipaths configuration parameter to on, you do not have to disable multipathing on these devices.

If you do not set the find_multipaths configuration parameter to on, you can use the following procedure to modify the DM Multipath configuration file to ignore the local disks when configuring multipath.

Procedure

  1. Determine which disks are the internal disks. In these examples, /dev/sda is the internal disk:

    • Display existing multipath devices: 

      # multipath -v2 -l

SIBM-ESXSST336732LC____F3ET0EP0Q000072428BX1 dm-2 WINSYS,SF2372
size=33 GB features="0" hwhandler="0" wp=rw
`-+- policy='round-robin 0' prio=0 status=active
  |- 0:0:0:0 sda 8:0 active undef running

    • Display additional multipath devices that DM Multipath could create: 

      # multipath -v2 -d

: SIBM-ESXSST336732LC____F3ET0EP0Q000072428BX1 undef WINSYS,SF2372
size=33 GB features="0" hwhandler="0" wp=undef
`-+- policy='round-robin 0' prio=1 status=undef
  |- 0:0:0:0 sda 8:0  undef ready running

  2. Edit the blacklist section of the /etc/multipath.conf file to include this device.

    Identify the device using its WWID attribute. Although you could identify the sda device using a devnode type, that would not be a safe procedure because /dev/sda is not guaranteed to be the same on reboot.

    In the previous example, the WWID of the /dev/sda device is SIBM-ESXSST336732LC____F3ET0EP0Q000072428BX1. To ignore this device, include the following in the /etc/multipath.conf file: 

    blacklist {
      wwid SIBM-ESXSST336732LC____F3ET0EP0Q000072428BX1
}

  3. Validate the /etc/multipath.conf file after modifying the multipath configuration file by running one of the following commands:

    • To display any configuration errors, run: 

      # multipath -t > /dev/null

    • To display the new configuration with the changes added, run: 

      # multipath -t

  4. Reload the /etc/multipath.conf file and reconfigure the multipathd daemon for changes to take effect: 

    # service multipathd reload

Additional resources

  • multipath.conf(5) man page

3.4. Configuring additional storage devices

By default, DM Multipath includes support for the most common storage arrays, which support DM Multipath.

Procedure

  • View the default configuration value, including supported devices: 

    # multipathd show config
# multipath -t

  • Optional: To add an additional storage device that is not supported by default as a known multipath device, edit the /etc/multipath.conf file and insert the appropriate device information.

    The following example ilustrates how to add information about the HP Open-V series. This sets the device to queue for a minute or 12 retries and 5 seconds per retry after all paths have failed. 

    devices {
        device {
                vendor "HP"
                product "OPEN-V"
                no_path_retry 12
        }
}

3.5. Setting up multipathing in the initramfs file system

You can set up multipathing in the initramfs file system. You do not need to set it up if you are not using the devices that you want multipathed, until after boot leaves the initramfs file system.

Prerequisites

  • You have configured DM multipath in your system.

Procedure

  • Rebuild the initramfs file system with the multipath configuration files by running the following command: 

    # dracut --force --add multipath

    If you run multipath from the initramfs file system and you make any changes to the multipath configuration files, you must rebuild the initramfs file system for the changes to take effect. When a root device uses multipath, running the dracut command automatically adds the multipath module to the initramfs.

  • Optional: If you need multipath running in the initramfs, but you are not setting up a multipathed root device, run: 

    # echo add_dracutmodules+=\"multipath\" > /etc/dracut.conf.d/multipath.conf
# dracut --force
Note

The dracut command includes multipath in the initramfs, even after multipath is no longer required. To stop including multipath, run: 

# rm /etc/dracut.conf.d/multipath.conf
# dracut --force