Menu Close
Chapter 5. Modifying the DM-Multipath configuration file
By default, DM Multipath provides configuration values for the most common uses of multipathing. In addition, DM Multipath includes support for the most common storage arrays that themselves support DM Multipath. You can override the default configuration values for DM Multipath by editing the /etc/multipath.conf
configuration file. If necessary, you can also add an unsupported by default storage array to the configuration file.
For information on the default configuration values, including supported devices, run either of the following commands:
# multipathd show config # multipath -t
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
In the multipath configuration file, you need to specify only the sections that you need for your configuration, or that you wish to change from the default values. If there are sections of the file that are not relevant to your environment or for which you do not need to override the default values, you can leave them commented out, as they are in the initial file.
The configuration file allows regular expression description syntax.
5.1. Configuration file overview
The multipath configuration file is divided into the following sections:
- blacklist
- Listing of specific devices that will not be considered for multipath.
- blacklist_exceptions
-
Listing of multipath devices that would otherwise be ignored according to the parameters of the
blacklist
section. - defaults
- General default settings for DM Multipath.
- multipaths
-
Settings for the characteristics of individual multipath devices. These values overwrite what is specified in the
overrides
,devices
, anddefaults
sections of the configuration file. - devices
-
Settings for the individual storage controllers. These values overwrite what is specified in the
defaults
section of the configuration file. If you are using a storage array that is not supported by default, you may need to create adevices
subsection for your array. - overrides
-
Settings that are applied to all devices. These values overwrite what is specified in the
devices
anddefaults
sections of the configuration file.
When the system determines the attributes of a multipath device, it checks the settings of the separate sections from the multipath.conf
file in the following order:
-
multipaths
section -
overrides
section -
devices
section -
defaults
section
5.2. DM Multipath overrides of the device timeout
The recovery_tmo
sysfs
option controls the timeout for a particular iSCSI device. The following options globally override the recovery_tmo
values:
-
The
replacement_timeout
configuration option globally overrides therecovery_tmo
value for all iSCSI devices. For all iSCSI devices that are managed by DM Multipath, the
fast_io_fail_tmo
option in DM Multipath globally overrides therecovery_tmo
value.The
fast_io_fail_tmo
option in DM Multipath also overrides thefast_io_fail_tmo
option in Fibre Channel devices.
The DM Multipath fast_io_fail_tmo
option takes precedence over replacement_timeout
. Red Hat does not recommend using replacement_timeout
to override recovery_tmo
in devices managed by DM Multipath because DM Multipath always resets recovery_tmo
, when the multipathd
service reloads.
5.3. Modifying multipath configuration file defaults
The /etc/multipath.conf
configuration file includes a defaults
section that sets the user_friendly_names
parameter to yes
, as follows.
defaults { user_friendly_names yes }
This overwrites the default value of the user_friendly_names
parameter. The default values that are set in the defaults section on the multipath.conf file
, are used by DM Multipath unless they are overwritten by the attributes specified in the devices, multipath, or overrides sections of the multipath.conf
file.
Procedure
View the
/etc/multipath.conf
configuration file, which includes a template of configuration defaults:#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 #}
Overwrite the default value for any of the configuration parameters. You can copy the relevant line from this template into the
defaults
section and uncomment it.For example, to overwrite the
path_grouping_policy
parameter tomultibus
instead of the default value offailover
, copy the appropriate line from the template to the initial defaults section of the configuration file, and uncomment it, as follows:defaults { user_friendly_names yes path_grouping_policy multibus }
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
Reload the
/etc/multipath.conf
file and reconfigure themultipathd
daemon for changes to take effect:# service multipathd reload
Additional resources
-
multipath.conf(5)
andmultipathd(8)
man pages
5.4. Modifying multipath settings for specific devices
In the multipaths
section of the multipath.conf
configuration file, you can add configurations that are specific to an individual multipath device, referenced by the mandatory WWID parameter.
These defaults are used by DM Multipath and override attributes set in the overrides
, defaults
, and devices
sections of the multipath.conf
file. There can be any number of multipath subsections in the multipaths
section.
Procedure
Modify the
multipaths
section for specific multipath device. The following example shows multipath attributes specified in the configuration file for two specific multipath devices:-
The first device has a WWID of
3600508b4000156d70001200000b0000
and a symbolic name ofyellow
. -
The second multipath device in the example has a WWID of
1DEC_321816758474
and a symbolic name ofred
.
In this example, the
rr_weight
attribute is set topriorities
.multipaths { multipath { wwid 3600508b4000156d70001200000b0000 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 rr_weight priorities } }
-
The first device has a WWID of
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
Reload the
/etc/multipath.conf
file and reconfigure themultipathd
daemon for changes to take effect:# service multipathd reload
Additional resources
-
multipath.conf(5)
man page
5.5. Modifying multipath settings for storage controllers
The devices
section of the multipath.conf
configuration file sets attributes for individual storage devices. These attributes are used by DM Multipath unless they are overwritten by the attributes specified in the multipaths
or overrides
sections of the multipath.conf
file for paths that contain the device. These attributes override the attributes set in the defaults
section of the multipath.conf
file.
Procedure
View the information on the default configuration value, including supported devices:
# multipathd show config # multipath -t
Many devices that support multipathing are included by default in a multipath configuration.
-
Optional: If you need to modify the default configuration values, you can overwrite the default values by including an entry in the configuration file for the device that overwrites those values. You can copy the device configuration defaults for the device that the
multipathd show config
command displays and override the values that you want to change. Add a device that is not configured automatically by default to the
devices
section of the configuration file by setting thevendor
andproduct
parameters. Find these values by opening the/sys/block/device_name/device/vendor
and/sys/block/device_name/device/model
files where device_name is the device to be multipathed, as mentioned in the following example:# cat /sys/block/sda/device/vendor WINSYS # cat /sys/block/sda/device/model SF2372
Optional: Specify the additional parameters depending on your specific device:
active/active
device-
Usually there is no need to set additional parameters in this case. If required, you might set
path_grouping_policy
tomultibus
. Other parameters you may need to set areno_path_retry
andrr_min_io
. active/passive
device-
If it automatically switches paths with I/O to the passive path, you need to change the checker function to one that does not send I/O to the path to test if it is working, otherwise, your device will keep failing over. This means that you have set the
path_checker
totur
, which works for all SCSI devices that support the Test Unit Ready command, which most do.
If the device needs a special command to switch paths, then configuring this device for multipath requires a hardware handler kernel module. The current available hardware handler is
emc
. If this is not sufficient for your device, you might not be able to configure the device for multipath.The following example shows a
device
entry in the multipath configuration file:# } # device { # vendor "COMPAQ " # product "MSA1000 " # path_grouping_policy multibus # path_checker tur # rr_weight priorities # } #}
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
Reload the
/etc/multipath.conf
file and reconfigure themultipathd
daemon for changes to take effect:# service multipathd reload
Additional resources
-
multipath.conf(5)
andmultipathd(8)
man pages
5.6. Setting multipath values for all devices
Using the overrides
section of the multipath.conf
configuration file, you can set a configuration value for all of your devices. This section supports all attributes that are supported by both the devices
and defaults
section of the multipath.conf
configuration file, which is all of the devices
section attributes except vendor
, product
, and revision
.
These attributes are used by DM Multipath for all devices unless they are overwritten by the attributes specified in the multipaths
section of the multipath.conf
file for paths that contain the device. These attributes override the attributes set in the devices
and defaults
sections of the multipath.conf
file.
Procedure
Override device specific settings. For example, you might want all devices to set
no_path_retry
tofail
. Use the following command to turn off queueing, when all paths have failed. This overrides any device specific settings.overrides { no_path_retry fail }
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
Reload the
/etc/multipath.conf
file and reconfigure themultipathd
daemon for changes to take effect:# service multipathd reload
Additional resources
-
multipath.conf(5)
man page