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 This option is not supported any more. The value is
114 ignored.
115 path_selector The default path selector algorithm to use; they are
117 offered by the kernel multipath target:
118 round-robin 0
120 Loop through every path in the path group,
121 sending the same amount of I/O to each.
122 Some aspects of behavior can be controlled
123 with the attributes: rr_min_io,
124 rr_min_io_rq and rr_weight.
125 queue-length 0
127 (Since 2.6.31 kernel) Choose the path for
128 the next bunch of I/O based on the amount
129 of outstanding I/O to the path.
130 service-time 0
132 (Since 2.6.31 kernel) Choose the path for
133 the next bunch of I/O based on the amount
134 of outstanding I/O to the path and its
135 relative throughput.
136 historical-service-time 0
138 (Since 5.8 kernel) Choose the path for the
139 next bunch of I/O based on the estimation
140 of future service time based on the his‐
141 tory of previous I/O submitted to each
142 path.
143 io-affinity 0
145 (Since 5.11 kernel) Choose the path for
146 the next bunch of I/O based on a CPU to
147 path mapping the user passes in and what
148 CPU we are executing on.
149 The default is: service-time 0
151 path_grouping_policy
153 The default path grouping policy to apply to unspeci‐
154 fied multipaths. Possible values are:
155 failover One path per priority group.
157 multibus All paths in one priority group.
159 group_by_serial
161 One priority group per serial number.
162 group_by_prio
164 One priority group per priority value.
165 Priorities are determined by callout pro‐
166 grams specified as a global, per-con‐
167 troller or per-multipath option in the
168 configuration file.
169 group_by_node_name
171 One priority group per target node name.
172 Target node names are fetched in
173 /sys/class/fc_transport/target*/node_name.
174 The default is: failover
176 uid_attrs Setting this option activates merging uevents by WWID,
178 which may improve uevent processing efficiency. More‐
179 over, it's an alternative method to configure the udev
180 properties to use for determining unique path identi‐
181 fiers (WWIDs).
182 The value of this option is a space separated list of
184 records like "type:ATTR", where type is matched
185 against the beginning of the device node name (e.g.
186 sd:ATTR matches sda), and ATTR is the name of the udev
187 property to use for matching devices.
188 If this option is configured and matches the device
190 node name of a device, it overrides any other config‐
191 ured methods for determining the WWID for this de‐
192 vice.
193 This option cannot be changed during runtime with the
195 multipathd reconfigure command.
196 The default is: <unset>. To enable uevent merging, set
198 it e.g. to "sd:ID_SERIAL dasd:ID_UID nvme:ID_WWN".
199 uid_attribute The udev attribute providing a unique path identifier
201 (WWID). If uid_attribute is set to the empty string,
202 WWID determination is done using the sysfs method
203 rather then using udev (not recommended in production;
204 see WWID generation below).
205 The default is: ID_SERIAL, for SCSI devices
207 The default is: ID_UID, for DASD devices
209 The default is: ID_WWN, for NVMe devices
211 getuid_callout This option is not supported any more. The value is
213 ignored.
214 prio The name of the path priority routine. The specified
216 routine should return a numeric value specifying the
217 relative priority of this path. Higher number have a
218 higher priority. "none" is a valid value. Currently
219 the following path priority routines are implemented:
220 const Return a constant priority of 1.
222 sysfs Use the sysfs attributes access_state and
224 preferred_path to generate the path prior‐
225 ity. This prioritizer accepts the optional
226 prio_arg exclusive_pref_bit.
227 emc (Hardware-dependent) Generate the path
229 priority for DGC class arrays as CLARiiON
230 CX/AX and EMC VNX families with Failover
231 Mode 1 (Passive Not Ready(PNR)).
232 alua (Hardware-dependent) Generate the path
234 priority based on the SCSI-3 ALUA set‐
235 tings. This prioritizer accepts the op‐
236 tional prio_arg exclusive_pref_bit.
237 ontap (Hardware-dependent) Generate the path
239 priority for NetApp ONTAP class, and re‐
240 branded arrays.
241 rdac (Hardware-dependent) Generate the path
243 priority for LSI/Engenio/NetApp RDAC class
244 as NetApp SANtricity E/EF Series, and re‐
245 branded arrays.
246 hp_sw (Hardware-dependent) Generate the path
248 priority for HP/COMPAQ/DEC HSG80 and
249 MSA/HSV arrays with Active/Standby mode
250 exclusively.
251 hds (Hardware-dependent) Generate the path
253 priority for Hitachi AMS families of ar‐
254 rays other than AMS 2000.
255 random Generate a random priority between 1 and
257 10.
258 weightedpath
260 Generate the path priority based on the
261 regular expression and the priority pro‐
262 vided as argument. Requires prio_args key‐
263 word.
264 path_latency
266 Generate the path priority based on a la‐
267 tency algorithm. Requires prio_args key‐
268 word.
269 ana (Hardware-dependent) Generate the path
271 priority based on the NVMe ANA settings.
272 datacore (Hardware-dependent) Generate the path
274 priority for some DataCore storage arrays.
275 Requires prio_args keyword.
276 iet (iSCSI only) Generate path priority for
278 iSCSI targets based on IP address. Re‐
279 quires prio_args keyword.
280 The default depends on the detect_prio setting: If de‐
282 tect_prio is yes (default), the default priority algo‐
283 rithm is sysfs (except for NetAPP E-Series, where it
284 is alua). If detect_prio is no, the default priority
285 algorithm is const.
286 prio_args Arguments to pass to to the prio function. This only
288 applies to certain prioritizers:
289 weighted Needs a value of the form "<hbtl|dev‐
291 name|serial|wwn> <regex1> <prio1> <regex2>
292 <prio2> ..."
293 hbtl Regex can be of SCSI H:B:T:L for‐
295 mat. For example: 1:0:.:. ,
296 *:0:0:.
297 devname Regex can be of device name for‐
299 mat. For example: sda , sd.e
300 serial Regex can be of serial number for‐
302 mat. For example: .*J1FR.*324 .
303 The serial can be looked up
304 through sysfs or by running multi‐
305 pathd show paths format "%z". For
306 example: 0395J1FR904324
307 wwn Regex can be of the form
309 "host_wwnn:host_wwpn:tar‐
310 get_wwnn:target_wwpn" these values
311 can be looked up through sysfs or
312 by running multipathd show paths
313 format "%N:%R:%n:%r". For example:
314 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.*
315 , .*:.*:iqn.2009-10.com.red‐
316 hat.msp.lab.ask-06:.*
317 path_latency
319 Needs a value of the form "io_num=<20>
320 base_num=<10>"
321 io_num The number of read IOs sent to the
323 current path continuously, used to
324 calculate the average path la‐
325 tency. Valid Values: Integer, [2,
326 200].
327 base_num
329 The base number value of logarith‐
330 mic scale, used to partition dif‐
331 ferent priority ranks. Valid Val‐
332 ues: Integer, [2, 10]. And Max av‐
333 erage latency value is 100s, min
334 average latency value is 1us. For
335 example: If base_num=10, the paths
336 will be grouped in priority groups
337 with path latency <=1us, (1us,
338 10us], (10us, 100us], (100us,
339 1ms], (1ms, 10ms], (10ms, 100ms],
340 (100ms, 1s], (1s, 10s], (10s,
341 100s], >100s.
342 alua If exclusive_pref_bit is set, paths with
344 the preferred path bit set will always be
345 in their own path group.
346 sysfs If exclusive_pref_bit is set, paths with
348 the preferred path bit set will always be
349 in their own path group.
350 datacore
352 preferredsds
354 (Mandatory) The preferred "SDS
355 name".
356 timeout (Optional) The timeout for the IN‐
358 QUIRY, in ms.
359 iet
361 preferredip=...
363 (Mandatory) Th preferred IP ad‐
364 dress, in dotted decimal notation,
365 for iSCSI targets.
366 The default is: <unset>
368 features Specify any device-mapper features to be used. Syntax
370 is num list where num is the number, between 0 and 8,
371 of features in list. Possible values for the feature
372 list are:
373 queue_if_no_path
375 (Deprecated, superseded by no_path_retry)
376 Queue I/O if no path is active. Identical
377 to the no_path_retry with queue value. If
378 both this feature and no_path_retry are
379 set, the latter value takes precedence.
380 See KNOWN ISSUES.
381 pg_init_retries <times>
383 (Since kernel 2.6.24) Number of times to
384 retry pg_init, it must be between 1 and
385 50.
386 pg_init_delay_msecs <msecs>
388 (Since kernel 2.6.38) Number of msecs be‐
389 fore pg_init retry, it must be between 0
390 and 60000.
391 queue_mode <mode>
393 (Since kernel 4.8) Select the queueing
394 mode per multipath device. <mode> can be
395 bio, rq or mq, which corresponds to bio-
396 based, request-based, and block-multiqueue
397 (blk-mq) request-based, respectively. The
398 default depends on the kernel parameter
399 dm_mod.use_blk_mq. It is mq if the latter
400 is set, and rq otherwise.
401 The default is: <unset>
403 path_checker The default method used to determine the path's state.
405 The synchronous checkers (all except tur and directio)
406 will cause multipathd to pause most activity, waiting
407 up to checker_timeout seconds for the path to respond.
408 The asynchronous checkers (tur and directio) will not
409 pause multipathd. Instead, multipathd will check for a
410 response once per second, until checker_timeout sec‐
411 onds have elapsed. Possible values are:
412 readsector0 (Deprecated) Read the first sector of the
414 device. This checker is being deprecated,
415 please use tur instead.
416 tur Issue a TEST UNIT READY command to the de‐
418 vice.
419 emc_clariion
421 (Hardware-dependent) Query the DGC/EMC
422 specific EVPD page 0xC0 to determine the
423 path state for CLARiiON CX/AX and EMC VNX
424 and Unity arrays families.
425 hp_sw (Hardware-dependent) Check the path state
427 for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
428 with Active/Standby mode exclusively.
429 rdac (Hardware-dependent) Check the path state
431 for LSI/Engenio/NetApp RDAC class as Ne‐
432 tApp SANtricity E/EF Series, and rebranded
433 arrays.
434 directio Read the first sector with direct I/O.
436 This checker could cause spurious path
437 failures under high load. Increasing
438 checker_timeout can help with this.
439 cciss_tur (Hardware-dependent) Check the path state
441 for HP/COMPAQ Smart Array(CCISS) con‐
442 trollers.
443 none Do not check the device, fallback to use
445 the values retrieved from sysfs
446 The default is: tur
448 alias_prefix The user_friendly_names prefix.
450 The default is: mpath
452 failback Tell multipathd how to manage path group failback. To
454 select immediate or a value, it's mandatory that the
455 device has support for a working prioritizer.
456 immediate Immediately failback to the highest prior‐
458 ity pathgroup that contains active paths.
459 manual Do not perform automatic failback.
461 followover Used to deal with multiple computers ac‐
463 cessing the same Active/Passive storage
464 devices. Only perform automatic failback
465 when the first path of a pathgroup becomes
466 active. This keeps a cluster node from au‐
467 tomatically failing back when another node
468 requested the failover.
469 values > 0 Deferred failback (time to defer in sec‐
471 onds).
472 The default is: manual
474 rr_min_io Number of I/O requests to route to a path before
476 switching to the next in the same path group. This is
477 only for Block I/O(BIO) based multipath and only apply
478 to round-robin path_selector.
479 The default is: 1000
481 rr_min_io_rq Number of I/O requests to route to a path before
483 switching to the next in the same path group. This is
484 only for Request based multipath and only apply to
485 round-robin path_selector.
486 The default is: 1
488 max_fds Specify the maximum number of file descriptors that
490 can be opened by multipath and multipathd. This is
491 equivalent to ulimit -n. A value of max will set this
492 to the system limit from /proc/sys/fs/nr_open. If this
493 is not set, the maximum number of open fds is taken
494 from the calling process. It is usually 1024. To be
495 safe, this should be set to the maximum number of
496 paths plus 32, if that number is greater than 1024.
497 The default is: max
499 rr_weight If set to priorities the multipath configurator will
501 assign path weights as "path prio * rr_min_io". Possi‐
502 ble values are priorities or uniform . Only apply to
503 round-robin path_selector.
504 The default is: uniform
506 no_path_retry Specify what to do when all paths are down. Possible
508 values are:
509 value > 0 Number of retries until disable I/O queue‐
511 ing.
512 fail For immediate failure (no I/O queueing).
514 queue For never stop I/O queueing, similar to
516 queue_if_no_path. See KNOWN ISSUES.
517 The default is: fail
519 queue_without_daemon
521 If set to no , when multipathd stops, queueing will be
522 turned off for all devices. This is useful for de‐
523 vices that set no_path_retry. If a machine is shut
524 down while all paths to a device are down, it is pos‐
525 sible to hang waiting for I/O to return from the de‐
526 vice after multipathd has been stopped. Without multi‐
527 pathd running, access to the paths cannot be restored,
528 and the kernel cannot be told to stop queueing I/O.
529 Setting queue_without_daemon to no , avoids this prob‐
530 lem.
531 The default is: no
533 checker_timeout Specify the timeout to use for path checkers and pri‐
535 oritizers, in seconds. Only prioritizers that issue
536 scsi commands use checker_timeout. If a path does not
537 respond to the checker command after checker_timeout
538 seconds have elapsed, it is considered down.
539 The default is: in /sys/block/<dev>/device/timeout
541 allow_usb_devices
543 If set to no , all USB devices will be skipped during
544 path discovery. If you intend to use multipath on USB
545 attached devices, set this to yes.
546 The default is: no
548 flush_on_last_del
550 If set to yes , multipathd will disable queueing when
551 the last path to a device has been deleted.
552 The default is: no
554 user_friendly_names
556 If set to yes , using the bindings file /etc/multi‐
557 path/bindings to assign a persistent and unique alias
558 to the multipath, in the form of mpath<n>. If set to
559 no use the WWID as the alias. In either case this be
560 will be overridden by any specific aliases in the mul‐
561 tipaths section.
562 The default is: no
564 fast_io_fail_tmo Specify the number of seconds the SCSI layer will wait
566 after a problem has been detected on a FC remote port
567 before failing I/O to devices on that remote port.
568 This should be smaller than dev_loss_tmo. Setting this
569 to off will disable the timeout.
570 The default is: 5
572 dev_loss_tmo Specify the number of seconds the SCSI layer will wait
574 after a problem has been detected on a FC remote port
575 before removing it from the system. This can be set to
576 "infinity" which sets it to the max value of
577 2147483647 seconds, or 68 years. It will be automati‐
578 cally adjusted to the overall retry interval
579 no_path_retry * polling_interval if a number of re‐
580 tries is given with no_path_retry and the overall
581 retry interval is longer than the specified
582 dev_loss_tmo value. The Linux kernel will cap this
583 value to 600 if fast_io_fail_tmo is not set. See KNOWN
584 ISSUES.
585 The default is: 600
587 eh_deadline Specify the maximum number of seconds the SCSI layer
589 will spend doing error handling when scsi devices
590 fail. After this timeout the scsi layer will perform a
591 full HBA reset. Setting this may be necessary in cases
592 where the rport is never lost, so fast_io_fail_tmo and
593 dev_loss_tmo will never trigger, but (frequently do to
594 load) scsi commands still hang. Note: when the scsi
595 error handler performs the HBA reset, all target paths
596 on that HBA will be affected. eh_deadline should only
597 be set in cases where all targets on the affected HBAs
598 are multipathed.
599 The default is: <unset>
601 bindings_file This option is deprecated, and will be removed in a
603 future release. The full pathname of the binding file
604 to be used when the user_friendly_names option is set.
605 The default is: /etc/multipath/bindings
607 wwids_file This option is deprecated, and will be removed in a
609 future release. The full pathname of the WWIDs file,
610 which is used by multipath to keep track of the WWIDs
611 for LUNs it has created multipath devices on in the
612 past.
613 The default is: /etc/multipath/wwids
615 prkeys_file This option is deprecated, and will be removed in a
617 future release. The full pathname of the prkeys file,
618 which is used by multipathd to keep track of the per‐
619 sistent reservation key used for a specific WWID, when
620 reservation_key is set to file.
621 The default is: /etc/multipath/prkeys
623 log_checker_err If set to once , multipathd logs the first path
625 checker error at logging level 2. Any later errors are
626 logged at level 3 until the device is restored. If set
627 to always , multipathd always logs the path checker
628 error at logging level 2.
629 The default is: always
631 reservation_key This is the service action reservation key used by
633 mpathpersist. It must be set for all multipath devices
634 using persistent reservations, and it must be the same
635 as the RESERVATION KEY field of the PERSISTENT RESERVE
636 OUT parameter list which contains an 8-byte value pro‐
637 vided by the application client to the device server
638 to identify the I_T nexus. If the --param-aptpl option
639 is used when registering the key with mpathpersist,
640 :aptpl must be appended to the end of the reservation
641 key.
642 Alternatively, this can be set to file, which will
644 store the RESERVATION KEY registered by mpathpersist
645 in the prkeys_file. multipathd will then use this key
646 to register additional paths as they appear. When the
647 registration is removed, the RESERVATION KEY is re‐
648 moved from the prkeys_file. The prkeys file will auto‐
649 matically keep track of whether the key was registered
650 with --param-aptpl.
651 The default is: <unset>
653 all_tg_pt Set the 'all targets ports' flag when registering keys
655 with mpathpersist. Some arrays automatically set and
656 clear registration keys on all target ports from a
657 host, instead of per target port per host. The
658 ALL_TG_PT flag must be set to successfully use mpath‐
659 persist on these arrays. Setting this option is iden‐
660 tical to calling mpathpersist with --param-alltgpt
661 The default is: no
663 retain_attached_hw_handler
665 (Obsolete for kernels >= 4.3) If set to yes and the
666 SCSI layer has already attached a hardware_handler to
667 the device, multipath will not force the device to use
668 the hardware_handler specified by multipath.conf. If
669 the SCSI layer has not attached a hardware handler,
670 multipath will continue to use its configured hardware
671 handler.
672 The default is: yes
674 Important Note: Linux kernel 4.3 or newer always be‐
676 haves as if "retain_attached_hw_handler yes" was set.
677 detect_prio If set to yes , multipath will try to detect if the
679 device supports SCSI-3 ALUA. If so, the device will
680 automatically use the sysfs prioritizer if the re‐
681 quired sysf attributes access_state and preferred_path
682 are supported, or the alua prioritizer if not. If set
683 to no , the prioritizer will be selected as usual.
684 The default is: yes
686 detect_checker if set to yes , multipath will try to detect if the
688 device supports SCSI-3 ALUA. If so, the device will
689 automatically use the tur checker. If set to no , the
690 checker will be selected as usual.
691 The default is: yes
693 force_sync If set to yes , multipathd will call the path checkers
695 in sync mode only. This means that only one checker
696 will run at a time. This is useful in the case where
697 many multipathd checkers running in parallel causes
698 significant CPU pressure.
699 The default is: no
701 strict_timing If set to yes , multipathd will start a new path
703 checker loop after exactly one second, so that each
704 path check will occur at exactly polling_interval sec‐
705 onds. On busy systems path checks might take longer
706 than one second; here the missing ticks will be ac‐
707 counted for on the next round. A warning will be
708 printed if path checks take longer than polling_inter‐
709 val seconds.
710 The default is: no
712 deferred_remove If set to yes , multipathd will do a deferred remove
714 instead of a regular remove when the last path device
715 has been deleted. This means that if the multipath
716 device is still in use, it will be freed when the last
717 user closes it. If path is added to the multipath de‐
718 vice before the last user closes it, the deferred re‐
719 move will be canceled.
720 The default is: no
722 partition_delimiter
724 This parameter controls how multipath chooses the
725 names of partition devices of multipath maps if a mul‐
726 tipath map is renamed (e.g. if a map alias is added or
727 changed). If this parameter is set to a string other
728 than "/UNSET/" (even the empty string), multipath in‐
729 serts that string between device name and partition
730 number to construct the partition device name. Other‐
731 wise (i.e. if this parameter is unset or has the value
732 "/UNSET/"), the behavior depends on the map name: if
733 it ends in a digit, a "p" is inserted between name and
734 partition number; otherwise, the partition number is
735 simply appended. Distributions may use a non-null de‐
736 fault value for this option; in this case, the user
737 must set it to "/UNSET/" to obtain the original <un‐
738 set> behavior. Use multipath -T to check the current
739 settings.
740 The default is: <unset>
742 config_dir This option is not supported any more. The value is
744 ignored.
745 san_path_err_threshold
747 If set to a value greater than 0, multipathd will
748 watch paths and check how many times a path has been
749 failed due to errors.If the number of failures on a
750 particular path is greater than the
751 san_path_err_threshold, then the path will not rein‐
752 state till san_path_err_recovery_time. These path
753 failures should occur within a san_path_err_for‐
754 get_rate checks, if not we will consider the path is
755 good enough to reinstantate. See "Shaky paths detec‐
756 tion" below.
757 The default is: no
759 san_path_err_forget_rate
761 If set to a value greater than 0, multipathd will
762 check whether the path failures has exceeded the
763 san_path_err_threshold within this many checks i.e
764 san_path_err_forget_rate . If so we will not reinstate
765 the path till san_path_err_recovery_time. See "Shaky
766 paths detection" below.
767 The default is: no
769 san_path_err_recovery_time
771 If set to a value greater than 0, multipathd will make
772 sure that when path failures has exceeded the
773 san_path_err_threshold within san_path_err_forget_rate
774 then the path will be placed in failed state for
775 san_path_err_recovery_time duration.Once
776 san_path_err_recovery_time has timeout we will rein‐
777 state the failed path . san_path_err_recovery_time
778 value should be in secs. See "Shaky paths detection"
779 below.
780 The default is: no
782 marginal_path_double_failed_time
784 One of the four parameters of supporting path check
785 based on accounting IO error such as intermittent er‐
786 ror. When a path failed event occurs twice in mar‐
787 ginal_path_double_failed_time seconds due to an IO er‐
788 ror and all the other three parameters are set, multi‐
789 pathd will fail the path and enqueue this path into a
790 queue of which members are sent a couple of continuous
791 direct reading asynchronous IOs at a fixed sample rate
792 of 10HZ to start IO error accounting process. See
793 "Shaky paths detection" below.
794 The default is: no
796 marginal_path_err_sample_time
798 One of the four parameters of supporting path check
799 based on accounting IO error such as intermittent er‐
800 ror. If it is set to a value no less than 120, when a
801 path fail event occurs twice in marginal_path_dou‐
802 ble_failed_time second due to an IO error, multipathd
803 will fail the path and enqueue this path into a queue
804 of which members are sent a couple of continuous di‐
805 rect reading asynchronous IOs at a fixed sample rate
806 of 10HZ to start the IO accounting process for the
807 path will last for marginal_path_err_sample_time. If
808 the rate of IO error on a particular path is greater
809 than the marginal_path_err_rate_threshold, then the
810 path will not reinstate for mar‐
811 ginal_path_err_recheck_gap_time seconds unless there
812 is only one active path. After mar‐
813 ginal_path_err_recheck_gap_time expires, the path will
814 be requeued for rechecking. If checking result is good
815 enough, the path will be reinstated. See "Shaky paths
816 detection" below.
817 The default is: no
819 marginal_path_err_rate_threshold
821 The error rate threshold as a permillage (1/1000). One
822 of the four parameters of supporting path check based
823 on accounting IO error such as intermittent error. Re‐
824 fer to marginal_path_err_sample_time. If the rate of
825 IO errors on a particular path is greater than this
826 parameter, then the path will not reinstate for mar‐
827 ginal_path_err_recheck_gap_time seconds unless there
828 is only one active path. See "Shaky paths detection"
829 below.
830 The default is: no
832 marginal_path_err_recheck_gap_time
834 One of the four parameters of supporting path check
835 based on accounting IO error such as intermittent er‐
836 ror. Refer to marginal_path_err_sample_time. If this
837 parameter is set to a positive value, the failed path
838 of which the IO error rate is larger than mar‐
839 ginal_path_err_rate_threshold will be kept in failed
840 state for marginal_path_err_recheck_gap_time seconds.
841 When marginal_path_err_recheck_gap_time seconds ex‐
842 pires, the path will be requeued for checking. If
843 checking result is good enough, the path will be rein‐
844 stated, or else it will keep failed. See "Shaky paths
845 detection" below.
846 The default is: no
848 delay_watch_checks
850 This option is deprecated, and mapped to
851 san_path_err_forget_rate. If this is set to a value
852 greater than 0 and no san_path_err options are set,
853 san_path_err_forget_rate will be set to the value of
854 delay_watch_checks and san_path_err_threshold will be
855 set to 1. See the san_path_err_forget_rate and
856 san_path_err_threshold options, and "Shaky paths de‐
857 tection" below for more information.
858 The default is: no
860 delay_wait_checks
862 This option is deprecated, and mapped to
863 san_path_err_recovery_time. If this is set to a value
864 greater than 0 and no san_path_err options are set,
865 san_path_err_recovery_time will be set to the value of
866 delay_wait_checks times max_polling_interval. This
867 will give approximately the same wait time as de‐
868 lay_wait_checks previously did. Also,
869 san_path_err_threshold will be set to 1. See the
870 san_path_err_recovery_time and san_path_err_threshold
871 options, and "Shaky paths detection" below for more
872 information.
873 The default is: no
875 marginal_pathgroups
877 If set to off, the delay_*_checks, marginal_path_*,
878 and san_path_err_* options will keep marginal, or
879 "shaky", paths from being reinstated until they have
880 been monitored for some time. This can cause situa‐
881 tions where all non-marginal paths are down, and no
882 paths are usable until multipathd detects this and re‐
883 instates a marginal path. If the multipath device is
884 not configured to queue IO in this case, it can cause
885 IO errors to occur, even though there are marginal
886 paths available. However, if this option is set to
887 on, when one of the marginal path detecting methods
888 determines that a path is marginal, it will be rein‐
889 stated and placed in a separate pathgroup that will
890 only be used after all the non-marginal pathgroups
891 have been tried first. This prevents the possibility
892 of IO errors occurring while marginal paths are still
893 usable. After the path has been monitored for the con‐
894 figured time, and is declared healthy, it will be re‐
895 turned to its normal pathgroup. If this option is set
896 to fpin, multipathd will receive fpin notifications,
897 set path states to "marginal" accordingly, and regroup
898 paths as described for on. This option can't be used
899 in combination with other options for "Shaky path de‐
900 tection" (see below). Note: If this is set to fpin,
901 the marginal_path_* and san_path_err_* options are im‐
902 plicitly set to no. Also, this option cannot be
903 switched either to or from fpin on a multipathd recon‐
904 figure. multipathd must be restarted for the change to
905 take effect. See "Shaky paths detection" below for
906 more information.
907 The default is: off
909 find_multipaths This option controls whether multipath and multipathd
911 try to create multipath maps over non-blacklisted de‐
912 vices they encounter. This matters a) when a device is
913 encountered by multipath -u during udev rule process‐
914 ing (a device is blocked from further processing by
915 higher layers - such as LVM - if and only if it´s con‐
916 sidered a valid multipath device path), and b) when
917 multipathd detects a new device. The following values
918 are possible:
919 strict Both multipath and multipathd treat only
921 such devices as multipath devices which have
922 been part of a multipath map previously, and
923 which are therefore listed in the
924 wwids_file. Users can manually set up multi‐
925 path maps using the multipathd add map com‐
926 mand. Once set up manually, the map is re‐
927 membered in the wwids file and will be set
928 up automatically in the future.
929 no Multipath behaves like strict. Multipathd
931 behaves like greedy.
932 yes Both multipathd and multipath treat a device
934 as multipath device if the conditions for
935 strict are met, or if at least two non-
936 blacklisted paths with the same WWID have
937 been detected.
938 greedy Both multipathd and multipath treat every
940 non-blacklisted device as multipath device
941 path.
942 smart This differs from find_multipaths yes only
944 in the way it treats new devices for which
945 only one path has been detected yet. When
946 such a device is first encountered in udev
947 rules, it is treated as a multipath device.
948 multipathd waits whether additional paths
949 with the same WWID appears. If that happens,
950 it sets up a multipath map. If it doesn´t
951 happen until a timeout expires, or if set‐
952 ting up the map fails, a new uevent is trig‐
953 gered for the device; at second encounter in
954 the udev rules, the device will be treated
955 as non-multipath and passed on to upper lay‐
956 ers. Note: this may cause delays during de‐
957 vice detection if there are single-path de‐
958 vices which aren´t blacklisted.
959 The default is: strict
961 find_multipaths_timeout
963 Timeout, in seconds, to wait for additional paths af‐
964 ter detecting the first one, if find_multipaths
965 "smart" (see above) is set. If the value is positive,
966 this timeout is used for all unknown, non-blacklisted
967 devices encountered. If the value is negative (recom‐
968 mended), it's only applied to "known" devices that
969 have an entry in multipath's hardware table, either in
970 the built-in table or in a device section; other ("un‐
971 known") devices will use a timeout of only 1 second to
972 avoid booting delays. The value 0 means "use the
973 built-in default". If find_multipath has a value other
974 than smart, this option has no effect.
975 The default is: -10 (10s for known and 1s for unknown
977 hardware)
978 uxsock_timeout CLI receive timeout in milliseconds. For larger sys‐
980 tems CLI commands might timeout before the multipathd
981 lock is released and the CLI command can be processed.
982 This will result in errors like "timeout receiving
983 packet" to be returned from CLI commands. In these
984 cases it is recommended to increase the CLI timeout to
985 avoid those issues.
986 The default is: 4000
988 retrigger_tries Sets the number of times multipathd will try to re‐
990 trigger a uevent to get the WWID.
991 The default is: 3
993 retrigger_delay Sets the amount of time, in seconds, to wait between
995 retriggers.
996 The default is: 10
998 missing_uev_wait_timeout
1000 Controls how many seconds multipathd will wait, after
1001 a new multipath device is created, to receive a change
1002 event from udev for the device, before automatically
1003 enabling device reloads. Usually multipathd will delay
1004 reloads on a device until it receives a change uevent
1005 from the initial table load.
1006 The default is: 30
1008 skip_kpartx If set to yes , kpartx will not automatically create
1010 partitions on the device.
1011 The default is: no
1013 disable_changed_wwids
1015 This option is deprecated and ignored. If the WWID of
1016 a path suddenly changes, multipathd handles it as if
1017 it was removed and then added again.
1018 remove_retries This sets how may times multipath will retry removing
1020 a device that is in-use. Between each attempt, multi‐
1021 path will sleep 1 second.
1022 The default is: 0
1024 max_sectors_kb Sets the max_sectors_kb device parameter on all path
1026 devices and the multipath device to the specified
1027 value.
1028 The default is: in /sys/block/<dev>/queue/max_sec‐
1030 tors_kb
1031 ghost_delay Sets the number of seconds that multipath will wait
1033 after creating a device with only ghost paths before
1034 marking it ready for use in systemd. This gives the
1035 active paths time to appear before the multipath runs
1036 the hardware handler to switch the ghost paths to ac‐
1037 tive ones. Setting this to 0 or no makes multipath im‐
1038 mediately mark a device with only ghost paths as
1039 ready.
1040 The default is: no
1042 enable_foreign Enables or disables foreign libraries (see section
1044 FOREIGN MULTIPATH SUPPORT below). The value is a regu‐
1045 lar expression; foreign libraries are loaded if their
1046 name (e.g. "nvme") matches the expression. By default,
1047 no foreign libraries are enabled. Set this to "nvme"
1048 to enable NVMe native multipath support, or ".*" to
1049 enable all foreign libraries.
1050 The default is: "NONE"
1052 recheck_wwid If set to yes, when a failed path is restored, its
1054 wwid is rechecked. If the wwid has changed, the path
1055 is removed from the current multipath device, and re-
1056 added as a new path. Multipathd will also recheck a
1057 path's wwid if it is manually re-added. This option
1058 only works for SCSI devices that are configured to use
1059 the default uid_attribute, ID_SERIAL, or sysfs for
1060 getting their wwid.
1061 The default is: no
1063
1066 The blacklist section is used to exclude specific devices from the mul‐
1067 tipath topology. It is most commonly used to exclude local disks or
1068 non-disk devices (such as LUNs for the storage array controller) from
1069 being handled by multipath-tools.
1070 In the blacklist and blacklist_exceptions sections, starting a quoted
1072 value with an exclamation mark "!" will invert the matching of the rest
1073 of the regular expression. For instance, "!^sd[a-z]" will match all
1074 values that do not start with "sd[a-z]". The exclamation mark can be
1075 escaped "\!" to match a literal ! at the start of a regular expression.
1076 Note: The exclamation mark must be inside quotes, otherwise it will be
1077 treated as starting a comment.
1078 The blacklist_exceptions section is used to revert the actions of the
1080 blacklist section. This allows one to selectively include ("whitelist")
1081 devices which would normally be excluded via the blacklist section. A
1082 common usage is to blacklist "everything" using a catch-all regular ex‐
1083 pression, and create specific blacklist_exceptions entries for those
1084 devices that should be handled by multipath-tools.
1085 The following keywords are recognized in both sections. The defaults
1087 are empty unless explicitly stated.
1088 devnode Regular expression matching the device nodes to be ex‐
1090 cluded/included.
1091 The default blacklist consists of the regular expres‐
1093 sion "!^(sd[a-z]|dasd[a-z]|nvme[0-9])". This causes
1094 all device types other than scsi, dasd, and nvme to be
1095 excluded from multipath handling by default.
1096 wwid Regular expression for the World Wide Identifier of a
1098 device to be excluded/included.
1099 device Subsection for the device description. This subsection
1101 recognizes the vendor and product keywords. Both are
1102 regular expressions. For a full description of these
1103 keywords please see the devices section description.
1104 property Regular expression for an udev property. All devices
1106 that have matching udev properties will be ex‐
1107 cluded/included. The handling of the property keyword
1108 is special, because if a property blacklist_exception
1109 is set, devices must have at least one whitelisted
1110 udev property; otherwise they're treated as black‐
1111 listed, and the message "blacklisted, udev property
1112 missing" is displayed in the logs. For example, set‐
1113 ting the property blacklist_exception to
1114 (SCSI_IDENT_|ID_WWN), will cause well-behaved SCSI de‐
1115 vices and devices that provide a WWN (World Wide Num‐
1116 ber) to be included, and all others to be excluded.
1117 This works to exclude most non-multipathable devices.
1118 Note: The behavior of this option has changed in mul‐
1120 tipath-tools 0.8.2 compared to previous versions.
1121 Blacklisting by missing properties is only applied to
1122 devices which do have the property specified by
1123 uid_attribute (e.g. ID_SERIAL) set. Previously, it was
1124 applied to every device, possibly causing devices to
1125 be blacklisted because of temporary I/O error condi‐
1126 tions.
1127 protocol Regular expression for the protocol of a device to be
1129 excluded/included.
1130 The protocol strings that multipath recognizes are
1132 scsi:fcp, scsi:spi, scsi:ssa, scsi:sbp, scsi:srp,
1133 scsi:iscsi, scsi:sas, scsi:adt, scsi:ata, scsi:unspec,
1134 ccw, cciss, nvme, and undef. The protocol that a path
1135 is using can be viewed by running multipathd show
1136 paths format "%d %P"
1137 For every device, these 5 blacklist criteria are evaluated in the order
1139 "property, devnode, device, protocol, wwid". If a device turns out to
1140 be blacklisted by any criterion, it's excluded from handling by multi‐
1141 pathd, and the later criteria aren't evaluated any more. For each cri‐
1142 terion, the whitelist takes precedence over the blacklist if a device
1143 matches both.
1144 Note: Besides the blacklist and whitelist, other configuration options
1146 such as find_multipaths have an impact on whether or not a given device
1147 is handled by multipath-tools.
1148
1150 The multipaths section allows setting attributes of multipath maps. The
1151 attributes that are set via the multipaths section (see list below)
1152 take precedence over all other configuration settings, including those
1153 from the overrides section.
1154 The only recognized attribute for the multipaths section is the multi‐
1156 path subsection. If there are multiple multipath subsections matching a
1157 given WWID, the contents of these sections are merged, and settings
1158 from later entries take precedence.
1159 The multipath subsection recognizes the following attributes:
1161 wwid (Mandatory) World Wide Identifier. Detected multipath
1163 maps are matched against this attribute. Note that,
1164 unlike the wwid attribute in the blacklist section,
1165 this is not a regular expression or a substring; WWIDs
1166 must match exactly inside the multipaths section.
1167 alias Symbolic name for the multipath map. This takes prece‐
1169 dence over a an entry for the same WWID in the bind‐
1170 ings_file.
1171 The following attributes are optional; if not set the default values
1173 are taken from the overrides, devices, or defaults section:
1174 path_grouping_policy
1176 path_selector
1177 prio
1178 prio_args
1179 failback
1180 rr_weight
1181 no_path_retry
1182 rr_min_io
1183 rr_min_io_rq
1184 flush_on_last_del
1185 features
1186 reservation_key
1187 user_friendly_names
1188 deferred_remove
1189 san_path_err_threshold
1190 san_path_err_forget_rate
1191 san_path_err_recovery_time
1192 marginal_path_err_sample_time
1193 marginal_path_err_rate_threshold
1194 marginal_path_err_recheck_gap_time
1195 marginal_path_double_failed_time
1196 delay_watch_checks
1197 delay_wait_checks
1198 skip_kpartx
1199 max_sectors_kb
1200 ghost_delay
1201
1203 Important:
1204 The built-in hardware device table of multipath-tools is created by
1205 members of the Linux community in the hope that it will be useful.
1206 The existence of an entry for a given storage product in the hard‐
1207 ware table does not imply that the product vendor supports, or has
1208 tested, the product with multipath-tools in any way. Always con‐
1209 sult the vendor's official documentation for support-related infor‐
1210 mation.
1211 multipath-tools have a built-in device table with reasonable defaults
1213 for more than 100 known multipath-capable storage devices. The devices
1214 section can be used to override these settings. If there are multiple
1215 matches for a given device, the attributes of all matching entries are
1216 applied to it. If an attribute is specified in several matching device
1217 subsections, later entries take precedence. Thus, entries in files un‐
1218 der config_dir (in reverse alphabetical order) have the highest prece‐
1219 dence, followed by entries in multipath.conf; the built-in hardware ta‐
1220 ble has the lowest precedence. Inside a configuration file, later en‐
1221 tries have higher precedence than earlier ones.
1222 The only recognized attribute for the devices section is the device
1224 subsection. Devices detected in the system are matched against the de‐
1225 vice entries using the vendor, product, and revision fields, which are
1226 all POSIX Extended regular expressions (see regex(7)).
1227 The vendor, product, and revision fields that multipath or multipathd
1229 detect for devices in a system depend on the device type. For SCSI de‐
1230 vices, they correspond to the respective fields of the SCSI INQUIRY
1231 page. In general, the command 'multipathd show paths format "%d %s"'
1232 command can be used to see the detected properties for all devices in
1233 the system.
1234 The device subsection recognizes the following attributes:
1236 vendor (Mandatory) Regular expression to match the vendor
1238 name.
1239 product (Mandatory) Regular expression to match the product
1241 name.
1242 revision Regular expression to match the product revision. If
1244 not specified, any revision matches.
1245 product_blacklist
1247 Products with the given vendor matching this string
1248 are blacklisted. This is equivalent to a device entry
1249 in the blacklist section with the vendor attribute set
1250 to this entry's vendor, and the product attribute set
1251 to the value of product_blacklist.
1252 alias_prefix The user_friendly_names prefix to use for this device
1254 type, instead of the default "mpath".
1255 vpd_vendor The vendor specific vpd page information, using the
1257 vpd page abbreviation. The vpd page abbreviation can
1258 be found by running sg_vpd -e. multipathd will use
1259 this information to gather device specific information
1260 that can be displayed with the %g wildcard for the
1261 multipathd show maps format and multipathd show paths
1262 format commands. Currently only the hp3par vpd page is
1263 supported.
1264 hardware_handler The hardware handler to use for this device type. The
1266 following hardware handler are implemented:
1267 1 emc (Hardware-dependent) Hardware handler for
1269 DGC class arrays as CLARiiON CX/AX and EMC
1270 VNX families with Failover Mode 1 (Passive
1271 Not Ready(PNR)).
1272 1 rdac (Hardware-dependent) Hardware handler for
1274 LSI/Engenio/NetApp RDAC class as NetApp
1275 SANtricity E/EF Series, and rebranded ar‐
1276 rays.
1277 1 hp_sw (Hardware-dependent) Hardware handler for
1279 HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
1280 with Active/Standby mode exclusively.
1281 1 alua (Hardware-dependent) Hardware handler for
1283 SCSI-3 ALUA compatible arrays.
1284 1 ana (Hardware-dependent) Hardware handler for
1286 NVMe ANA compatible arrays.
1287 The default is: <unset>
1289 Important Note: Linux kernels 4.3 and newer automati‐
1291 cally attach a device handler to known devices (which
1292 includes all devices supporting SCSI-3 ALUA) and dis‐
1293 allow changing the handler afterwards. Setting hard‐
1294 ware_handler for such devices on these kernels has no
1295 effect.
1296 The following attributes are optional; if not set the default values
1298 are taken from the defaults section:
1299 path_grouping_policy
1301 uid_attribute
1302 path_selector
1303 path_checker
1304 prio
1305 prio_args
1306 features
1307 failback
1308 rr_weight
1309 no_path_retry
1310 rr_min_io
1311 rr_min_io_rq
1312 fast_io_fail_tmo
1313 dev_loss_tmo
1314 eh_deadline
1315 flush_on_last_del
1316 user_friendly_names
1317 retain_attached_hw_handler
1318 detect_prio
1319 detect_checker
1320 deferred_remove
1321 san_path_err_threshold
1322 san_path_err_forget_rate
1323 san_path_err_recovery_time
1324 marginal_path_err_sample_time
1325 marginal_path_err_rate_threshold
1326 marginal_path_err_recheck_gap_time
1327 marginal_path_double_failed_time
1328 delay_watch_checks
1329 delay_wait_checks
1330 skip_kpartx
1331 max_sectors_kb
1332 ghost_delay
1333 all_tg_pt
1334
1336 The overrides section recognizes the following optional attributes; if
1337 not set the values are taken from the devices or defaults sections:
1338 path_grouping_policy
1340 uid_attribute
1341 path_selector
1342 path_checker
1343 alias_prefix
1344 features
1345 prio
1346 prio_args
1347 failback
1348 rr_weight
1349 no_path_retry
1350 rr_min_io
1351 rr_min_io_rq
1352 flush_on_last_del
1353 fast_io_fail_tmo
1354 dev_loss_tmo
1355 eh_deadline
1356 user_friendly_names
1357 retain_attached_hw_handler
1358 detect_prio
1359 detect_checker
1360 deferred_remove
1361 san_path_err_threshold
1362 san_path_err_forget_rate
1363 san_path_err_recovery_time
1364 marginal_path_err_sample_time
1365 marginal_path_err_rate_threshold
1366 marginal_path_err_recheck_gap_time
1367 marginal_path_double_failed_time
1368 delay_watch_checks
1369 delay_wait_checks
1370 skip_kpartx
1371 max_sectors_kb
1372 ghost_delay
1373 all_tg_pt
1374 The overrides section also recognizes the optional protocol subsection,
1376 and can contain multiple protocol subsections. Path devices are matched
1377 against the protocol subsection using the mandatory type attribute.
1378 Attributes in a matching protocol subsection take precedence over at‐
1379 tributes in the rest of the overrides section. If there are multiple
1380 matching protocol subsections, later entries take precedence.
1381 protocol subsection
1383 The protocol subsection recognizes the following mandatory at‐
1384 tribute:
1385 type The protocol string of the path device. The possible val‐
1387 ues are scsi:fcp, scsi:spi, scsi:ssa, scsi:sbp, scsi:srp,
1388 scsi:iscsi, scsi:sas, scsi:adt, scsi:ata, scsi:unspec,
1389 ccw, cciss, nvme, and undef. This is not a regular ex‐
1390 pression. the path device protocol string must match ex‐
1391 actly. The protocol that a path is using can be viewed by
1392 running multipathd show paths format "%d %P"
1393 The following attributes are optional; if not set, the default
1395 values are taken from the overrides, devices, or defaults sec‐
1396 tion:
1397 fast_io_fail_tmo
1399 dev_loss_tmo
1400 eh_deadline
1401
1403 Multipath uses a World Wide Identification (WWID) to determine which
1404 paths belong to the same device. Each path presenting the same WWID is
1405 assumed to point to the same device.
1406 The WWID is generated by four methods (in the order of preference):
1408 uid_attrs The WWID is derived from udev attributes by matching
1410 the device node name; cf uid_attrs above.
1411 uid_attribute Use the value of the specified udev attribute; cf
1413 uid_attribute above.
1414 sysfs Try to determine the WWID from sysfs attributes. For
1416 SCSI devices, this means reading the Vital Product
1417 Data (VPD) page "Device Identification" (0x83).
1418 The default settings (using udev and uid_attribute configured from the
1420 built-in hardware table) should work fine in most scenarios. Users who
1421 want to enable uevent merging must set uid_attrs.
1422
1424 A common problem in SAN setups is the occurrence of intermittent er‐
1425 rors: a path is unreachable, then reachable again for a short time,
1426 disappears again, and so forth. This happens typically on unstable in‐
1427 terconnects. It is undesirable to switch pathgroups unnecessarily on
1428 such frequent, unreliable events. multipathd supports three different
1429 methods for detecting this situation and dealing with it. All methods
1430 share the same basic mode of operation: If a path is found to be
1431 "shaky" or "flipping", and appears to be in healthy status, it is not
1432 reinstated (put back to use) immediately. Instead, it is placed in the
1433 "delayed" state and watched for some time, and only reinstated if the
1434 healthy state appears to be stable. If the marginal_pathgroups option
1435 is set, the path will reinstated immediately, but placed in a special
1436 pathgroup for marginal paths. Marginal pathgroups will not be used un‐
1437 til all other pathgroups have been tried. At the time when the path
1438 would normally be reinstated, it will be returned to its normal path‐
1439 group. The logic of determining "shaky" condition, as well as the logic
1440 when to reinstate, differs between the three methods.
1441 "delay_checks" failure tracking
1443 This method is deprecated and mapped to the "san_path_err"
1444 method. See the delay_watch_checks and delay_wait_checks op‐
1445 tions above for more information.
1446 "marginal_path" failure tracking
1449 If a second failure event (good->bad transition) occurs within
1450 marginal_path_double_failed_time seconds after a failure, high-
1451 frequency monitoring is started for the affected path: I/O is
1452 sent at a rate of 10 per second. This is done for mar‐
1453 ginal_path_err_sample_time seconds. During this period, the
1454 path is not reinstated. If the rate of errors remains below
1455 marginal_path_err_rate_threshold during the monitoring period,
1456 the path is reinstated. Otherwise, it is kept in failed state
1457 for marginal_path_err_recheck_gap_time, and after that, it is
1458 monitored again. For this method, time intervals are measured
1459 in seconds.
1460 "san_path_err" failure tracking
1462 multipathd counts path failures for each path. Once the number
1463 of failures exceeds the value given by san_path_err_threshold,
1464 the path is not reinstated for san_path_err_recovery_time sec‐
1465 onds. While counting failures, multipathd "forgets" one past
1466 failure every "san_path_err_forget_rate" ticks; thus if errors
1467 don't occur more often then once in the forget rate interval,
1468 the failure count doesn't increase and the threshold is never
1469 reached. Ticks are the time between path checks by multipathd,
1470 which is variable and controlled by the polling_interval and
1471 max_polling_interval parameters.
1472 "FPIN " failure tracking
1474 Fibre channel fabrics can notify hosts about fabric-level is‐
1475 sues such as integrity failures or congestion with so-called
1476 Fabric Performance Impact Notifications (FPINs).On receiving
1477 the fpin notifications through ELS multipathd will move the af‐
1478 fected path and port states to marginal.
1479 This method is deprecated in favor of the "marginal_path" fail‐
1481 ure tracking method, and only offered for backward compatibil‐
1482 ity.
1483 See the documentation of the individual options above for details. It
1485 is strongly discouraged to use more than one of these methods for any
1486 given multipath map, because the two concurrent methods may interact in
1487 unpredictable ways. If the "marginal_path" method is active, the
1488 "san_path_err" parameters are implicitly set to 0.
1489
1491 multipath and multipathd can load "foreign" libraries to add support
1492 for other multipathing technologies besides the Linux device mapper.
1493 Currently this support is limited to printing detected information
1494 about multipath setup. In topology output, the names of foreign maps
1495 are prefixed by the foreign library name in square brackets, as in this
1496 example:
1497 # multipath -ll
1499 uuid.fedcba98-3579-4567-8765-123456789abc [nvme]:nvme4n9 NVMe,Some NVMe controller,FFFFFFFF
1500 size=167772160 features='n/a' hwhandler='ANA' wp=rw
1501 |-+- policy='n/a' prio=50 status=optimized
1502 | `- 4:38:1 nvme4c38n1 0:0 n/a optimized live
1503 `-+- policy='n/a' prio=50 status=optimized
1504 `- 4:39:1 nvme4c39n1 0:0 n/a optimized live
1505 The "nvme" foreign library provides support for NVMe native multi‐
1507 pathing in the kernel. It is part of the standard multipath package.
1508
1510 The usage of queue_if_no_path option can lead to D state processes be‐
1511 ing hung and not killable in situations where all the paths to the LUN
1512 go offline. It is advisable to use the no_path_retry option instead.
1513 The use of queue_if_no_path or no_path_retry might lead to a deadlock
1515 if the dev_loss_tmo setting results in a device being removed while I/O
1516 is still queued. The multipath daemon will update the dev_loss_tmo set‐
1517 ting accordingly to avoid this deadlock. Hence if both values are spec‐
1518 ified the order of precedence is no_path_retry, queue_if_no_path,
1519 dev_loss_tmo.
1520
1522 udev(8), dmsetup(8), multipath(8), multipathd(8).
1523
1525 multipath-tools was developed by Christophe Varoqui, <christophe.varo‐
1526 qui@opensvc.com> and others.
1527Linux 2021-09-08 MULTIPATH.CONF(5)