Search

4.3. Configuration File Defaults

download PDF
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 configuration file includes a template of configuration defaults. This section is commented out, as follows.
#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
#}
To 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 so that it is multibus rather than the default value of failover, 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
}
Table 4.1, “Multipath Configuration Defaults” describes the attributes that are set in the defaults section of the multipath.conf configuration file. These values are used by DM Multipath unless they are overwritten by the attributes specified in the devices and multipaths sections of the multipath.conf file.
Table 4.1. Multipath Configuration Defaults
AttributeDescription
polling_interval Specifies the interval between two path checks in seconds. For properly functioning paths, the interval between checks will gradually increase to (4 * polling_interval). The default value is 5.
multipath_dir The directory where the dynamic shared objects are stored. The default value is system dependent, commonly /lib/multipath.
find_multipaths
Defines the mode for setting up multipath devices. If this parameter is set to yes, then multipath will not try to create a device for every path that is not blacklisted. Instead multipath will create a device only if one of three conditions are met:
- There are at least two paths that are not blacklisted with the same WWID.
- The user manually forces the creation of the device by specifying a device with the multipath command.
- A path has the same WWID as a multipath device that was previously created. Whenever a multipath device is created with find_multipaths set, multipath remembers the WWID of the device so that it will automatically create the device again as soon as it sees a path with that WWID. This allows you to have multipath automatically choose the correct paths to make into multipath devices, without having to edit the multipath blacklist. For instructions on the procedure to follow if you have previously created multipath devices when the find_multipaths parameter was not set, see Section 4.2, “Configuration File Blacklist”.
The default value is no. The default multipath.conf file created by mpathconf, however, will enable find_multipaths as of Red Hat Enterprise Linux 7.
reassign_maps Enable reassigning of device-mapper maps. With this option, The multipathd daemon will remap existing device-mapper maps to always point to the multipath device, not the underlying block devices. Possible values are yes and no. The default value is yes.
verbosity The default verbosity. Higher values increase the verbosity level. Valid levels are between 0 and 6. The default value is 2.
path_selector
Specifies the default algorithm to use in determining what path to use for the next I/O operation. Possible values include:
round-robin 0: Loop through every path in the path group, sending the same amount of I/O to each.
queue-length 0: Send the next bunch of I/O down the path with the least number of outstanding I/O requests.
service-time 0: Send the next bunch of I/O down the path with the shortest estimated service time, which is determined by dividing the total size of the outstanding I/O to each path by its relative throughput.
The default value is service-time 0.
path_grouping_policy
Specifies the default path grouping policy to apply to unspecified multipaths. Possible values include:
failover: 1 path per priority group.
multibus: all valid paths in 1 priority group.
group_by_serial: 1 priority group per detected serial number.
group_by_prio: 1 priority group per path priority value. Priorities are determined by callout programs specified as global, per-controller, or per-multipath options.
group_by_node_name: 1 priority group per target node name. Target node names are fetched in /sys/class/fc_transport/target*/node_name.
The default value is failover.
prio
Specifies the default function to call to obtain a path priority value. For example, the ALUA bits in SPC-3 provide an exploitable prio value. Possible values include:
const: Set a priority of 1 to all paths.
emc: Generate the path priority for EMC arrays.
alua: Generate the path priority based on the SCSI-3 ALUA settings. As of Red Hat Enterprise Linux 7.3, if you specify prio "alua exclusive_pref_bit" in your device configuration, multipath will create a path group that contains only the path with the pref bit set and will give that path group the highest priority.
ontap: Generate the path priority for NetApp arrays.
rdac: Generate the path priority for LSI/Engenio RDAC controller.
hp_sw: Generate the path priority for Compaq/HP controller in active/standby mode.
hds: Generate the path priority for Hitachi HDS Modular storage arrays.
The default value is const.
features
The default extra features of multipath devices, using the format: "number_of_features_plus_arguments feature1 ...".
Possible values for features include:
queue_if_no_path, which is the same as setting no_path_retry to queue. For information on issues that may arise when using this feature, see Section 5.6, “Issues with queue_if_no_path feature”.
retain_attached_hw_handler: If this parameter is set to yes and the SCSI layer has already attached a hardware handler to the path device, multipath will not force the device to use the hardware_handler specified by the multipath.conf file. If the SCSI layer has not attached a hardware handler, multipath will continue to use its configured hardware handler as usual. The default value is no.
pg_init_retries n: Retry path group initialization up to n times before failing where 1 <= n <= 50.
pg_init_delay_msecs n: Wait n milliseconds between path group initialization retries where 0 <= n <= 60000.
path_checker
Specifies the default method used to determine the state of the paths. Possible values include:
readsector0: Read the first sector of the device.
tur: Issue a TEST UNIT READY command to the device.
emc_clariion: Query the EMC Clariion specific EVPD page 0xC0 to determine the path.
hp_sw: Check the path state for HP storage arrays with Active/Standby firmware.
rdac: Check the path state for LSI/Engenio RDAC storage controller.
directio: Read the first sector with direct I/O.
The default value is directio.
failback
Manages path group failback.
A value of immediate specifies immediate failback to the highest priority path group that contains active paths.
A value of manual specifies that there should not be immediate failback but that failback can happen only with operator intervention.
A value of followover specifies that automatic failback should be performed when the first path of a path group becomes active. This keeps a node from automatically failing back when another node requested the failover.
A numeric value greater than zero specifies deferred failback, expressed in seconds.
The default value is manual.
rr_min_io Specifies the number of I/O requests to route to a path before switching to the next path in the current path group. This setting is only for systems running kernels older than 2.6.31. Newer systems should use rr_min_io_rq. The default value is 1000.
rr_min_io_rq Specifies the number of I/O requests to route to a path before switching to the next path in the current path group, using request-based device-mapper-multipath. This setting should be used on systems running current kernels. On systems running kernels older than 2.6.31, use rr_min_io. The default value is 1.
rr_weight If set to priorities, then instead of sending rr_min_io requests to a path before calling path_selector to choose the next path, the number of requests to send is determined by rr_min_io times the path's priority, as determined by the prio function. If set to uniform, all path weights are equal. The default value is uniform.
no_path_retry
A numeric value for this attribute specifies the number of times the system should attempt to use a failed path before disabling queuing.
A value of fail indicates immediate failure, without queuing.
A value of queue indicates that queuing should not stop until the path is fixed.
The default value is 0.
user_friendly_names If set to yes, specifies that the system should use the /etc/multipath/bindings file to assign a persistent and unique alias to the multipath, in the form of mpathn. If set to no, specifies that the system should use the WWID as the alias for the multipath. In either case, what is specified here will be overridden by any device-specific aliases you specify in the multipaths section of the configuration file. The default value is no.
queue_without_daemon If set to no, the multipathd daemon will disable queuing for all devices when it is shut down. The default value is no.
flush_on_last_del If set to yes, the multipathd daemon will disable queuing when the last path to a device has been deleted. The default value is no.
max_fds Sets the maximum number of open file descriptors that can be opened by multipath and the multipathd daemon. This is equivalent to the ulimit -n command. As of the Red Hat Enterprise Linux 6.3 release, the default value is max, which sets this to the system limit from /proc/sys/fs/nr_open. For earlier releases, if this is not set the maximum number of open file descriptors is taken from the calling process; it is usually 1024. To be safe, this should be set to the maximum number of paths plus 32, if that number is greater than 1024.
checker_timeout The timeout to use for prioritizers and path checkers that issue SCSI commands with an explicit timeout, in seconds. The default value is taken from sys/block/sdx/device/timeout.
fast_io_fail_tmo The number of seconds the SCSI layer will wait after a problem has been detected on an FC remote port before failing I/O to devices on that remote port. This value should be smaller than the value of dev_loss_tmo. Setting this to off will disable the timeout. The default value is determined by the OS. The fast_io_fail_tmo option overrides the values of the recovery_tmo and replacement_timeout options. For details, see Section 4.6, “iSCSI and DM Multipath overrides”.
dev_loss_tmo The number of seconds the SCSI layer will wait after a problem has been detected on an FC remote port before removing it from the system. Setting this to infinity will set this to 2147483647 seconds, or 68 years. The default value is determined by the OS.
hw_string_match
Each device configuration in the devices section of the multipath.conf file will either create its own device configuration or it will modify one of the built-in device configurations. If hw_string_match is set to yes, then if the vendor, product, and revision strings in a user's device configuration exactly match those strings in a built-in device configuration, the built-in configuration is modified by the options in the user's configuration. Otherwise, the user's device configuration is treated as a new configuration. If hw_string_match is set to no, a regular expression match is used instead of a string match.
The hw_string_match parameter is set to no by default.
retain_attached_hw_handler If this parameter is set to yes and the SCSI layer has already attached a hardware handler to the path device, multipath will not force the device to use the hardware_handler specified by the multipath.conf file. If the SCSI layer has not attached a hardware handler, multipath will continue to use its configured hardware handler as usual. The default value is no.
detect_prio If this is set to yes, multipath will first check if the device supports ALUA, and if so it will automatically assign the device the alua prioritizer. If the device does not support ALUA, it will determine the prioritizer as it always does. The default value is no.
uid_attribute Provides a unique path identifier. The default value is ID_SERIAL.
force_sync (Red Hat Enterprise Linux Release 7.1 and later) If this is set to "yes", it prevents path checkers from running in async mode. This means that only one checker will run at a time. This is useful in the case where many multipathd checkers running in parallel causes significant CPU pressure. The default value is no.
delay_watch_checks (Red Hat Enterprise Linux Release 7.2 and later) If set to a value greater than 0, the multipathd daemon will watch paths that have recently become valid for the specified number of checks. If they fail again while they are being watched, when they next become valid they will not be used until they have stayed up for the number of consecutive checks specified with delay_wait_checks. This allows you to keep paths that may be unreliable from immediately being put back into use as soon as they come back online. The default value is no.
delay_wait_checks (Red Hat Enterprise Linux Release 7.2 and later) If set to a value greater than 0, when a device that has recently come back online fails again within the number of checks specified with delay_watch_checks, the next time it comes back online it will be marked and delayed and it will not be used until it has passed the number of checks specified in delay_wait_checks. The default value is no.
ignore_new_boot_devs (Red Hat Enterprise Linux Release 7.2 and later) If set to yes, when the node is still in the initramfs file system during early boot, multipath will not create any devices whose WWIDs do not already exist in the initramfs copy of the /etc/multipath/wwids. This feature can be used for booting up during installation, when multipath would otherwise attempt to set itself up on devices that it did not claim when they first appeared by means of the udev rules. This parameter can be set to yes or no. If unset, it defaults to no.
retrigger_tries, retrigger_delay (Red Hat Enterprise Linux Release 7.2 and later) The retrigger_tries and retrigger_delay parameters are used in conjunction to make multipathd retrigger uevents if udev failed to completely process the original ones, leaving the device unusable by multipath. The retrigger_tries parameter sets the number of times that multipath will try to retrigger a uevent if a device has not been completely set up. The retrigger_delay parameter sets the number of seconds between retries. Both of these options accept numbers greater than or equal to zero. Setting the retrigger_tries parameter to zero disables retries. Setting the retrigger_delay parameter to zero causes the uevent to be reissued on the next loop of the path checker. If the retrigger_tries parameter is unset, it defaults to 3. If the retrigger_delay parameter is unset, it defaults to 10.
new_bindings_in_boot (Red Hat Enterprise Linux Release 7.2 and later) The new_bindings_in_boot parameter is used to keep multipath from giving out a user_friendly_name in the initramfs file system that was already given out by the bindings file in the regular file system, an issue that can arise since the user_friendly_names bindings in the initramfs file system get synced with the bindings in the regular file system only when the initramfs file system is remade. When this parameter is set to no multipath will not create any new bindings in the initramfs file system. If a device does not already have a binding in the initramfs copy of /etc/multipath/bindings, multipath will use its WWID as an alias instead of giving it a user_friendly_name. Later in boot, after the node has mounted the regular filesystem, multipath will give out a user_friendly_name to the device. This parameter can be set to yes or no. If unset, it defaults to no.
config_dir (Red Hat Enterprise Linux Release 7.2 and later) If set to anything other than "", multipath will search this directory alphabetically for files ending in ".conf" and it will read configuration information from them, just as if the information were in the /etc/multipath.conf file. This allows you to have one main configuration that you share between machines in addition to a separate machine-specific configuration file or files. The config_dir parameter must either be "" or a fully qualified directory name. This parameter can be set only in the main /etc/multipath.conf file and not in one of the files specified in the config_dir file itself. The default value is /etc/multipath/conf.d.
deferred_remove If set to yes, multipathd will do a deferred remove instead of a regular remove when the last path device has been deleted. This ensures that if a multipathed device is in use when a regular remove is performed and the remove fails, the device will automatically be removed when the last user closes the device. The default value is no.
log_checker_err If set to once, multipathd logs the first path checker error at verbosity level 2. Any later errors are logged at verbosity level 3 until the device is restored. If it is set to always, multipathd always logs the path checker error at verbosity level 2. The default value is always.
skip_kpartx (Red Hat Enterprise Linux Release 7.3 and later) If set to yes, kpartx will not automatically create partitions on the device. This allows users to create a multipath device without creating partitions, even if the device has a partition table. The default value of this option is no.
max_sectors_kb (Red Hat Enterprise Linux Release 7.4 and later) Sets the max_sectors_kb device queue parameter to the specified value on all underlying paths of a multipath device before the multipath device is first activated. When a multipath device is created, the device inherits the max_sectors_kb value from the path devices. Manually raising this value for the multipath device or lowering this value for the path devices can cause multipath to create I/O operations larger than the path devices allow. Using the max_sectors_kb parameter is an easy way to set these values before a multipath device is created on top of the path devices and prevent invalid-sized I/O operations from being passed. If this parameter is not set by the user, the path devices have it set by their device driver, and the multipath device inherits it from the path devices.
remove_retries (Red Hat Enterprise Linux Release 7.4 and later) Sets how may times multipath will retry removing a device that is in use. Between each attempt, multipath will sleep 1 second. The default value is 0, which means that multipath will not retry the remove.
disable_changed_wwids (Red Hat Enterprise Linux Release 7.4 and later) If set to yes and the WWID of a path device changes while it is part of a multipath device, multipath will disable access to the path device until the WWID of the path is restored to the WWID of the multipath device. The default value is no, which does not check if a path's WWID has changed.
detect_path_checker (Red Hat Enterprise Linux Release 7.4 and later) If set to yes, multipath will try to detect if the device supports ALUA. If so, the device will automatically use the tur path checker. If not, the path_checker will be selected as usual. The default value is no.
reservation_key
This is the service action reservation key used by mpathpersist. It must be set for all multipath devices using persistent reservations, and it must be the same as the RESERVATION KEY field of the PERSISTENT RESERVE OUT parameter list which contains an 8-byte value provided by the application client to the device server to identify the I_T nexus. If the --param-aptpl option is used when registering the key with mpathpersist, :aptpl must be appended to the end of the reservation key.
As of Red Hat Enterprise Linux Release 7.5, this parameter can be set to file, which will store the RESERVATION KEY registered by mpath‐persist in the prkeys file. The multipathd daemon will then use this key to register additional paths as they appear. When the registration is removed, the RESERVATION KEY is removed from the prkeys file. It is unset by default.
prkeys_file (Red Hat Enterprise Linux Release 7.5 and later) The full path name of the prkeys file, which is used by the multipathd daemon to keep track of the reservation key used for a specific WWID when the reservation_key parameter is set to file. The default value is /etc/multipath/prkeys.
all_tg_pt (Red Hat Enterprise Linux Release 7.6 and later) If this option is set to yes, when mpathpersist registers keys it will treat a key registered from one host to one target port as going from one host to all target ports. This must be set to yes to successfully use mpathpersist on arrays that automatically set and clear registration keys on all target ports from a host, instead of per target port per host. The default value is no.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.