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
51 attribute 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
62 appropriate 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
74 details on the WWID generation see section WWID gener‐
75 ation below. Attributes set in this section take
76 precedence over all others.
77 devices This section defines the device-specific settings.
79 Devices are identified by vendor, product, and revi‐
80 sion.
81 overrides This section defines values for attributes that should
83 override the device-specific settings for all devices.
84
86 The defaults section recognizes the following keywords:
87 verbosity Default verbosity. Higher values increase the ver‐
89 bosity level. Valid levels are between 0 and 6.
90 The default is: 2
92 polling_interval Interval between two path checks in seconds. For prop‐
94 erly functioning paths, the interval between checks
95 will gradually increase to max_polling_interval. This
96 value will be overridden by the WatchdogSec setting in
97 the multipathd.service definition if systemd is used.
98 The default is: 5
100 max_polling_interval
102 Maximal interval between two path checks in seconds.
103 The default is: 4 * polling_interval
105 reassign_maps Enable reassigning of device-mapper maps. With this
107 option multipathd will remap existing device-mapper
108 maps to always point to multipath device, not the
109 underlying block devices. Possible values are yes and
110 no.
111 The default is: no
113 multipath_dir Directory where the dynamic shared objects are stored.
115 Defined at compile time, commonly /lib64/multipath/ or
116 /lib/multipath/.
117 The default is: <system dependent>
119 path_selector The default path selector algorithm to use; they are
121 offered by the kernel multipath target. There are
122 three selector algorithms:
123 round-robin 0
125 Loop through every path in the path group,
126 sending the same amount of I/O to each.
127 Some aspects of behavior can be controlled
128 with the attributes: rr_min_io,
129 rr_min_io_rq and rr_weight.
130 queue-length 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.
135 service-time 0
137 (Since 2.6.31 kernel) Choose the path for
138 the next bunch of I/O based on the amount
139 of outstanding I/O to the path and its
140 relative throughput.
141 The default is: service-time 0
143 path_grouping_policy
145 The default path grouping policy to apply to unspeci‐
146 fied multipaths. Possible values are:
147 failover One path per priority group.
149 multibus All paths in one priority group.
151 group_by_serial
153 One priority group per serial number.
154 group_by_prio
156 One priority group per priority value.
157 Priorities are determined by callout pro‐
158 grams specified as a global, per-con‐
159 troller or per-multipath option in the
160 configuration file.
161 group_by_node_name
163 One priority group per target node name.
164 Target node names are fetched in
165 /sys/class/fc_transport/target*/node_name.
166 The default is: failover
168 uid_attrs The udev attribute providing a unique path identifier
170 for corresponding type of path devices. If this field
171 is configured and matched with type of device, it
172 would override any other methods providing for device
173 unique identifier in config file, and it would acti‐
174 vate merging uevents according to the identifier to
175 promote effiecncy in processing uevents. It has no
176 default value, if you want to identify path by udev
177 attribute and to activate merging uevents for SCSI and
178 DASD devices, you can set its value as: uid_attrs
179 "sd:ID_SERIAL dasd:ID_UID".
180 The default is: <unset>
182 uid_attribute The udev attribute providing a unique path identifier.
184 The default is: for SCSI devices ID_SERIAL
186 The default is: for DASD devices ID_UID
188 The default is: for NVME devices ID_WWN
190 getuid_callout (Superseded by uid_attribute) The default program and
192 args to callout to obtain a unique path identifier.
193 Should be specified with an absolute path.
194 The default is: <unset>
196 prio The name of the path priority routine. The specified
198 routine should return a numeric value specifying the
199 relative priority of this path. Higher number have a
200 higher priority. "none" is a valid value. Currently
201 the following path priority routines are implemented:
202 const Return a constant priority of 1.
204 sysfs Use the sysfs attributes access_state and
206 preferred_path to generate the path prior‐
207 ity. This prioritizer accepts the optional
208 prio_arg exclusive_pref_bit.
209 emc (Hardware-dependent) Generate the path
211 priority for DGC class arrays as CLARiiON
212 CX/AX and EMC VNX and Unity families.
213 alua (Hardware-dependent) Generate the path
215 priority based on the SCSI-3 ALUA set‐
216 tings. This prioritizer accepts the
217 optional prio_arg exclusive_pref_bit.
218 ontap (Hardware-dependent) Generate the path
220 priority for NetApp ONTAP class and OEM
221 arrays as IBM NSeries.
222 rdac (Hardware-dependent) Generate the path
224 priority for LSI/Engenio/NetApp RDAC class
225 as NetApp SANtricity E/EF Series, and OEM
226 arrays from IBM DELL SGI STK and SUN.
227 hp_sw (Hardware-dependent) Generate the path
229 priority for HP/COMPAQ/DEC HSG80 and
230 MSA/HSV arrays with Active/Standby mode
231 exclusively.
232 hds (Hardware-dependent) Generate the path
234 priority for Hitachi AMS families of
235 arrays other than AMS 2000.
236 random Generate a random priority between 1 and
238 10.
239 weightedpath
241 Generate the path priority based on the
242 regular expression and the priority pro‐
243 vided as argument. Requires prio_args key‐
244 word.
245 path_latency
247 Generate the path priority based on a
248 latency algorithm. Requires prio_args
249 keyword.
250 datacore (Hardware-dependent) Generate the path
252 priority for some DataCore storage arrays.
253 Requires prio_args keyword.
254 iet (iSCSI only) Generate path priority for
256 iSCSI targets based on IP address.
257 Requires prio_args keyword.
258 The default depends on the detect_prio setting: If
260 detect_prio is yes (default), the default priority
261 algorithm is sysfs (except for NetAPP E-Series, where
262 it is alua). If detect_prio is no, the default prior‐
263 ity algorithm is const.
264 prio_args Arguments to pass to to the prio function. This only
266 applies to certain prioritizers:
267 weighted Needs a value of the form "<hbtl|dev‐
269 name|serial|wwn> <regex1> <prio1> <regex2>
270 <prio2> ..."
271 hbtl Regex can be of SCSI H:B:T:L for‐
273 mat. For example: 1:0:.:. ,
274 *:0:0:.
275 devname Regex can be of device name for‐
277 mat. For example: sda , sd.e
278 serial Regex can be of serial number for‐
280 mat. For example: .*J1FR.*324 .
281 The serial can be looked up
282 through sysfs or by running multi‐
283 pathd show paths format "%z". For
284 example: 0395J1FR904324
285 wwn Regex can be of the form
287 "host_wwnn:host_wwpn:tar‐
288 get_wwnn:target_wwpn" these values
289 can be looked up through sysfs or
290 by running multipathd show paths
291 format "%N:%R:%n:%r". For example:
292 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.*
293 , .*:.*:iqn.2009-10.com.red‐
294 hat.msp.lab.ask-06:.*
295 path_latency
297 Needs a value of the form "io_num=<20>
298 base_num=<10>"
299 io_num The number of read IOs sent to the
301 current path continuously, used to
302 calculate the average path
303 latency. Valid Values: Integer,
304 [2, 200].
305 base_num
307 The base number value of logarith‐
308 mic scale, used to partition dif‐
309 ferent priority ranks. Valid Val‐
310 ues: Integer, [2, 10]. And Max
311 average latency value is 100s, min
312 average latency value is 1us. For
313 example: If base_num=10, the paths
314 will be grouped in priority groups
315 with path latency <=1us, (1us,
316 10us], (10us, 100us], (100us,
317 1ms], (1ms, 10ms], (10ms, 100ms],
318 (100ms, 1s], (1s, 10s], (10s,
319 100s], >100s.
320 alua If exclusive_pref_bit is set, paths with
322 the preferred path bit set will always be
323 in their own path group.
324 sysfs If exclusive_pref_bit is set, paths with
326 the preferred path bit set will always be
327 in their own path group.
328 datacore
330 preferredsds
332 (Mandatory) The preferred "SDS
333 name".
334 timeout (Optional) The timeout for the
336 INQUIRY, in ms.
337 iet
339 preferredip=...
341 (Mandatory) Th preferred IP
342 address, in dotted decimal nota‐
343 tion, for iSCSI targets.
344 The default is: <unset>
346 features Specify any device-mapper features to be used. Syntax
348 is num list where num is the number, between 0 and 8,
349 of features in list. Possible values for the feature
350 list are:
351 queue_if_no_path
353 (Deprecated, superseded by no_path_retry)
354 Queue I/O if no path is active. Identical
355 to the no_path_retry with queue value. If
356 both this feature and no_path_retry are
357 set, the latter value takes precedence.
358 See KNOWN ISSUES.
359 pg_init_retries <times>
361 (Since kernel 2.6.24) Number of times to
362 retry pg_init, it must be between 1 and
363 50.
364 pg_init_delay_msecs <msecs>
366 (Since kernel 2.6.38) Number of msecs
367 before pg_init retry, it must be between 0
368 and 60000.
369 queue_mode <mode>
371 (Since kernel 4.8) Select the the queueing
372 mode per multipath device. <mode> can be
373 bio, rq or mq, which corresponds to bio-
374 based, request-based, and block-multiqueue
375 (blk-mq) request-based, respectively. The
376 default depends on the kernel parameter
377 dm_mod.use_blk_mq. It is mq if the latter
378 is set, and rq otherwise.
379 The default is: <unset>
381 path_checker The default method used to determine the paths state.
383 Possible values are:
384 readsector0 (Deprecated) Read the first sector of the
386 device. This checker is being deprecated,
387 please use tur instead.
388 tur Issue a TEST UNIT READY command to the
390 device.
391 emc_clariion
393 (Hardware-dependent) Query the DGC/EMC
394 specific EVPD page 0xC0 to determine the
395 path state for CLARiiON CX/AX and EMC VNX
396 and Unity arrays families.
397 hp_sw (Hardware-dependent) Check the path state
399 for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
400 with Active/Standby mode exclusively.
401 rdac (Hardware-dependent) Check the path state
403 for LSI/Engenio/NetApp RDAC class as
404 NetApp SANtricity E/EF Series, and OEM
405 arrays from IBM DELL SGI STK and SUN.
406 directio (Deprecated) Read the first sector with
408 direct I/O. This checker is being depre‐
409 cated, it could cause spurious path fail‐
410 ures under high load. Please use tur
411 instead.
412 cciss_tur (Hardware-dependent) Check the path state
414 for HP/COMPAQ Smart Array(CCISS) con‐
415 trollers.
416 none Do not check the device, fallback to use
418 the values retrieved from sysfs
419 The default is: tur
421 alias_prefix The user_friendly_names prefix.
423 The default is: mpath
425 failback Tell multipathd how to manage path group failback. To
427 select immediate or a value, it's mandatory that the
428 device has support for a working prioritizer.
429 immediate Immediately failback to the highest prior‐
431 ity pathgroup that contains active paths.
432 manual Do not perform automatic failback.
434 followover Used to deal with multiple computers
436 accessing the same Active/Passive storage
437 devices. Only perform automatic failback
438 when the first path of a pathgroup becomes
439 active. This keeps a cluster node from
440 automatically failing back when another
441 node requested the failover.
442 values > 0 Deferred failback (time to defer in sec‐
444 onds).
445 The default is: manual
447 rr_min_io Number of I/O requests to route to a path before
449 switching to the next in the same path group. This is
450 only for Block I/O(BIO) based multipath and only apply
451 to round-robin path_selector.
452 The default is: 1000
454 rr_min_io_rq Number of I/O requests to route to a path before
456 switching to the next in the same path group. This is
457 only for Request based multipath and only apply to
458 round-robin path_selector.
459 The default is: 1
461 max_fds Specify the maximum number of file descriptors that
463 can be opened by multipath and multipathd. This is
464 equivalent to ulimit -n. A value of max will set this
465 to the system limit from /proc/sys/fs/nr_open. If this
466 is not set, the maximum number of open fds is taken
467 from the calling process. It is usually 1024. To be
468 safe, this should be set to the maximum number of
469 paths plus 32, if that number is greated than 1024.
470 The default is: max
472 rr_weight If set to priorities the multipath configurator will
474 assign path weights as "path prio * rr_min_io". Possi‐
475 ble values are priorities or uniform . Only apply to
476 round-robin path_selector.
477 The default is: uniform
479 no_path_retry Specify what to do when all paths are down. Possible
481 values are:
482 value > 0 Number of retries until disable I/O queue‐
484 ing.
485 fail For immediate failure (no I/O queueing).
487 queue For never stop I/O queueing, similar to
489 queue_if_no_path. See KNOWN ISSUES.
490 The default is: fail
492 queue_without_daemon
494 If set to no , when multipathd stops, queueing will be
495 turned off for all devices. This is useful for
496 devices that set no_path_retry. If a machine is shut
497 down while all paths to a device are down, it is pos‐
498 sible to hang waiting for I/O to return from the
499 device after multipathd has been stopped. Without mul‐
500 tipathd running, access to the paths cannot be
501 restored, and the kernel cannot be told to stop queue‐
502 ing I/O. Setting queue_without_daemon to no , avoids
503 this problem.
504 The default is: no
506 checker_timeout Specify the timeout to use for path checkers and pri‐
508 oritizers that issue SCSI commands with an explicit
509 timeout, in seconds.
510 The default is: in /sys/block/sd<x>/device/timeout
512 flush_on_last_del
514 If set to yes , multipathd will disable queueing when
515 the last path to a device has been deleted.
516 The default is: no
518 user_friendly_names
520 If set to yes , using the bindings file /etc/multi‐
521 path/bindings to assign a persistent and unique alias
522 to the multipath, in the form of mpath<n>. If set to
523 no use the WWID as the alias. In either case this be
524 will be overridden by any specific aliases in the mul‐
525 tipaths section.
526 The default is: no
528 fast_io_fail_tmo Specify the number of seconds the SCSI layer will wait
530 after a problem has been detected on a FC remote port
531 before failing I/O to devices on that remote port.
532 This should be smaller than dev_loss_tmo. Setting this
533 to off will disable the timeout.
534 The default is: in 5
536 dev_loss_tmo Specify the number of seconds the SCSI layer will wait
538 after a problem has been detected on a FC remote port
539 before removing it from the system. This can be set to
540 "infinity" which sets it to the max value of
541 2147483647 seconds, or 68 years. It will be automati‐
542 cally adjusted to the overall retry interval
543 no_path_retry * polling_interval if a number of
544 retries is given with no_path_retry and the overall
545 retry interval is longer than the specified
546 dev_loss_tmo value. The Linux kernel will cap this
547 value to 600 if fast_io_fail_tmo is not set. See KNOWN
548 ISSUES.
549 The default is: 600
551 bindings_file The full pathname of the binding file to be used when
553 the user_friendly_names option is set.
554 The default is: /etc/multipath/bindings
556 wwids_file The full pathname of the WWIDs file, which is used by
558 multipath to keep track of the WWIDs for LUNs it has
559 created multipath devices on in the past.
560 The default is: /etc/multipath/wwids
562 prkeys_file The full pathname of the prkeys file, which is used by
564 multipathd to keep track of the persistent reservation
565 key used for a specific WWID, when reservation_key is
566 set to file.
567 The default is /etc/multipath/prkeys
569 log_checker_err If set to once , multipathd logs the first path
571 checker error at logging level 2. Any later errors are
572 logged at level 3 until the device is restored. If set
573 to always , multipathd always logs the path checker
574 error at logging level 2.
575 The default is: always
577 reservation_key This is the service action reservation key used by
579 mpathpersist. It must be set for all multipath devices
580 using persistent reservations, and it must be the same
581 as the RESERVATION KEY field of the PERSISTENT RESERVE
582 OUT parameter list which contains an 8-byte value pro‐
583 vided by the application client to the device server
584 to identify the I_T nexus. If the --param-aptpl option
585 is used when registering the key with mpathpersist,
586 :aptpl must be appended to the end of the reservation
587 key.
588 Alternatively, this can be set to file, which will
590 store the RESERVATION KEY registered by mpathpersist
591 in the prkeys_file. multipathd will then use this key
592 to register additional paths as they appear. When the
593 registration is removed, the RESERVATION KEY is
594 removed from the prkeys_file. The prkeys file will
595 automatically keep track of whether the key was regis‐
596 tered with --param-aptpl.
597 The default is: <unset>
599 all_tg_pt Set the 'all targets ports' flag when registering keys
601 with mpathpersist. Some arrays automatically set and
602 clear registration keys on all target ports from a
603 host, instead of per target port per host. The
604 ALL_TG_PT flag must be set to successfully use mpath‐
605 persist on these arrays. Setting this option is iden‐
606 tical to calling mpathpersist with --param-alltgpt
607 The default is: no
609 retain_attached_hw_handler
611 (Obsolete for kernels >= 4.3) If set to yes and the
612 SCSI layer has already attached a hardware_handler to
613 the device, multipath will not force the device to use
614 the hardware_handler specified by mutipath.conf. If
615 the SCSI layer has not attached a hardware handler,
616 multipath will continue to use its configured hardware
617 handler.
618 The default is: yes
620 Important Note: Linux kernel 4.3 or newer always
622 behaves as if "retain_attached_hw_handler yes" was
623 set.
624 detect_prio If set to yes , multipath will try to detect if the
626 device supports SCSI-3 ALUA. If so, the device will
627 automatically use the sysfs prioritizer if the
628 required sysf attributes access_state and pre‐
629 ferred_path are supported, or the alua prioritizer if
630 not. If set to no , the prioritizer will be selected
631 as usual.
632 The default is: yes
634 detect_checker if set to yes , multipath will try to detect if the
636 device supports SCSI-3 ALUA. If so, the device will
637 automatically use the tur checker. If set to no , the
638 checker will be selected as usual.
639 The default is: yes
641 force_sync If set to yes , multipathd will call the path checkers
643 in sync mode only. This means that only one checker
644 will run at a time. This is useful in the case where
645 many multipathd checkers running in parallel causes
646 significant CPU pressure.
647 The default is: no
649 strict_timing If set to yes , multipathd will start a new path
651 checker loop after exactly one second, so that each
652 path check will occur at exactly polling_interval sec‐
653 onds. On busy systems path checks might take longer
654 than one second; here the missing ticks will be
655 accounted for on the next round. A warning will be
656 printed if path checks take longer than polling_inter‐
657 val seconds.
658 The default is: no
660 deferred_remove If set to yes , multipathd will do a deferred remove
662 instead of a regular remove when the last path device
663 has been deleted. This means that if the multipath
664 device is still in use, it will be freed when the last
665 user closes it. If path is added to the multipath
666 device before the last user closes it, the deferred
667 remove will be canceled.
668 The default is: no
670 partition_delimiter
672 This parameter controls how multipath chooses the
673 names of partition devices of multipath maps if a mul‐
674 tipath map is renamed (e.g. if a map alias is added or
675 changed). If this parameter is set to a string other
676 than "/UNSET/" (even the empty string), multipath
677 inserts that string between device name and partition
678 number to construct the partition device name. Other‐
679 wise (i.e. if this parameter is unset or has the value
680 "/UNSET/"), the behavior depends on the map name: if
681 it ends in a digit, a "p" is inserted between name and
682 partition number; otherwise, the partition number is
683 simply appended. Distributions may use a non-null
684 default value for this option; in this case, the user
685 must set it to "/UNSET/" to obtain the original
686 <unset> behavior. Use multipath -T to check the cur‐
687 rent settings.
688 The default is: <unset>
690 config_dir If set to anything other than "", multipath will
692 search this directory alphabetically for file ending
693 in ".conf" and it will read configuration information
694 from them, just as if it was in /etc/multipath.conf.
695 config_dir must either be "" or a fully qualified
696 directory name.
697 The default is: /etc/multipath/conf.d/
699 marginal_path_double_failed_time
701 One of the four parameters of supporting path check
702 based on accounting IO error such as intermittent
703 error. When a path failed event occurs twice in mar‐
704 ginal_path_double_failed_time seconds due to an IO
705 error and all the other three parameters are set, mul‐
706 tipathd will fail the path and enqueue this path into
707 a queue of which members are sent a couple of continu‐
708 ous direct reading asynchronous IOs at a fixed sample
709 rate of 10HZ to start IO error accounting process.
710 The default is: no
712 marginal_path_err_sample_time
714 One of the four parameters of supporting path check
715 based on accounting IO error such as intermittent
716 error. If it is set to a value no less than 120, when
717 a path fail event occurs twice in marginal_path_dou‐
718 ble_failed_time second due to an IO error, multipathd
719 will fail the path and enqueue this path into a queue
720 of which members are sent a couple of continuous
721 direct reading asynchronous IOs at a fixed sample rate
722 of 10HZ to start the IO accounting process for the
723 path will last for marginal_path_err_sample_time. If
724 the rate of IO error on a particular path is greater
725 than the marginal_path_err_rate_threshold, then the
726 path will not reinstate for margin‐
727 al_path_err_recheck_gap_time seconds unless there is
728 only one active path. After margin‐
729 al_path_err_recheck_gap_time expires, the path will be
730 requeueed for rechecking. If checking result is good
731 enough, the path will be reinstated.
732 The default is: no
734 marginal_path_err_rate_threshold
736 The error rate threshold as a permillage (1/1000). One
737 of the four parameters of supporting path check based
738 on accounting IO error such as intermittent error.
739 Refer to marginal_path_err_sample_time. If the rate of
740 IO errors on a particular path is greater than this
741 parameter, then the path will not reinstate for mar‐
742 ginal_path_err_recheck_gap_time seconds unless there
743 is only one active path.
744 The default is: no
746 marginal_path_err_recheck_gap_time
748 One of the four parameters of supporting path check
749 based on accounting IO error such as intermittent
750 error. Refer to marginal_path_err_sample_time. If this
751 parameter is set to a positive value, the failed path
752 of which the IO error rate is larger than margin‐
753 al_path_err_rate_threshold will be kept in failed
754 state for marginal_path_err_recheck_gap_time seconds.
755 When marginal_path_err_recheck_gap_time seconds
756 expires, the path will be requeueed for checking. If
757 checking result is good enough, the path will be rein‐
758 stated, or else it will keep failed.
759 The default is: no
761 delay_watch_checks
763 If set to a value greater than 0, multipathd will
764 watch paths that have recently become valid for this
765 many checks. If they fail again while they are being
766 watched, when they next become valid, they will not be
767 used until they have stayed up for delay_wait_checks
768 checks.
769 The default is: no
771 delay_wait_checks
773 If set to a value greater than 0, when a device that
774 has recently come back online fails again within
775 delay_watch_checks checks, the next time it comes back
776 online, it will marked and delayed, and not used until
777 it has passed delay_wait_checks checks.
778 The default is: no
780 find_multipaths This option controls whether multipath and multipathd
782 try to create multipath maps over non-blacklisted
783 devices they encounter. This matters a) when a device
784 is encountered by multipath -u during udev rule pro‐
785 cessing (a device is blocked from further processing
786 by higher layers - such as LVM - if and only if it´s
787 considered a valid multipath device path), and b) when
788 multipathd detects a new device. The following values
789 are possible:
790 strict Both multipath and multipathd treat only
792 such devices as multipath devices which have
793 been part of a multipath map previously, and
794 which are therefore listed in the
795 wwids_file. Users can manually set up multi‐
796 path maps using the multipathd add map com‐
797 mand. Once set up manually, the map is
798 remembered in the wwids file and will be set
799 up automatically in the future.
800 no Multipath behaves like strict. Multipathd
802 behaves like greedy.
803 yes Both multipathd and multipath treat a device
805 as multipath device if the conditions for
806 strict are met, or if at least two non-
807 blacklisted paths with the same WWID have
808 been detected.
809 greedy Both multipathd and multipath treat every
811 non-blacklisted device as multipath device
812 path.
813 smart This differs from find_multipaths yes only
815 in the way it treats new devices for which
816 only one path has been detected yet. When
817 such a device is first encounted in udev
818 rules, it is treated as a multipath device.
819 multipathd waits whether additional paths
820 with the same WWID appears. If that happens,
821 it sets up a multipath map. If it doesn´t
822 happen until a timeout expires, or if set‐
823 ting up the map fails, a new uevent is trig‐
824 gered for the device; at second encounter in
825 the udev rules, the device will be treated
826 as non-multipath and passed on to upper lay‐
827 ers. Note: this may cause delays during
828 device detection if there are single-path
829 devices which aren´t blacklisted.
830 The default is: strict
832 find_multipaths_timeout
834 Timeout, in seconds, to wait for additional paths
835 after detecting the first one, if find_multipaths
836 "smart" (see above) is set. If the value is positive,
837 this timeout is used for all unknown, non-blacklisted
838 devices encountered. If the value is negative (recom‐
839 mended), it's only applied to "known" devices that
840 have an entry in multipath's hardware table, either in
841 the built-in table or in a device section; other
842 ("unknown") devices will use a timeout of only 1 sec‐
843 ond to avoid booting delays. The value 0 means "use
844 the built-in default". If find_multipath has a value
845 other than smart, this option has no effect.
846 The default is: -10 (10s for known and 1s for unknown
848 hardware)
849 uxsock_timeout CLI receive timeout in milliseconds. For larger sys‐
851 tems CLI commands might timeout before the multipathd
852 lock is released and the CLI command can be processed.
853 This will result in errors like "timeout receiving
854 packet" to be returned from CLI commands. In these
855 cases it is recommended to increase the CLI timeout to
856 avoid those issues.
857 The default is: 1000
859 retrigger_tries Sets the number of times multipathd will try to
861 retrigger a uevent to get the WWID.
862 The default is: 3
864 retrigger_delay Sets the amount of time, in seconds, to wait between
866 retriggers.
867 The default is: 10
869 missing_uev_wait_timeout
871 Controls how many seconds multipathd will wait, after
872 a new multipath device is created, to receive a change
873 event from udev for the device, before automatically
874 enabling device reloads. Usually multipathd will delay
875 reloads on a device until it receives a change uevent
876 from the initial table load.
877 The default is: 30
879 skip_kpartx If set to yes , kpartx will not automatically create
881 partitions on the device.
882 The default is: no
884 disable_changed_wwids
886 If set to yes, multipathd will check the path wwid on
887 change events, and if it has changed from the wwid of
888 the multipath device, multipathd will disable access
889 to the path until the wwid changes back.
890 The default is: no
892 remove_retries This sets how may times multipath will retry removing
894 a device that is in-use. Between each attempt, multi‐
895 path will sleep 1 second.
896 The default is: 0
898 max_sectors_kb Sets the max_sectors_kb device parameter on all path
900 devices and the multipath device to the specified
901 value.
902 The default is: <device dependent>
904 ghost_delay Sets the number of seconds that multipath will wait
906 after creating a device with only ghost paths before
907 marking it ready for use in systemd. This gives the
908 active paths time to appear before the multipath runs
909 the hardware handler to switch the ghost paths to
910 active ones. Setting this to 0 or on makes multipath
911 immediately mark a device with only ghost paths as
912 ready.
913 The default is no
915
917 The blacklist section is used to exclude specific devices from the mul‐
918 tipath topology. It is most commonly used to exclude local disks or
919 non-disk devices (such as LUNs for the storage array controller) from
920 being handled by multipath-tools.
921 The blacklist_exceptions section is used to revert the actions of the
923 blacklist section. This allows one to selectively include ("whitelist")
924 devices which would normally be excluded via the blacklist section. A
925 common usage is to blacklist "everything" using a catch-all regular
926 expression, and create specific blacklist_exceptions entries for those
927 devices that should be handled by multipath-tools.
928 The following keywords are recognized in both sections. The defaults
930 are empty unless explicitly stated.
931 devnode Regular expression matching the device nodes to be
933 excluded/included.
934 The default blacklist consists of the regular expres‐
936 sions "^(ram|raw|loop|fd|md|dm-|sr|scd|st|dcss‐
937 blk)[0-9]" and "^(td|hd|vd)[a-z]". This causes virtual
938 devices, non-disk devices, and some other device types
939 to be excluded from multipath handling by default.
940 wwid Regular expression for the World Wide Identifier of a
942 device to be excluded/included.
943 device Subsection for the device description. This subsection
945 recognizes the vendor and product keywords. Both are
946 regular expressions. For a full description of these
947 keywords please see the devices section description.
948 property Regular expression for an udev property. All devices
950 that have matching udev properties will be
951 excluded/included. The handling of the property key‐
952 word is special, because if a property black‐
953 list_exception is set, devices must have at least one
954 whitelisted udev property; otherwise they're treated
955 as blacklisted, and the message "blacklisted, udev
956 property missing" is displayed in the logs. For exam‐
957 ple, setting the property blacklist_exception to
958 (SCSI_IDENT_|ID_WWN), will cause well-behaved SCSI
959 devices and devices that provide a WWN (World Wide
960 Number) to be included, and all others to be excluded.
961 This works to exclude most non-multipathable devices.
962 protocol Regular expression for the protocol of a device to be
964 excluded/included.
965 The protocol strings that multipath recognizes are
967 scsi:fcp, scsi:spi, scsi:ssa, scsi:sbp, scsi:srp,
968 scsi:iscsi, scsi:sas, scsi:adt, scsi:ata, scsi:unspec,
969 ccw, cciss, nvme, and undef. The protocol that a path
970 is using can be viewed by running multipathd show
971 paths format "%d %P"
972 For every device, these 5 blacklist criteria are evaluated in the the
974 order "property, devnode, device, protocol, wwid". If a device turns
975 out to be blacklisted by any criterion, it's excluded from handling by
976 multipathd, and the later criteria aren't evaluated any more. For each
977 criterion, the whitelist takes precedence over the blacklist if a
978 device matches both.
979 Note: Besides the blacklist and whitelist, other configuration options
981 such as find_multipaths have an impact on whether or not a given device
982 is handled by multipath-tools.
983
985 The multipaths section allows setting attributes of multipath maps. The
986 attributes that are set via the multipaths section (see list below)
987 take precedence over all other configuration settings, including those
988 from the overrides section.
989 The only recognized attribute for the multipaths section is the multi‐
991 path subsection. If there are multiple multipath subsections matching a
992 given WWID, the contents of these sections are merged, and settings
993 from later entries take precedence.
994 The multipath subsection recognizes the following attributes:
996 wwid (Mandatory) World Wide Identifier. Detected multipath
998 maps are matched agains this attribute. Note that,
999 unlike the wwid attribute in the blacklist section,
1000 this is not a regular expression or a substring; WWIDs
1001 must match exactly inside the multipaths section.
1002 alias Symbolic name for the multipath map. This takes prece‐
1004 dence over a an entry for the same WWID in the bind‐
1005 ings_file.
1006 The following attributes are optional; if not set the default values
1008 are taken from the overrides, devices, or defaults section:
1009 path_grouping_policy
1011 path_selector
1012 prio
1013 prio_args
1014 failback
1015 rr_weight
1016 no_path_retry
1017 rr_min_io
1018 rr_min_io_rq
1019 flush_on_last_del
1020 features
1021 reservation_key
1022 user_friendly_names
1023 deferred_remove
1024 marginal_path_err_sample_time
1025 marginal_path_err_rate_threshold
1026 marginal_path_err_recheck_gap_time
1027 marginal_path_double_failed_time
1028 delay_watch_checks
1029 delay_wait_checks
1030 skip_kpartx
1031 max_sectors_kb
1032 ghost_delay
1033
1035 multipath-tools have a built-in device table with reasonable defaults
1036 for more than 100 known multipath-capable storage devices. The devices
1037 section can be used to override these settings. If there are multiple
1038 matches for a given device, the attributes of all matching entries are
1039 applied to it. If an attribute is specified in several matching device
1040 subsections, later entries take precedence. Thus, entries in files
1041 under config_dir (in reverse alphabetical order) have the highest
1042 precedence, followed by entries in multipath.conf; the built-in hard‐
1043 ware table has the lowest precedence. Inside a configuration file,
1044 later entries have higher precedence than earlier ones.
1045 The only recognized attribute for the devices section is the device
1047 subsection. Devices detected in the system are matched against the
1048 device entries using the vendor, product, and revision fields, which
1049 are all POSIX Extended regular expressions (see regex(7)).
1050 The vendor, product, and revision fields that multipath or multipathd
1052 detect for devices in a system depend on the device type. For SCSI
1053 devices, they correspond to the respective fields of the SCSI INQUIRY
1054 page. In general, the command 'multipathd show paths format "%d %s"'
1055 command can be used to see the detected properties for all devices in
1056 the system.
1057 The device subsection recognizes the following attributes:
1059 vendor (Mandatory) Regular expression to match the vendor
1061 name.
1062 product (Mandatory) Regular expression to match the product
1064 name.
1065 revision Regular expression to match the product revision. If
1067 not specified, any revision matches.
1068 product_blacklist
1070 Products with the given vendor matching this string
1071 are blacklisted. This is equivalent to a device entry
1072 in the blacklist section with the vendor attribute set
1073 to this entry's vendor, and the product attribute set
1074 to the value of product_blacklist.
1075 alias_prefix The user_friendly_names prefix to use for this device
1077 type, instead of the default "mpath".
1078 hardware_handler The hardware handler to use for this device type. The
1080 following hardware handler are implemented:
1081 1 emc (Hardware-dependent) Hardware handler for
1083 DGC class arrays as CLARiiON CX/AX and EMC
1084 VNX and Unity families.
1085 1 rdac (Hardware-dependent) Hardware handler for
1087 LSI/Engenio/NetApp RDAC class as NetApp
1088 SANtricity E/EF Series, and OEM arrays
1089 from IBM DELL SGI STK and SUN.
1090 1 hp_sw (Hardware-dependent) Hardware handler for
1092 HP/COMPAQ/DEC HSG80 and MSA/HSV arrays
1093 with Active/Standby mode exclusively.
1094 1 alua (Hardware-dependent) Hardware handler for
1096 SCSI-3 ALUA compatible arrays.
1097 The default is: <unset>
1099 Important Note: Linux kernels 4.3 and newer automati‐
1101 cally attach a device handler to known devices (which
1102 includes all devices supporting SCSI-3 ALUA) and dis‐
1103 allow changing the handler afterwards. Setting hard‐
1104 ware_handler for such devices on these kernels has no
1105 effect.
1106 The following attributes are optional; if not set the default values
1108 are taken from the defaults section:
1109 path_grouping_policy
1111 uid_attribute
1112 path_selector
1113 path_checker
1114 prio
1115 prio_args
1116 features
1117 failback
1118 rr_weight
1119 no_path_retry
1120 rr_min_io
1121 rr_min_io_rq
1122 fast_io_fail_tmo
1123 dev_loss_tmo
1124 flush_on_last_del
1125 retain_attached_hw_handler
1126 detect_prio
1127 detect_checker
1128 deferred_remove
1129 marginal_path_err_sample_time
1130 marginal_path_err_rate_threshold
1131 marginal_path_err_recheck_gap_time
1132 marginal_path_double_failed_time
1133 delay_watch_checks
1134 delay_wait_checks
1135 skip_kpartx
1136 max_sectors_kb
1137 ghost_delay
1138
1140 The overrides section recognizes the following optional attributes; if
1141 not set the values are taken from the devices or defaults sections:
1142 path_grouping_policy
1144 uid_attribute
1145 getuid_callout
1146 path_selector
1147 path_checker
1148 alias_prefix
1149 features
1150 prio
1151 prio_args
1152 failback
1153 rr_weight
1154 no_path_retry
1155 rr_min_io
1156 rr_min_io_rq
1157 flush_on_last_del
1158 fast_io_fail_tmo
1159 dev_loss_tmo
1160 user_friendly_names
1161 retain_attached_hw_handler
1162 detect_prio
1163 detect_checker
1164 deferred_remove
1165 marginal_path_err_sample_time
1166 marginal_path_err_rate_threshold
1167 marginal_path_err_recheck_gap_time
1168 marginal_path_double_failed_time
1169 delay_watch_checks
1170 delay_wait_checks
1171 skip_kpartx
1172 ghost_delay
1173
1175 Multipath uses a World Wide Identification (WWID) to determine which
1176 paths belong to the same device. Each path presenting the same WWID is
1177 assumed to point to the same device.
1178 The WWID is generated by four methods (in the order of preference):
1180 uid_attrs The WWID is derived from udev attributes by matching
1182 the device node name. See description of uid_attrs in
1183 the defaults section above.
1184 getuid_callout Use the specified external program; cf getuid_callout
1186 above. Care should be taken when using this method;
1187 the external program needs to be loaded from disk for
1188 execution, which might lead to deadlock situations in
1189 an all-paths-down scenario.
1190 uid_attribute Use the value of the specified udev attribute; cf
1192 uid_attribute above. This method is preferred to
1193 getuid_callout as multipath does not need to call any
1194 external programs here. However, under certain circum‐
1195 stances udev might not be able to generate the
1196 requested variable.
1197 vpd_pg83 If none of the getuid_callout or uid_attribute parame‐
1199 ters are present multipath will try to use the sysfs
1200 attribute vpd_pg83 to generate the WWID.
1201
1203 The usage of queue_if_no_path option can lead to D state processes
1204 being hung and not killable in situations where all the paths to the
1205 LUN go offline. It is advisable to use the no_path_retry option
1206 instead.
1207 The use of queue_if_no_path or no_path_retry might lead to a deadlock
1209 if the dev_loss_tmo setting results in a device being removed while I/O
1210 is still queued. The multipath daemon will update the dev_loss_tmo set‐
1211 ting accordingly to avoid this deadlock. Hence if both values are spec‐
1212 ified the order of precedence is no_path_retry, queue_if_no_path,
1213 dev_loss_tmo.
1214
1216 udev(8), dmsetup(8), multipath(8), multipathd(8).
1217
1219 multipath-tools was developed by Christophe Varoqui, <christophe.varo‐
1220 qui@opensvc.com> and others.
1221Linux 2018-05-21 MULTIPATH.CONF(5)