1MULTIPATH.CONF(5) File Formats Manual MULTIPATH.CONF(5)
2
6 multipath.conf - multipath daemon configuration file.
7
9 /etc/multipath.conf is the configuration file for the multipath daemon.
10 It is used to overwrite the built-in configuration table of multipathd.
11 Any line whose first non-white-space character is a '#' is considered a
12 comment line. Empty lines are ignored.
13 Currently used multipathd configuration can be displayed with the mul‐
15 tipath -t or multipathd show config command.
16
18 The configuration file contains entries of the form:
19 <section> {
21 <attribute> <value>
22 ...
23 <subsection> {
24 <attribute> <value>
25 ...
26 }
27 }
28 Each section contains one or more attributes or subsections. The recog‐
30 nized keywords for attributes or subsections depend on the section in
31 which they occur.
32 <attribute> and <value> must be on a single line. <attribute> is one
34 of the keywords listed in this man page. <value> is either a simple
35 word (containing no whitespace and none of the characters '"', '#', and
36 '!') or one string enclosed in double quotes ("..."). Outside a quoted
37 string, text starting with '#', and '!' is regarded as a comment and
38 ignored until the end of the line. Inside a quoted string, '#' and '!'
39 are normal characters, and whitespace is preserved. To represent a
40 double quote character inside a double quoted string, use two consecu‐
41 tive double quotes ('""'). Thus '2.5" SSD' can be written as "2.5""
42 SSD".
43 Opening braces ('{') must follow the (sub)section name on the same
45 line. Closing braces ('}') that mark the end of a (sub)section must be
46 the only non-whitespace character on the line. Whitespace is ignored
47 except inside double quotes, thus the indentation shown in the above
48 example is helpful for human readers but not mandatory.
49 Note on regular expressions: The multipath.conf syntax allows many at‐
51 tribute values to be specified as POSIX Extended Regular Expressions
52 (see regex(7)). These regular expressions are case sensitive and not
53 anchored, thus the expression "bar" matches "barbie", "rhabarber", and
54 "wunderbar", but not "Barbie". To avoid unwanted substring matches,
55 standard regular expression syntax using the special characters "^" and
56 "$" can be used.
57 The following section keywords are recognized:
59 defaults This section defines default values for attributes
61 which are used whenever no values are given in the ap‐
62 propriate device or multipath sections.
63 blacklist This section defines which devices should be excluded
65 from the multipath topology discovery.
66 blacklist_exceptions
68 This section defines which devices should be included
69 in the multipath topology discovery, despite being
70 listed in the blacklist section.
71 multipaths This section defines the multipath topologies. They
73 are indexed by a World Wide Identifier(WWID). For de‐
74 tails on the WWID generation see section WWID genera‐
75 tion below. Attributes set in this section take prece‐
76 dence over all others.
77 devices This section defines the device-specific settings. De‐
79 vices are identified by vendor, product, and revision.
80 overrides This section defines values for attributes that should
82 override the device-specific settings for all devices.
83
85 The defaults section recognizes the following keywords:
86 verbosity Default verbosity. Higher values increase the ver‐
88 bosity level. Valid levels are between 0 and 6.
89 The default is: 2
91 polling_interval Interval between two path checks in seconds. For prop‐
93 erly functioning paths, the interval between checks
94 will gradually increase to max_polling_interval. This
95 value will be overridden by the WatchdogSec setting in
96 the multipathd.service definition if systemd is used.
97 The default is: 5
99 max_polling_interval
101 Maximal interval between two path checks in seconds.
102 The default is: 4 * polling_interval
104 reassign_maps Enable reassigning of device-mapper maps. With this
106 option multipathd will remap existing device-mapper
107 maps to always point to multipath device, not the un‐
108 derlying block devices. Possible values are yes and
109 no.
110 The default is: no
112 multipath_dir Directory where the dynamic shared objects are stored.
114 Defined at compile time, commonly /lib64/multipath/ or
115 /lib/multipath/.
116 The default is: <system dependent>
118 path_selector The default path selector algorithm to use; they are
120 offered by the kernel multipath target. There are
121 three selector algorithms:
122 round-robin 0
124 Loop through every path in the path group,
125 sending the same amount of I/O to each.
126 Some aspects of behavior can be controlled
127 with the attributes: rr_min_io,
128 rr_min_io_rq and rr_weight.
129 queue-length 0
131 (Since 2.6.31 kernel) Choose the path for
132 the next bunch of I/O based on the amount
133 of outstanding I/O to the path.
134 service-time 0
136 (Since 2.6.31 kernel) Choose the path for
137 the next bunch of I/O based on the amount
138 of outstanding I/O to the path and its
139 relative throughput.
140 historical-service-time 0
142 (Since 5.8 kernel) Choose the path for the
143 next bunch of IOs based on the estimation
144 of future service time based on the his‐
145 tory of previous I/O submitted to each
146 path.
147 The default is: service-time 0
149 path_grouping_policy
151 The default path grouping policy to apply to unspeci‐
152 fied multipaths. Possible values are:
153 failover One path per priority group.
155 multibus All paths in one priority group.
157 group_by_serial
159 One priority group per serial number.
160 group_by_prio
162 One priority group per priority value.
163 Priorities are determined by callout pro‐
164 grams specified as a global, per-con‐
165 troller or per-multipath option in the
166 configuration file.
167 group_by_node_name
169 One priority group per target node name.
170 Target node names are fetched in
171 /sys/class/fc_transport/target*/node_name.
172 The default is: failover
174 uid_attrs Setting this option activates merging uevents by WWID,
176 which may improve uevent processing effiency. More‐
177 over, it's an alternative method to configure the udev
178 properties to use for determining unique path identi‐
179 fiers (WWIDs).
180 The value of this option is a space separated list of
182 records like "type:ATTR", where type is matched
183 against the beginning of the device node name (e.g.
184 sd:ATTR matches sda), and ATTR is the name of the udev
185 property to use for matching devices.
186 If this option is configured and matches the device
188 node name of a device, it overrides any other config‐
189 ured methods for determining the WWID for this de‐
190 vice.
191 The default is: <unset>. To enable uevent merging, set
193 it e.g. to "sd:ID_SERIAL dasd:ID_UID nvme:ID_WWN".
194 uid_attribute The udev attribute providing a unique path identifier
196 (WWID). If uid_attribute is set to the empty string,
197 WWID determination is done using the sysfs method
198 rather then using udev (not recommended in production;
199 see WWID generation below).
200 The default is: ID_SERIAL, for SCSI devices
202 The default is: ID_UID, for DASD devices
204 The default is: ID_WWN, for NVMe devices
206 getuid_callout (Superseded by uid_attribute) The default program and
208 args to callout to obtain a unique path identifier.
209 Should be specified with an absolute path.
210 The default is: <unset>
212 prio The name of the path priority routine. The specified
214 routine should return a numeric value specifying the
215 relative priority of this path. Higher number have a
216 higher priority. "none" is a valid value. Currently
217 the following path priority routines are implemented:
218 const Return a constant priority of 1.
220 sysfs Use the sysfs attributes access_state and
222 preferred_path to generate the path prior‐
223 ity. This prioritizer accepts the optional
224 prio_arg exclusive_pref_bit.
225 emc (Hardware-dependent) Generate the path
227 priority for DGC class arrays as CLARiiON
228 CX/AX and EMC VNX and Unity families.
229 alua (Hardware-dependent) Generate the path
231 priority based on the SCSI-3 ALUA set‐
232 tings. This prioritizer accepts the op‐
233 tional prio_arg exclusive_pref_bit.
234 ontap (Hardware-dependent) Generate the path
236 priority for NetApp ONTAP class and OEM
237 arrays as IBM NSeries.
238 rdac (Hardware-dependent) Generate the path
240 priority for LSI/Engenio/NetApp RDAC class
241 as NetApp SANtricity E/EF Series, and OEM
242 arrays from IBM DELL SGI STK and SUN.
243 hp_sw (Hardware-dependent) Generate the path
245 priority for HP/COMPAQ/DEC HSG80 and
246 MSA/HSV arrays with Active/Standby mode
247 exclusively.
248 hds (Hardware-dependent) Generate the path
250 priority for Hitachi AMS families of ar‐
251 rays other than AMS 2000.
252 random Generate a random priority between 1 and
254 10.
255 weightedpath
257 Generate the path priority based on the
258 regular expression and the priority pro‐
259 vided as argument. Requires prio_args key‐
260 word.
261 path_latency
263 Generate the path priority based on a la‐
264 tency algorithm. Requires prio_args key‐
265 word.
266 ana (Hardware-dependent) Generate the path
268 priority based on the NVMe ANA settings.
269 datacore (Hardware-dependent) Generate the path
271 priority for some DataCore storage arrays.
272 Requires prio_args keyword.
273 iet (iSCSI only) Generate path priority for
275 iSCSI targets based on IP address. Re‐
276 quires prio_args keyword.
277 The default depends on the detect_prio setting: If de‐
279 tect_prio is yes (default), the default priority algo‐
280 rithm is sysfs (except for NetAPP E-Series, where it
281 is alua). If detect_prio is no, the default priority
282 algorithm is const.
283 prio_args Arguments to pass to to the prio function. This only
285 applies to certain prioritizers:
286 weighted Needs a value of the form "<hbtl|dev‐
288 name|serial|wwn> <regex1> <prio1> <regex2>
289 <prio2> ..."
290 hbtl Regex can be of SCSI H:B:T:L for‐
292 mat. For example: 1:0:.:. ,
293 *:0:0:.
294 devname Regex can be of device name for‐
296 mat. For example: sda , sd.e
297 serial Regex can be of serial number for‐
299 mat. For example: .*J1FR.*324 .
300 The serial can be looked up
301 through sysfs or by running multi‐
302 pathd show paths format "%z". For
303 example: 0395J1FR904324
304 wwn Regex can be of the form
306 "host_wwnn:host_wwpn:tar‐
307 get_wwnn:target_wwpn" these values
308 can be looked up through sysfs or
309 by running multipathd show paths
310 format "%N:%R:%n:%r". For example:
311 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.*
312 , .*:.*:iqn.2009-10.com.red‐
313 hat.msp.lab.ask-06:.*
314 path_latency
316 Needs a value of the form "io_num=<20>
317 base_num=<10>"
318 io_num The number of read IOs sent to the
320 current path continuously, used to
321 calculate the average path la‐
322 tency. Valid Values: Integer, [2,
323 200].
324 base_num
326 The base number value of logarith‐
327 mic scale, used to partition dif‐
328 ferent priority ranks. Valid Val‐
329 ues: Integer, [2, 10]. And Max av‐
330 erage latency value is 100s, min
331 average latency value is 1us. For
332 example: If base_num=10, the paths
333 will be grouped in priority groups
334 with path latency <=1us, (1us,
335 10us], (10us, 100us], (100us,
336 1ms], (1ms, 10ms], (10ms, 100ms],
337 (100ms, 1s], (1s, 10s], (10s,
338 100s], >100s.
339 alua If exclusive_pref_bit is set, paths with
341 the preferred path bit set will always be
342 in their own path group.
343 sysfs If exclusive_pref_bit is set, paths with
345 the preferred path bit set will always be
346 in their own path group.
347 datacore
349 preferredsds
351 (Mandatory) The preferred "SDS
352 name".
353 timeout (Optional) The timeout for the IN‐
355 QUIRY, in ms.
356 iet
358 preferredip=...
360 (Mandatory) Th preferred IP ad‐
361 dress, in dotted decimal notation,
362 for iSCSI targets.
363 The default is: <unset>
365 features Specify any device-mapper features to be used. Syntax
367 is num list where num is the number, between 0 and 8,
368 of features in list. Possible values for the feature
369 list are:
370 queue_if_no_path
372 (Deprecated, superseded by no_path_retry)
373 Queue I/O if no path is active. Identical
374 to the no_path_retry with queue value. If
375 both this feature and no_path_retry are
376 set, the latter value takes precedence.
377 See KNOWN ISSUES.
378 pg_init_retries <times>
380 (Since kernel 2.6.24) Number of times to
381 retry pg_init, it must be between 1 and
382 50.
383 pg_init_delay_msecs <msecs>
385 (Since kernel 2.6.38) Number of msecs be‐
386 fore pg_init retry, it must be between 0
387 and 60000.
388 queue_mode <mode>
390 (Since kernel 4.8) Select the the queueing
391 mode per multipath device. <mode> can be
392 bio, rq or mq, which corresponds to bio-
393 based, request-based, and block-multiqueue
394 (blk-mq) request-based, respectively. The
395 default depends on the kernel parameter
396 dm_mod.use_blk_mq. It is mq if the latter
397 is set, and rq otherwise.
398 The default is: <unset>
400 path_checker The default method used to determine the path's state.
402 The synchronous checkers (all except tur and directio)
403 will cause multipathd to pause most activity, waiting
404 up to checker_timeout seconds for the path to respond.
405 The asynchronous checkers (tur and directio) will not
406 pause multipathd. Instead, multipathd will check for a
407 response once per second, until checker_timeout sec‐
408 onds have elapsed. Possible values are:
409 readsector0 (Deprecated) Read the first sector of the
411 device. This checker is being deprecated,
412 please use tur instead.
413 tur Issue a TEST UNIT READY command to the de‐
415 vice.
416 emc_clariion
418 (Hardware-dependent) Query the DGC/EMC
419 specific EVPD page 0xC0 to determine the
420 path state for CLARiiON CX/AX and EMC VNX
421 and Unity arrays families.
422 hp_sw (Hardware-dependent) Check the path state
424 for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
425 with Active/Standby mode exclusively.
426 rdac (Hardware-dependent) Check the path state
428 for LSI/Engenio/NetApp RDAC class as Ne‐
429 tApp SANtricity E/EF Series, and OEM ar‐
430 rays from IBM DELL SGI STK and SUN.
431 directio Read the first sector with direct I/O.
433 This checker could cause spurious path
434 failures under high load. Increasing
435 checker_timeout can help with this.
436 cciss_tur (Hardware-dependent) Check the path state
438 for HP/COMPAQ Smart Array(CCISS) con‐
439 trollers.
440 none Do not check the device, fallback to use
442 the values retrieved from sysfs
443 The default is: tur
445 alias_prefix The user_friendly_names prefix.
447 The default is: mpath
449 failback Tell multipathd how to manage path group failback. To
451 select immediate or a value, it's mandatory that the
452 device has support for a working prioritizer.
453 immediate Immediately failback to the highest prior‐
455 ity pathgroup that contains active paths.
456 manual Do not perform automatic failback.
458 followover Used to deal with multiple computers ac‐
460 cessing the same Active/Passive storage
461 devices. Only perform automatic failback
462 when the first path of a pathgroup becomes
463 active. This keeps a cluster node from au‐
464 tomatically failing back when another node
465 requested the failover.
466 values > 0 Deferred failback (time to defer in sec‐
468 onds).
469 The default is: manual
471 rr_min_io Number of I/O requests to route to a path before
473 switching to the next in the same path group. This is
474 only for Block I/O(BIO) based multipath and only apply
475 to round-robin path_selector.
476 The default is: 1000
478 rr_min_io_rq Number of I/O requests to route to a path before
480 switching to the next in the same path group. This is
481 only for Request based multipath and only apply to
482 round-robin path_selector.
483 The default is: 1
485 max_fds Specify the maximum number of file descriptors that
487 can be opened by multipath and multipathd. This is
488 equivalent to ulimit -n. A value of max will set this
489 to the system limit from /proc/sys/fs/nr_open. If this
490 is not set, the maximum number of open fds is taken
491 from the calling process. It is usually 1024. To be
492 safe, this should be set to the maximum number of
493 paths plus 32, if that number is greated than 1024.
494 The default is: max
496 rr_weight If set to priorities the multipath configurator will
498 assign path weights as "path prio * rr_min_io". Possi‐
499 ble values are priorities or uniform . Only apply to
500 round-robin path_selector.
501 The default is: uniform
503 no_path_retry Specify what to do when all paths are down. Possible
505 values are:
506 value > 0 Number of retries until disable I/O queue‐
508 ing.
509 fail For immediate failure (no I/O queueing).
511 queue For never stop I/O queueing, similar to
513 queue_if_no_path. See KNOWN ISSUES.
514 The default is: fail
516 queue_without_daemon
518 If set to no , when multipathd stops, queueing will be
519 turned off for all devices. This is useful for de‐
520 vices that set no_path_retry. If a machine is shut
521 down while all paths to a device are down, it is pos‐
522 sible to hang waiting for I/O to return from the de‐
523 vice after multipathd has been stopped. Without multi‐
524 pathd running, access to the paths cannot be restored,
525 and the kernel cannot be told to stop queueing I/O.
526 Setting queue_without_daemon to no , avoids this prob‐
527 lem.
528 The default is: no
530 checker_timeout Specify the timeout to use for path checkers and pri‐
532 oritizers, in seconds. Only prioritizers that issue
533 scsi commands use checker_timeout. If a path does not
534 respond to the checker command after checker_timeout
535 seconds have elapsed, it is considered down.
536 The default is: in /sys/block/<dev>/device/timeout
538 allow_usb_devices
540 If set to no , all USB devices will be skipped during
541 path discovery. If you intend to use multipath on USB
542 attached devices, set this to yes.
543 The default is: no
545 flush_on_last_del
547 If set to yes , multipathd will disable queueing when
548 the last path to a device has been deleted.
549 The default is: no
551 user_friendly_names
553 If set to yes , using the bindings file /etc/multi‐
554 path/bindings to assign a persistent and unique alias
555 to the multipath, in the form of mpath<n>. If set to
556 no use the WWID as the alias. In either case this be
557 will be overridden by any specific aliases in the mul‐
558 tipaths section.
559 The default is: no
561 fast_io_fail_tmo Specify the number of seconds the SCSI layer will wait
563 after a problem has been detected on a FC remote port
564 before failing I/O to devices on that remote port.
565 This should be smaller than dev_loss_tmo. Setting this
566 to off will disable the timeout.
567 The default is: 5
569 dev_loss_tmo Specify the number of seconds the SCSI layer will wait
571 after a problem has been detected on a FC remote port
572 before removing it from the system. This can be set to
573 "infinity" which sets it to the max value of
574 2147483647 seconds, or 68 years. It will be automati‐
575 cally adjusted to the overall retry interval
576 no_path_retry * polling_interval if a number of re‐
577 tries is given with no_path_retry and the overall
578 retry interval is longer than the specified
579 dev_loss_tmo value. The Linux kernel will cap this
580 value to 600 if fast_io_fail_tmo is not set. See KNOWN
581 ISSUES.
582 The default is: 600
584 eh_deadline Specify the maximum number of seconds the SCSI layer
586 will spend doing error handling when scsi devices
587 fail. After this timeout the scsi layer will perform a
588 full HBA reset. Setting this may be necessary in cases
589 where the rport is never lost, so fast_io_fail_tmo and
590 dev_loss_tmo will never trigger, but (frequently do to
591 load) scsi commands still hang. Note: when the scsi
592 error handler performs the HBA reset, all target paths
593 on that HBA will be affected. eh_deadline should only
594 be set in cases where all targets on the affected HBAs
595 are multipathed.
596 The default is: <unset>
598 bindings_file The full pathname of the binding file to be used when
600 the user_friendly_names option is set.
601 The default is: /etc/multipath/bindings
603 wwids_file The full pathname of the WWIDs file, which is used by
605 multipath to keep track of the WWIDs for LUNs it has
606 created multipath devices on in the past.
607 The default is: /etc/multipath/wwids
609 prkeys_file The full pathname of the prkeys file, which is used by
611 multipathd to keep track of the persistent reservation
612 key used for a specific WWID, when reservation_key is
613 set to file.
614 The default is: /etc/multipath/prkeys
616 log_checker_err If set to once , multipathd logs the first path
618 checker error at logging level 2. Any later errors are
619 logged at level 3 until the device is restored. If set
620 to always , multipathd always logs the path checker
621 error at logging level 2.
622 The default is: always
624 reservation_key This is the service action reservation key used by
626 mpathpersist. It must be set for all multipath devices
627 using persistent reservations, and it must be the same
628 as the RESERVATION KEY field of the PERSISTENT RESERVE
629 OUT parameter list which contains an 8-byte value pro‐
630 vided by the application client to the device server
631 to identify the I_T nexus. If the --param-aptpl option
632 is used when registering the key with mpathpersist,
633 :aptpl must be appended to the end of the reservation
634 key.
635 Alternatively, this can be set to file, which will
637 store the RESERVATION KEY registered by mpathpersist
638 in the prkeys_file. multipathd will then use this key
639 to register additional paths as they appear. When the
640 registration is removed, the RESERVATION KEY is re‐
641 moved from the prkeys_file. The prkeys file will auto‐
642 matically keep track of whether the key was registered
643 with --param-aptpl.
644 The default is: <unset>
646 all_tg_pt Set the 'all targets ports' flag when registering keys
648 with mpathpersist. Some arrays automatically set and
649 clear registration keys on all target ports from a
650 host, instead of per target port per host. The
651 ALL_TG_PT flag must be set to successfully use mpath‐
652 persist on these arrays. Setting this option is iden‐
653 tical to calling mpathpersist with --param-alltgpt
654 The default is: no
656 retain_attached_hw_handler
658 (Obsolete for kernels >= 4.3) If set to yes and the
659 SCSI layer has already attached a hardware_handler to
660 the device, multipath will not force the device to use
661 the hardware_handler specified by mutipath.conf. If
662 the SCSI layer has not attached a hardware handler,
663 multipath will continue to use its configured hardware
664 handler.
665 The default is: yes
667 Important Note: Linux kernel 4.3 or newer always be‐
669 haves as if "retain_attached_hw_handler yes" was set.
670 detect_prio If set to yes , multipath will try to detect if the
672 device supports SCSI-3 ALUA. If so, the device will
673 automatically use the sysfs prioritizer if the re‐
674 quired sysf attributes access_state and preferred_path
675 are supported, or the alua prioritizer if not. If set
676 to no , the prioritizer will be selected as usual.
677 The default is: yes
679 detect_checker if set to yes , multipath will try to detect if the
681 device supports SCSI-3 ALUA. If so, the device will
682 automatically use the tur checker. If set to no , the
683 checker will be selected as usual.
684 The default is: yes
686 force_sync If set to yes , multipathd will call the path checkers
688 in sync mode only. This means that only one checker
689 will run at a time. This is useful in the case where
690 many multipathd checkers running in parallel causes
691 significant CPU pressure.
692 The default is: no
694 strict_timing If set to yes , multipathd will start a new path
696 checker loop after exactly one second, so that each
697 path check will occur at exactly polling_interval sec‐
698 onds. On busy systems path checks might take longer
699 than one second; here the missing ticks will be ac‐
700 counted for on the next round. A warning will be
701 printed if path checks take longer than polling_inter‐
702 val seconds.
703 The default is: no
705 deferred_remove If set to yes , multipathd will do a deferred remove
707 instead of a regular remove when the last path device
708 has been deleted. This means that if the multipath
709 device is still in use, it will be freed when the last
710 user closes it. If path is added to the multipath de‐
711 vice before the last user closes it, the deferred re‐
712 move will be canceled.
713 The default is: no
715 partition_delimiter
717 This parameter controls how multipath chooses the
718 names of partition devices of multipath maps if a mul‐
719 tipath map is renamed (e.g. if a map alias is added or
720 changed). If this parameter is set to a string other
721 than "/UNSET/" (even the empty string), multipath in‐
722 serts that string between device name and partition
723 number to construct the partition device name. Other‐
724 wise (i.e. if this parameter is unset or has the value
725 "/UNSET/"), the behavior depends on the map name: if
726 it ends in a digit, a "p" is inserted between name and
727 partition number; otherwise, the partition number is
728 simply appended. Distributions may use a non-null de‐
729 fault value for this option; in this case, the user
730 must set it to "/UNSET/" to obtain the original <un‐
731 set> behavior. Use multipath -T to check the current
732 settings.
733 The default is: <unset>
735 config_dir If set to anything other than "", multipath will
737 search this directory alphabetically for file ending
738 in ".conf" and it will read configuration information
739 from them, just as if it was in /etc/multipath.conf.
740 config_dir must either be "" or a fully qualified di‐
741 rectory name.
742 The default is: /etc/multipath/conf.d/
744 san_path_err_threshold
746 If set to a value greater than 0, multipathd will
747 watch paths and check how many times a path has been
748 failed due to errors.If the number of failures on a
749 particular path is greater then the
750 san_path_err_threshold, then the path will not rein‐
751 state till san_path_err_recovery_time. These path
752 failures should occur within a san_path_err_for‐
753 get_rate checks, if not we will consider the path is
754 good enough to reinstantate. See "Shaky paths detec‐
755 tion" below.
756 The default is: no
758 san_path_err_forget_rate
760 If set to a value greater than 0, multipathd will
761 check whether the path failures has exceeded the
762 san_path_err_threshold within this many checks i.e
763 san_path_err_forget_rate . If so we will not rein‐
764 stante the path till san_path_err_recovery_time. See
765 "Shaky paths detection" below.
766 The default is: no
768 san_path_err_recovery_time
770 If set to a value greater than 0, multipathd will make
771 sure that when path failures has exceeded the
772 san_path_err_threshold within san_path_err_forget_rate
773 then the path will be placed in failed state for
774 san_path_err_recovery_time duration.Once
775 san_path_err_recovery_time has timeout we will rein‐
776 stante the failed path . san_path_err_recovery_time
777 value should be in secs. See "Shaky paths detection"
778 below.
779 The default is: no
781 marginal_path_double_failed_time
783 One of the four parameters of supporting path check
784 based on accounting IO error such as intermittent er‐
785 ror. When a path failed event occurs twice in mar‐
786 ginal_path_double_failed_time seconds due to an IO er‐
787 ror and all the other three parameters are set, multi‐
788 pathd will fail the path and enqueue this path into a
789 queue of which members are sent a couple of continuous
790 direct reading asynchronous IOs at a fixed sample rate
791 of 10HZ to start IO error accounting process. See
792 "Shaky paths detection" below.
793 The default is: no
795 marginal_path_err_sample_time
797 One of the four parameters of supporting path check
798 based on accounting IO error such as intermittent er‐
799 ror. If it is set to a value no less than 120, when a
800 path fail event occurs twice in marginal_path_dou‐
801 ble_failed_time second due to an IO error, multipathd
802 will fail the path and enqueue this path into a queue
803 of which members are sent a couple of continuous di‐
804 rect reading asynchronous IOs at a fixed sample rate
805 of 10HZ to start the IO accounting process for the
806 path will last for marginal_path_err_sample_time. If
807 the rate of IO error on a particular path is greater
808 than the marginal_path_err_rate_threshold, then the
809 path will not reinstate for mar‐
810 ginal_path_err_recheck_gap_time seconds unless there
811 is only one active path. After mar‐
812 ginal_path_err_recheck_gap_time expires, the path will
813 be requeueed for rechecking. If checking result is
814 good enough, the path will be reinstated. See "Shaky
815 paths detection" below.
816 The default is: no
818 marginal_path_err_rate_threshold
820 The error rate threshold as a permillage (1/1000). One
821 of the four parameters of supporting path check based
822 on accounting IO error such as intermittent error. Re‐
823 fer to marginal_path_err_sample_time. If the rate of
824 IO errors on a particular path is greater than this
825 parameter, then the path will not reinstate for mar‐
826 ginal_path_err_recheck_gap_time seconds unless there
827 is only one active path. See "Shaky paths detection"
828 below.
829 The default is: no
831 marginal_path_err_recheck_gap_time
833 One of the four parameters of supporting path check
834 based on accounting IO error such as intermittent er‐
835 ror. Refer to marginal_path_err_sample_time. If this
836 parameter is set to a positive value, the failed path
837 of which the IO error rate is larger than mar‐
838 ginal_path_err_rate_threshold will be kept in failed
839 state for marginal_path_err_recheck_gap_time seconds.
840 When marginal_path_err_recheck_gap_time seconds ex‐
841 pires, the path will be requeueed for checking. If
842 checking result is good enough, the path will be rein‐
843 stated, or else it will keep failed. See "Shaky paths
844 detection" below.
845 The default is: no
847 delay_watch_checks
849 This option is deprecated, and mapped to
850 san_path_err_forget_rate. If this is set to a value
851 greater than 0 and no san_path_err options are set,
852 san_path_err_forget_rate will be set to the value of
853 delay_watch_checks and san_path_err_threshold will be
854 set to 1. See the san_path_err_forget_rate and
855 san_path_err_threshold options, and "Shaky paths de‐
856 tection" below for more information.
857 The default is: no
859 delay_wait_checks
861 This option is deprecated, and mapped to
862 san_path_err_recovery_time. If this is set to a value
863 greater than 0 and no san_path_err options are set,
864 san_path_err_recovery_time will be set to the value of
865 delay_wait_checks times max_polling_interval. This
866 will give approximately the same wait time as de‐
867 lay_wait_checks previously did. Also,
868 san_path_err_threshold will be set to 1. See the
869 san_path_err_recovery_time and san_path_err_threshold
870 options, and "Shaky paths detection" below for more
871 information.
872 The default is: no
874 marginal_pathgroups
876 If set to no, the delay_*_checks, marginal_path_*, and
877 san_path_err_* options will keep marginal, or "shaky",
878 paths from being reinstated until they have been moni‐
879 tored for some time. This can cause situations where
880 all non-marginal paths are down, and no paths are us‐
881 able until multipathd detects this and reinstates a
882 marginal path. If the multipath device is not config‐
883 ured to queue IO in this case, it can cause IO errors
884 to occur, even though there are marginal paths avail‐
885 able. However, if this option is set to yes, when one
886 of the marginal path detecting methods determines that
887 a path is marginal, it will be reinstated and placed
888 in a seperate pathgroup that will only be used after
889 all the non-marginal pathgroups have been tried first.
890 This prevents the possibility of IO errors occuring
891 while marginal paths are still usable. After the path
892 has been monitored for the configured time, and is de‐
893 clared healthy, it will be returned to its normal
894 pathgroup. See "Shaky paths detection" below for more
895 information.
896 The default is: no
898 find_multipaths This option controls whether multipath and multipathd
900 try to create multipath maps over non-blacklisted de‐
901 vices they encounter. This matters a) when a device is
902 encountered by multipath -u during udev rule process‐
903 ing (a device is blocked from further processing by
904 higher layers - such as LVM - if and only if it´s con‐
905 sidered a valid multipath device path), and b) when
906 multipathd detects a new device. The following values
907 are possible:
908 strict Both multipath and multipathd treat only
910 such devices as multipath devices which have
911 been part of a multipath map previously, and
912 which are therefore listed in the
913 wwids_file. Users can manually set up multi‐
914 path maps using the multipathd add map com‐
915 mand. Once set up manually, the map is re‐
916 membered in the wwids file and will be set
917 up automatically in the future.
918 no Multipath behaves like strict. Multipathd
920 behaves like greedy.
921 yes Both multipathd and multipath treat a device
923 as multipath device if the conditions for
924 strict are met, or if at least two non-
925 blacklisted paths with the same WWID have
926 been detected.
927 greedy Both multipathd and multipath treat every
929 non-blacklisted device as multipath device
930 path.
931 smart This differs from find_multipaths yes only
933 in the way it treats new devices for which
934 only one path has been detected yet. When
935 such a device is first encounted in udev
936 rules, it is treated as a multipath device.
937 multipathd waits whether additional paths
938 with the same WWID appears. If that happens,
939 it sets up a multipath map. If it doesn´t
940 happen until a timeout expires, or if set‐
941 ting up the map fails, a new uevent is trig‐
942 gered for the device; at second encounter in
943 the udev rules, the device will be treated
944 as non-multipath and passed on to upper lay‐
945 ers. Note: this may cause delays during de‐
946 vice detection if there are single-path de‐
947 vices which aren´t blacklisted.
948 The default is: strict
950 find_multipaths_timeout
952 Timeout, in seconds, to wait for additional paths af‐
953 ter detecting the first one, if find_multipaths
954 "smart" (see above) is set. If the value is positive,
955 this timeout is used for all unknown, non-blacklisted
956 devices encountered. If the value is negative (recom‐
957 mended), it's only applied to "known" devices that
958 have an entry in multipath's hardware table, either in
959 the built-in table or in a device section; other ("un‐
960 known") devices will use a timeout of only 1 second to
961 avoid booting delays. The value 0 means "use the
962 built-in default". If find_multipath has a value other
963 than smart, this option has no effect.
964 The default is: -10 (10s for known and 1s for unknown
966 hardware)
967 uxsock_timeout CLI receive timeout in milliseconds. For larger sys‐
969 tems CLI commands might timeout before the multipathd
970 lock is released and the CLI command can be processed.
971 This will result in errors like "timeout receiving
972 packet" to be returned from CLI commands. In these
973 cases it is recommended to increase the CLI timeout to
974 avoid those issues.
975 The default is: 4000
977 retrigger_tries Sets the number of times multipathd will try to re‐
979 trigger a uevent to get the WWID.
980 The default is: 3
982 retrigger_delay Sets the amount of time, in seconds, to wait between
984 retriggers.
985 The default is: 10
987 missing_uev_wait_timeout
989 Controls how many seconds multipathd will wait, after
990 a new multipath device is created, to receive a change
991 event from udev for the device, before automatically
992 enabling device reloads. Usually multipathd will delay
993 reloads on a device until it receives a change uevent
994 from the initial table load.
995 The default is: 30
997 skip_kpartx If set to yes , kpartx will not automatically create
999 partitions on the device.
1000 The default is: no
1002 disable_changed_wwids
1004 This option is deprecated and ignored. If the WWID of
1005 a path suddenly changes, multipathd handles it as if
1006 it was removed and then added again.
1007 remove_retries This sets how may times multipath will retry removing
1009 a device that is in-use. Between each attempt, multi‐
1010 path will sleep 1 second.
1011 The default is: 0
1013 max_sectors_kb Sets the max_sectors_kb device parameter on all path
1015 devices and the multipath device to the specified
1016 value.
1017 The default is: in /sys/block/<dev>/queue/max_sec‐
1019 tors_kb
1020 ghost_delay Sets the number of seconds that multipath will wait
1022 after creating a device with only ghost paths before
1023 marking it ready for use in systemd. This gives the
1024 active paths time to appear before the multipath runs
1025 the hardware handler to switch the ghost paths to ac‐
1026 tive ones. Setting this to 0 or no makes multipath im‐
1027 mediately mark a device with only ghost paths as
1028 ready.
1029 The default is: no
1031 enable_foreign Enables or disables foreign libraries (see section
1033 FOREIGN MULTIPATH SUPPORT below). The value is a regu‐
1034 lar expression; foreign libraries are loaded if their
1035 name (e.g. "nvme") matches the expression. By default,
1036 no foreign libraries are enabled. Set this to "nvme"
1037 to enable NVMe native multipath support, or ".*" to
1038 enable all foreign libraries.
1039 The default is: "NONE"
1041 recheck_wwid If set to yes, when a failed path is restored, its
1043 wwid is rechecked. If the wwid has changed, the path
1044 is removed from the current multipath device, and re-
1045 added as a new path. Multipathd will also recheck a
1046 path's wwid if it is manually re-added. This option
1047 only works for SCSI devices that are configured to use
1048 the default uid_attribute, ID_SERIAL, or sysfs for
1049 getting their wwid.
1050 The default is: no
1052
1055 The blacklist section is used to exclude specific devices from the mul‐
1056 tipath topology. It is most commonly used to exclude local disks or
1057 non-disk devices (such as LUNs for the storage array controller) from
1058 being handled by multipath-tools.
1059 In the blacklist and blacklist_exceptions sections, starting a quoted
1061 value with an exclamation mark "!" will invert the matching of the rest
1062 of the regular expression. For instance, "!^sd[a-z]" will match all
1063 values that do not start with "sd[a-z]". The exclamation mark can be
1064 escaped "\!" to match a literal ! at the start of a regular expression.
1065 Note: The exclamation mark must be inside quotes, otherwise it will be
1066 treated as starting a comment.
1067 The blacklist_exceptions section is used to revert the actions of the
1069 blacklist section. This allows one to selectively include ("whitelist")
1070 devices which would normally be excluded via the blacklist section. A
1071 common usage is to blacklist "everything" using a catch-all regular ex‐
1072 pression, and create specific blacklist_exceptions entries for those
1073 devices that should be handled by multipath-tools.
1074 The following keywords are recognized in both sections. The defaults
1076 are empty unless explicitly stated.
1077 devnode Regular expression matching the device nodes to be ex‐
1079 cluded/included.
1080 The default blacklist consists of the regular expres‐
1082 sion "!^(sd[a-z]|dasd[a-z]|nvme[0-9])". This causes
1083 all device types other than scsi, dasd, and nvme to be
1084 excluded from multipath handling by default.
1085 wwid Regular expression for the World Wide Identifier of a
1087 device to be excluded/included.
1088 device Subsection for the device description. This subsection
1090 recognizes the vendor and product keywords. Both are
1091 regular expressions. For a full description of these
1092 keywords please see the devices section description.
1093 property Regular expression for an udev property. All devices
1095 that have matching udev properties will be ex‐
1096 cluded/included. The handling of the property keyword
1097 is special, because if a property blacklist_exception
1098 is set, devices must have at least one whitelisted
1099 udev property; otherwise they're treated as black‐
1100 listed, and the message "blacklisted, udev property
1101 missing" is displayed in the logs. For example, set‐
1102 ting the property blacklist_exception to
1103 (SCSI_IDENT_|ID_WWN), will cause well-behaved SCSI de‐
1104 vices and devices that provide a WWN (World Wide Num‐
1105 ber) to be included, and all others to be excluded.
1106 This works to exclude most non-multipathable devices.
1107 Note: The behavior of this option has changed in mul‐
1109 tipath-tools 0.8.2 compared to previous versions.
1110 Blacklisting by missing properties is only applied to
1111 devices which do have the property specified by
1112 uid_attribute (e.g. ID_SERIAL) set. Previously, it was
1113 applied to every device, possibly causing devices to
1114 be blacklisted because of temporary I/O error condi‐
1115 tions.
1116 protocol Regular expression for the protocol of a device to be
1118 excluded/included.
1119 The protocol strings that multipath recognizes are
1121 scsi:fcp, scsi:spi, scsi:ssa, scsi:sbp, scsi:srp,
1122 scsi:iscsi, scsi:sas, scsi:adt, scsi:ata, scsi:unspec,
1123 ccw, cciss, nvme, and undef. The protocol that a path
1124 is using can be viewed by running multipathd show
1125 paths format "%d %P"
1126 For every device, these 5 blacklist criteria are evaluated in the the
1128 order "property, devnode, device, protocol, wwid". If a device turns
1129 out to be blacklisted by any criterion, it's excluded from handling by
1130 multipathd, and the later criteria aren't evaluated any more. For each
1131 criterion, the whitelist takes precedence over the blacklist if a de‐
1132 vice matches both.
1133 Note: Besides the blacklist and whitelist, other configuration options
1135 such as find_multipaths have an impact on whether or not a given device
1136 is handled by multipath-tools.
1137
1139 The multipaths section allows setting attributes of multipath maps. The
1140 attributes that are set via the multipaths section (see list below)
1141 take precedence over all other configuration settings, including those
1142 from the overrides section.
1143 The only recognized attribute for the multipaths section is the multi‐
1145 path subsection. If there are multiple multipath subsections matching a
1146 given WWID, the contents of these sections are merged, and settings
1147 from later entries take precedence.
1148 The multipath subsection recognizes the following attributes:
1150 wwid (Mandatory) World Wide Identifier. Detected multipath
1152 maps are matched agains this attribute. Note that,
1153 unlike the wwid attribute in the blacklist section,
1154 this is not a regular expression or a substring; WWIDs
1155 must match exactly inside the multipaths section.
1156 alias Symbolic name for the multipath map. This takes prece‐
1158 dence over a an entry for the same WWID in the bind‐
1159 ings_file.
1160 The following attributes are optional; if not set the default values
1162 are taken from the overrides, devices, or defaults section:
1163 path_grouping_policy
1165 path_selector
1166 prio
1167 prio_args
1168 failback
1169 rr_weight
1170 no_path_retry
1171 rr_min_io
1172 rr_min_io_rq
1173 flush_on_last_del
1174 features
1175 reservation_key
1176 user_friendly_names
1177 deferred_remove
1178 san_path_err_threshold
1179 san_path_err_forget_rate
1180 san_path_err_recovery_time
1181 marginal_path_err_sample_time
1182 marginal_path_err_rate_threshold
1183 marginal_path_err_recheck_gap_time
1184 marginal_path_double_failed_time
1185 delay_watch_checks
1186 delay_wait_checks
1187 skip_kpartx
1188 max_sectors_kb
1189 ghost_delay
1190
1192 multipath-tools have a built-in device table with reasonable defaults
1193 for more than 100 known multipath-capable storage devices. The devices
1194 section can be used to override these settings. If there are multiple
1195 matches for a given device, the attributes of all matching entries are
1196 applied to it. If an attribute is specified in several matching device
1197 subsections, later entries take precedence. Thus, entries in files un‐
1198 der config_dir (in reverse alphabetical order) have the highest prece‐
1199 dence, followed by entries in multipath.conf; the built-in hardware ta‐
1200 ble has the lowest precedence. Inside a configuration file, later en‐
1201 tries have higher precedence than earlier ones.
1202 The only recognized attribute for the devices section is the device
1204 subsection. Devices detected in the system are matched against the de‐
1205 vice entries using the vendor, product, and revision fields, which are
1206 all POSIX Extended regular expressions (see regex(7)).
1207 The vendor, product, and revision fields that multipath or multipathd
1209 detect for devices in a system depend on the device type. For SCSI de‐
1210 vices, they correspond to the respective fields of the SCSI INQUIRY
1211 page. In general, the command 'multipathd show paths format "%d %s"'
1212 command can be used to see the detected properties for all devices in
1213 the system.
1214 The device subsection recognizes the following attributes:
1216 vendor (Mandatory) Regular expression to match the vendor
1218 name.
1219 product (Mandatory) Regular expression to match the product
1221 name.
1222 revision Regular expression to match the product revision. If
1224 not specified, any revision matches.
1225 product_blacklist
1227 Products with the given vendor matching this string
1228 are blacklisted. This is equivalent to a device entry
1229 in the blacklist section with the vendor attribute set
1230 to this entry's vendor, and the product attribute set
1231 to the value of product_blacklist.
1232 alias_prefix The user_friendly_names prefix to use for this device
1234 type, instead of the default "mpath".
1235 vpd_vendor The vendor specific vpd page information, using the
1237 vpd page abbreviation. The vpd page abbreviation can
1238 be found by running sg_vpd -e. multipathd will use
1239 this information to gather device specific information
1240 that can be displayed with the %g wilcard for the mul‐
1241 tipathd show maps format and multipathd show paths
1242 format commands. Currently only the hp3par vpd page is
1243 supported.
1244 hardware_handler The hardware handler to use for this device type. The
1246 following hardware handler are implemented:
1247 1 emc (Hardware-dependent) Hardware handler for
1249 DGC class arrays as CLARiiON CX/AX and EMC
1250 VNX and Unity families.
1251 1 rdac (Hardware-dependent) Hardware handler for
1253 LSI/Engenio/NetApp RDAC class as NetApp
1254 SANtricity E/EF Series, and OEM arrays
1255 from IBM DELL SGI STK and SUN.
1256 1 hp_sw (Hardware-dependent) Hardware handler for
1258 HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
1259 with Active/Standby mode exclusively.
1260 1 alua (Hardware-dependent) Hardware handler for
1262 SCSI-3 ALUA compatible arrays.
1263 1 ana (Hardware-dependent) Hardware handler for
1265 NVMe ANA compatible arrays.
1266 The default is: <unset>
1268 Important Note: Linux kernels 4.3 and newer automati‐
1270 cally attach a device handler to known devices (which
1271 includes all devices supporting SCSI-3 ALUA) and dis‐
1272 allow changing the handler afterwards. Setting hard‐
1273 ware_handler for such devices on these kernels has no
1274 effect.
1275 The following attributes are optional; if not set the default values
1277 are taken from the defaults section:
1278 path_grouping_policy
1280 uid_attribute
1281 getuid_callout
1282 path_selector
1283 path_checker
1284 prio
1285 prio_args
1286 features
1287 failback
1288 rr_weight
1289 no_path_retry
1290 rr_min_io
1291 rr_min_io_rq
1292 fast_io_fail_tmo
1293 dev_loss_tmo
1294 flush_on_last_del
1295 user_friendly_names
1296 retain_attached_hw_handler
1297 detect_prio
1298 detect_checker
1299 deferred_remove
1300 san_path_err_threshold
1301 san_path_err_forget_rate
1302 san_path_err_recovery_time
1303 marginal_path_err_sample_time
1304 marginal_path_err_rate_threshold
1305 marginal_path_err_recheck_gap_time
1306 marginal_path_double_failed_time
1307 delay_watch_checks
1308 delay_wait_checks
1309 skip_kpartx
1310 max_sectors_kb
1311 ghost_delay
1312 all_tg_pt
1313
1315 The overrides section recognizes the following optional attributes; if
1316 not set the values are taken from the devices or defaults sections:
1317 path_grouping_policy
1319 uid_attribute
1320 getuid_callout
1321 path_selector
1322 path_checker
1323 alias_prefix
1324 features
1325 prio
1326 prio_args
1327 failback
1328 rr_weight
1329 no_path_retry
1330 rr_min_io
1331 rr_min_io_rq
1332 flush_on_last_del
1333 fast_io_fail_tmo
1334 dev_loss_tmo
1335 user_friendly_names
1336 retain_attached_hw_handler
1337 detect_prio
1338 detect_checker
1339 deferred_remove
1340 san_path_err_threshold
1341 san_path_err_forget_rate
1342 san_path_err_recovery_time
1343 marginal_path_err_sample_time
1344 marginal_path_err_rate_threshold
1345 marginal_path_err_recheck_gap_time
1346 marginal_path_double_failed_time
1347 delay_watch_checks
1348 delay_wait_checks
1349 skip_kpartx
1350 max_sectors_kb
1351 ghost_delay
1352 all_tg_pt
1353
1355 Multipath uses a World Wide Identification (WWID) to determine which
1356 paths belong to the same device. Each path presenting the same WWID is
1357 assumed to point to the same device.
1358 The WWID is generated by four methods (in the order of preference):
1360 uid_attrs The WWID is derived from udev attributes by matching
1362 the device node name; cf uid_attrs above.
1363 getuid_callout Use the specified external program; cf getuid_callout
1365 above. Care should be taken when using this method;
1366 the external program needs to be loaded from disk for
1367 execution, which might lead to deadlock situations in
1368 an all-paths-down scenario.
1369 uid_attribute Use the value of the specified udev attribute; cf
1371 uid_attribute above. This method is preferred to ge‐
1372 tuid_callout as multipath does not need to call any
1373 external programs here. However, under certain circum‐
1374 stances udev might not be able to generate the re‐
1375 quested variable.
1376 sysfs Try to determine the WWID from sysfs attributes. For
1378 SCSI devices, this means reading the Vital Product
1379 Data (VPD) page "Device Identification" (0x83).
1380 The default settings (using udev and uid_attribute configured from the
1382 built-in hardware table) should work fine in most scenarios. Users who
1383 want to enable uevent merging must set uid_attrs.
1384
1386 A common problem in SAN setups is the occurence of intermittent errors:
1387 a path is unreachable, then reachable again for a short time, disap‐
1388 pears again, and so forth. This happens typically on unstable intercon‐
1389 nects. It is undesirable to switch pathgroups unnecessarily on such
1390 frequent, unreliable events. multipathd supports three different meth‐
1391 ods for detecting this situation and dealing with it. All methods share
1392 the same basic mode of operation: If a path is found to be "shaky" or
1393 "flipping", and appears to be in healthy status, it is not reinstated
1394 (put back to use) immediately. Instead, it is placed in the "delayed"
1395 state and watched for some time, and only reinstated if the healthy
1396 state appears to be stable. If the marginal_pathgroups option is set,
1397 the path will reinstated immediately, but placed in a special pathgroup
1398 for marginal paths. Marginal pathgroups will not be used until all
1399 other pathgroups have been tried. At the time when the path would nor‐
1400 mally be reinstated, it will be returned to its normal pathgroup. The
1401 logic of determining "shaky" condition, as well as the logic when to
1402 reinstate, differs between the three methods.
1403 "delay_checks" failure tracking
1405 This method is deprecated and mapped to the "san_path_err"
1406 method. See the delay_watch_checks and delay_wait_checks op‐
1407 tions above for more information.
1408 "marginal_path" failure tracking
1411 If a second failure event (good->bad transition) occurs within
1412 marginal_path_double_failed_time seconds after a failure, high-
1413 frequency monitoring is started for the affected path: I/O is
1414 sent at a rate of 10 per second. This is done for mar‐
1415 ginal_path_err_sample_time seconds. During this period, the
1416 path is not reinstated. If the rate of errors remains below
1417 marginal_path_err_rate_threshold during the monitoring period,
1418 the path is reinstated. Otherwise, it is kept in failed state
1419 for marginal_path_err_recheck_gap_time, and after that, it is
1420 monitored again. For this method, time intervals are measured
1421 in seconds.
1422 "san_path_err" failure tracking
1424 multipathd counts path failures for each path. Once the number
1425 of failures exceeds the value given by san_path_err_threshold,
1426 the path is not reinstated for san_path_err_recovery_time sec‐
1427 onds. While counting failures, multipathd "forgets" one past
1428 failure every "san_path_err_forget_rate" ticks; thus if errors
1429 don't occur more often then once in the forget rate interval,
1430 the failure count doesn't increase and the threshold is never
1431 reached. Ticks are the time between path checks by multipathd,
1432 which is variable and controlled by the polling_interval and
1433 max_polling_interval parameters.
1434 This method is deprecated in favor of the "marginal_path" fail‐
1436 ure tracking method, and only offered for backward compatibil‐
1437 ity.
1438 See the documentation of the individual options above for details. It
1440 is strongly discouraged to use more than one of these methods for any
1441 given multipath map, because the two concurrent methods may interact in
1442 unpredictable ways. If the "marginal_path" method is active, the
1443 "san_path_err" parameters are implicitly set to 0.
1444
1446 multipath and multipathd can load "foreign" libraries to add support
1447 for other multipathing technologies besides the Linux device mapper.
1448 Currently this support is limited to printing detected information
1449 about multipath setup. In topology output, the names of foreign maps
1450 are prefixed by the foreign library name in square brackets, as in this
1451 example:
1452 # multipath -ll
1454 uuid.fedcba98-3579-4567-8765-123456789abc [nvme]:nvme4n9 NVMe,Some NVMe controller,FFFFFFFF
1455 size=167772160 features='n/a' hwhandler='ANA' wp=rw
1456 |-+- policy='n/a' prio=50 status=optimized
1457 | `- 4:38:1 nvme4c38n1 0:0 n/a optimized live
1458 `-+- policy='n/a' prio=50 status=optimized
1459 `- 4:39:1 nvme4c39n1 0:0 n/a optimized live
1460 The "nvme" foreign library provides support for NVMe native multi‐
1462 pathing in the kernel. It is part of the standard multipath package.
1463
1465 The usage of queue_if_no_path option can lead to D state processes be‐
1466 ing hung and not killable in situations where all the paths to the LUN
1467 go offline. It is advisable to use the no_path_retry option instead.
1468 The use of queue_if_no_path or no_path_retry might lead to a deadlock
1470 if the dev_loss_tmo setting results in a device being removed while I/O
1471 is still queued. The multipath daemon will update the dev_loss_tmo set‐
1472 ting accordingly to avoid this deadlock. Hence if both values are spec‐
1473 ified the order of precedence is no_path_retry, queue_if_no_path,
1474 dev_loss_tmo.
1475
1477 udev(8), dmsetup(8), multipath(8), multipathd(8).
1478
1480 multipath-tools was developed by Christophe Varoqui, <christophe.varo‐
1481 qui@opensvc.com> and others.
1482Linux 2018-05-21 MULTIPATH.CONF(5)