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