0fe8461d7b161192275706da8e3fdc9c1203aa24
[multipath-tools/.git] / multipath / multipath.conf.5
1 .\" ----------------------------------------------------------------------------
2 .\" Update the date below if you make any significant change.
3 .\" Make sure there are no errors with:
4 .\" groff -z -wall -b -e -t multipath/multipath.conf.5
5 .\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.conf.5 >/dev/null
6 .\"
7 .\" TODO: Look for XXX and ???
8 .\"
9 .\" ----------------------------------------------------------------------------
10 .
11 .TH MULTIPATH.CONF 5 2018-05-21 Linux
12 .
13 .
14 .\" ----------------------------------------------------------------------------
15 .SH NAME
16 .\" ----------------------------------------------------------------------------
17 .
18 multipath.conf \- multipath daemon configuration file.
19 .
20 .
21 .\" ----------------------------------------------------------------------------
22 .SH DESCRIPTION
23 .\" ----------------------------------------------------------------------------
24 .
25 .B "/etc/multipath.conf"
26 is the configuration file for the multipath daemon. It is used to
27 overwrite the built-in configuration table of \fBmultipathd\fP.
28 Any line whose first non-white-space character is a '#' is considered
29 a comment line. Empty lines are ignored.
30 .PP
31 Currently used multipathd configuration can be displayed with the \fBmultipath -t\fR
32 or \fBmultipathd show config\fR command.
33 .
34 .
35 .\" ----------------------------------------------------------------------------
36 .SH SYNTAX
37 .\" ----------------------------------------------------------------------------
38 .
39 The configuration file contains entries of the form:
40 .RS
41 .nf
42 .ft B
43 .sp
44 <section> {
45 .RS
46 .ft B
47 <attribute> <value>
48 .I "..."
49 .ft B
50 <subsection> {
51 .RS
52 .ft B
53 <attribute> <value>
54 .I "..."
55 .RE
56 .ft B
57 }
58 .RE
59 .ft B
60 }
61 .ft R
62 .fi
63 .RE
64 .LP
65 Each \fIsection\fP contains one or more attributes or subsections. The
66 recognized keywords for attributes or subsections depend on the
67 section in which they occur.
68 .LP
69 .
70 \fB<attribute>\fR and \fB<value>\fR must be on a single line.
71 \fB<attribute>\fR is one of the keywords listed in this man page.
72 \fB<value>\fR is either a simple word (containing no whitespace and none of the
73 characters '\(dq', '#', and '!') or \fIone\fR string enclosed in double
74 quotes ("..."). Outside a quoted string, text starting with '#', and '!' is
75 regarded as a comment and ignored until the end of the line. Inside a quoted
76 string, '#' and '!' are normal characters, and whitespace is preserved.
77 To represent a double quote character inside a double quoted string, use two
78 consecutive double quotes ('""'). Thus '2.5\(dq SSD' can be written as "2.5"" SSD".
79 .LP
80 .
81 Opening braces ('{') must follow the (sub)section name on the same line. Closing
82 braces ('}') that mark the end of a (sub)section must be the only non-whitespace
83 character on the line. Whitespace is ignored except inside double quotes, thus
84 the indentation shown in the above example is helpful for human readers but
85 not mandatory.
86 .LP
87 .
88 .LP
89 .B Note on regular expressions:
90 The \fImultipath.conf\fR syntax allows many attribute values to be specified as POSIX
91 Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions
92 are \fBcase sensitive\fR and \fBnot anchored\fR, thus the expression "bar" matches "barbie",
93 "rhabarber", and "wunderbar", but not "Barbie". To avoid unwanted substring
94 matches, standard regular expression syntax using the special characters "^" and "$" can be used.
95 .
96 .LP
97 .
98 The following \fIsection\fP keywords are recognized:
99 .TP 17
100 .B defaults
101 This section defines default values for attributes which are used
102 whenever no values are given in the appropriate device or multipath
103 sections.
104 .TP
105 .B blacklist
106 This section defines which devices should be excluded from the
107 multipath topology discovery.
108 .TP
109 .B blacklist_exceptions
110 This section defines which devices should be included in the
111 multipath topology discovery, despite being listed in the
112 \fIblacklist\fR section.
113 .TP
114 .B multipaths
115 This section defines the multipath topologies. They are indexed by a
116 \fIWorld Wide Identifier\fR(WWID). For details on the WWID generation
117 see section \fIWWID generation\fR below. Attributes set in this section take
118 precedence over all others.
119 .TP
120 .B devices
121 This section defines the device-specific settings. Devices are identified by
122 vendor, product, and revision.
123 .TP
124 .B overrides
125 This section defines values for attributes that should override the
126 device-specific settings for all devices.
127 .RE
128 .LP
129 .
130 .
131 .\" ----------------------------------------------------------------------------
132 .SH "defaults section"
133 .\" ----------------------------------------------------------------------------
134 .
135 The \fIdefaults\fR section recognizes the following keywords:
136 .
137 .
138 .TP 17
139 .B verbosity
140 Default verbosity. Higher values increase the verbosity level. Valid
141 levels are between 0 and 6.
142 .RS
143 .TP
144 The default is: \fB2\fR
145 .RE
146 .
147 .
148 .TP
149 .B polling_interval
150 Interval between two path checks in seconds. For properly functioning paths,
151 the interval between checks will gradually increase to \fImax_polling_interval\fR.
152 This value will be overridden by the \fIWatchdogSec\fR
153 setting in the multipathd.service definition if systemd is used.
154 .RS
155 .TP
156 The default is: \fB5\fR
157 .RE
158 .
159 .
160 .TP
161 .B max_polling_interval
162 Maximal interval between two path checks in seconds.
163 .RS
164 .TP
165 The default is: \fB4 * polling_interval\fR
166 .RE
167 .
168 .
169 .TP
170 .B reassign_maps
171 Enable reassigning of device-mapper maps. With this option multipathd
172 will remap existing device-mapper maps to always point to multipath
173 device, not the underlying block devices. Possible values are
174 \fIyes\fR and \fIno\fR.
175 .RS
176 .TP
177 The default is: \fBno\fR
178 .RE
179 .
180 .
181 .TP
182 .B multipath_dir
183 Directory where the dynamic shared objects are stored. Defined at compile time,
184 commonly \fI/lib64/multipath/\fR or \fI/lib/multipath/\fR.
185 .RS
186 .TP
187 The default is: \fB<system dependent>\fR
188 .RE
189 .
190 .
191 .TP
192 .B path_selector
193 The default path selector algorithm to use; they are offered by the
194 kernel multipath target. There are three selector algorithms:
195 .RS
196 .TP 12
197 .I "round-robin 0"
198 Loop through every path in the path group, sending the same amount of I/O to
199 each. Some aspects of behavior can be controlled with the attributes:
200 \fIrr_min_io\fR, \fIrr_min_io_rq\fR and \fIrr_weight\fR.
201 .TP
202 .I "queue-length 0"
203 (Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on the amount
204 of outstanding I/O to the path.
205 .TP
206 .I "service-time 0"
207 (Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on the amount
208 of outstanding I/O to the path and its relative throughput.
209 .TP
210 The default is: \fBservice-time 0\fR
211 .RE
212 .
213 .
214 .TP
215 .B path_grouping_policy
216 The default path grouping policy to apply to unspecified
217 multipaths. Possible values are:
218 .RS
219 .TP 12
220 .I failover
221 One path per priority group.
222 .TP
223 .I multibus
224 All paths in one priority group.
225 .TP
226 .I group_by_serial
227 One priority group per serial number.
228 .TP
229 .I group_by_prio
230 One priority group per priority value. Priorities are determined by
231 callout programs specified as a global, per-controller or
232 per-multipath option in the configuration file.
233 .TP
234 .I group_by_node_name
235 One priority group per target node name. Target node names are fetched
236 in \fI/sys/class/fc_transport/target*/node_name\fR.
237 .TP
238 The default is: \fBfailover\fR
239 .RE
240 .
241 .
242 .TP
243 .B uid_attrs
244 The udev attribute providing a unique path identifier for corresponding
245 type of path devices. If this field is configured and matched with type
246 of device, it would override any other methods providing for device
247 unique identifier in config file, and it would activate merging uevents
248 according to the identifier to promote effiecncy in processing uevents.
249 It has no default value, if you want to identify path by udev attribute
250 and to activate merging uevents for SCSI and DASD devices, you can set
251 its value as: \fIuid_attrs "sd:ID_SERIAL dasd:ID_UID"\fR.
252 .RS
253 .TP
254 The default is: \fB<unset>\fR
255 .RE
256 .
257 .
258 .TP
259 .B uid_attribute
260 The udev attribute providing a unique path identifier.
261 .RS
262 .TP
263 The default is: for SCSI devices \fBID_SERIAL\fR
264 .TP
265 The default is: for DASD devices \fBID_UID\fR
266 .TP
267 The default is: for NVME devices \fBID_WWN\fR
268 .RE
269 .
270 .
271 .TP
272 .B getuid_callout
273 (Superseded by \fIuid_attribute\fR) The default program and args to callout
274 to obtain a unique path identifier. Should be specified with an absolute path.
275 .RS
276 .TP
277 The default is: \fB<unset>\fR
278 .RE
279 .
280 .
281 .TP
282 .B prio
283 The name of the path priority routine. The specified routine
284 should return a numeric value specifying the relative priority
285 of this path. Higher number have a higher priority.
286 \fI"none"\fR is a valid value. Currently the following path priority routines
287 are implemented:
288 .RS
289 .TP 12
290 .I const
291 Return a constant priority of \fI1\fR.
292 .TP
293 .I sysfs
294 Use the sysfs attributes \fIaccess_state\fR and \fIpreferred_path\fR to
295 generate the path priority. This prioritizer accepts the optional prio_arg
296 \fIexclusive_pref_bit\fR.
297 .TP
298 .I emc
299 (Hardware-dependent)
300 Generate the path priority for DGC class arrays as CLARiiON CX/AX and
301 EMC VNX and Unity families.
302 .TP
303 .I alua
304 (Hardware-dependent)
305 Generate the path priority based on the SCSI-3 ALUA settings. This prioritizer
306 accepts the optional prio_arg \fIexclusive_pref_bit\fR.
307 .TP
308 .I ontap
309 (Hardware-dependent)
310 Generate the path priority for NetApp ONTAP class and OEM arrays as IBM NSeries.
311 .TP
312 .I rdac
313 (Hardware-dependent)
314 Generate the path priority for LSI/Engenio/NetApp RDAC class as NetApp SANtricity
315 E/EF Series, and OEM arrays from IBM DELL SGI STK and SUN.
316 .TP
317 .I hp_sw
318 (Hardware-dependent)
319 Generate the path priority for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
320 Active/Standby mode exclusively.
321 .TP
322 .I hds
323 (Hardware-dependent)
324 Generate the path priority for Hitachi AMS families of arrays other than AMS 2000.
325 .TP
326 .I random
327 Generate a random priority between 1 and 10.
328 .TP
329 .I weightedpath
330 Generate the path priority based on the regular expression and the
331 priority provided as argument. Requires prio_args keyword.
332 .TP
333 .I path_latency
334 Generate the path priority based on a latency algorithm.
335 Requires prio_args keyword.
336 .TP
337 .I ana
338 (Hardware-dependent)
339 Generate the path priority based on the NVMe ANA settings.
340 .TP
341 .I datacore
342 (Hardware-dependent)
343 Generate the path priority for some DataCore storage arrays. Requires prio_args
344 keyword.
345 .TP
346 .I iet
347 (iSCSI only)
348 Generate path priority for iSCSI targets based on IP address. Requires
349 prio_args keyword.
350 .PP
351 The default depends on the \fBdetect_prio\fR setting: If \fBdetect_prio\fR is
352 \fByes\fR (default), the default priority algorithm is \fBsysfs\fR (except for
353 NetAPP E-Series, where it is \fBalua\fR). If \fBdetect_prio\fR is
354 \fBno\fR, the default priority algorithm is \fBconst\fR.
355 .RE
356 .
357 .
358 .TP
359 .B prio_args
360 Arguments to pass to to the prio function. This only applies to certain
361 prioritizers:
362 .RS
363 .TP 12
364 .I weighted
365 Needs a value of the form
366 \fI"<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> ..."\fR
367 .RS
368 .TP 8
369 .I hbtl
370 Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
371 .TP
372 .I devname
373 Regex can be of device name format. For example: sda , sd.e
374 .TP
375 .I serial
376 Regex can be of serial number format. For example: .*J1FR.*324 . The serial can
377 be looked up through sysfs or by running multipathd show paths format "%z". For
378 example: 0395J1FR904324
379 .TP
380 .I wwn
381 Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
382 these values can be looked up through sysfs or by running \fImultipathd show paths format
383 "%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*
384 .RE
385 .TP 12
386 .I path_latency
387 Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR"
388 .RS
389 .TP 8
390 .I io_num
391 The number of read IOs sent to the current path continuously, used to calculate the average path latency.
392 Valid Values: Integer, [2, 200].
393 .TP
394 .I base_num
395 The base number value of logarithmic scale, used to partition different priority ranks. Valid Values: Integer,
396 [2, 10]. And Max average latency value is 100s, min average latency value is 1us.
397 For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us],
398 (10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s.
399 .RE
400 .TP 12
401 .I alua
402 If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
403 set will always be in their own path group.
404 .TP
405 .I sysfs
406 If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
407 set will always be in their own path group.
408 .TP
409 .I datacore
410 .RS
411 .TP 8
412 .I preferredsds
413 (Mandatory) The preferred "SDS name".
414 .TP
415 .I timeout
416 (Optional) The timeout for the INQUIRY, in ms.
417 .RE
418 .TP 12
419 .I iet
420 .RS
421 .TP 8
422 .I preferredip=...
423 (Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets.
424 .RE
425 .TP
426 The default is: \fB<unset>\fR
427 .RE
428 .
429 .
430 .TP
431 .B features
432 Specify any device-mapper features to be used. Syntax is \fInum list\fR
433 where \fInum\fR is the number, between 0 and 8, of features in \fIlist\fR.
434 Possible values for the feature list are:
435 .RS
436 .TP 12
437 .I queue_if_no_path
438 (Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active.
439 Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
440 feature and \fIno_path_retry\fR are set, the latter value takes
441 precedence. See KNOWN ISSUES.
442 .TP
443 .I pg_init_retries <times>
444 (Since kernel 2.6.24) Number of times to retry pg_init, it must be between 1 and 50.
445 .TP
446 .I pg_init_delay_msecs <msecs>
447 (Since kernel 2.6.38) Number of msecs before pg_init retry, it must be between 0 and 60000.
448 .TP
449 .I queue_mode <mode>
450 (Since kernel 4.8) Select the the queueing mode per multipath device.
451 <mode> can be \fIbio\fR, \fIrq\fR or \fImq\fR, which corresponds to
452 bio-based, request-based, and block-multiqueue (blk-mq) request-based,
453 respectively.
454 The default depends on the kernel parameter \fBdm_mod.use_blk_mq\fR. It is
455 \fImq\fR if the latter is set, and \fIrq\fR otherwise.
456 .TP
457 The default is: \fB<unset>\fR
458 .RE
459 .
460 .
461 .TP
462 .B path_checker
463 The default method used to determine the paths state. Possible values
464 are:
465 .RS
466 .TP 12
467 .I readsector0
468 (Deprecated) Read the first sector of the device. This checker is being
469 deprecated, please use \fItur\fR instead.
470 .TP
471 .I tur
472 Issue a \fITEST UNIT READY\fR command to the device.
473 .TP
474 .I emc_clariion
475 (Hardware-dependent)
476 Query the DGC/EMC specific EVPD page 0xC0 to determine the path state
477 for CLARiiON CX/AX and EMC VNX and Unity arrays families.
478 .TP
479 .I hp_sw
480 (Hardware-dependent)
481 Check the path state for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
482 Active/Standby mode exclusively.
483 .TP
484 .I rdac
485 (Hardware-dependent)
486 Check the path state for LSI/Engenio/NetApp RDAC class as NetApp SANtricity E/EF
487 Series, and OEM arrays from IBM DELL SGI STK and SUN.
488 .TP
489 .I directio
490 (Deprecated) Read the first sector with direct I/O. This checker is being
491 deprecated, it could cause spurious path failures under high load.
492 Please use \fItur\fR instead.
493 .TP
494 .I cciss_tur
495 (Hardware-dependent)
496 Check the path state for HP/COMPAQ Smart Array(CCISS) controllers.
497 .TP
498 .I none
499 Do not check the device, fallback to use the values retrieved from sysfs
500 .TP
501 The default is: \fBtur\fR
502 .RE
503 .
504 .
505 .TP
506 .B alias_prefix
507 The \fIuser_friendly_names\fR prefix.
508 .RS
509 .TP
510 The default is: \fBmpath\fR
511 .RE
512 .
513 .
514 .TP
515 .B failback
516 Tell multipathd how to manage path group failback.
517 To select \fIimmediate\fR or a \fIvalue\fR, it's mandatory that the device
518 has support for a working prioritizer.
519 .RS
520 .TP 12
521 .I immediate
522 Immediately failback to the highest priority pathgroup that contains
523 active paths.
524 .TP
525 .I manual
526 Do not perform automatic failback.
527 .TP
528 .I followover
529 Used to deal with multiple computers accessing the same Active/Passive storage
530 devices. Only perform automatic failback when the first path of a pathgroup
531 becomes active. This keeps a cluster node from automatically failing back when
532 another node requested the failover.
533 .TP
534 .I values > 0
535 Deferred failback (time to defer in seconds).
536 .TP
537 The default is: \fBmanual\fR
538 .RE
539 .
540 .
541 .TP
542 .B  rr_min_io
543 Number of I/O requests to route to a path before switching to the next in the
544 same path group. This is only for \fIBlock I/O\fR(BIO) based multipath and
545 only apply to \fIround-robin\fR path_selector.
546 .RS
547 .TP
548 The default is: \fB1000\fR
549 .RE
550 .
551 .
552 .TP
553 .B rr_min_io_rq
554 Number of I/O requests to route to a path before switching to the next in the
555 same path group. This is only for \fIRequest\fR based multipath and
556 only apply to \fIround-robin\fR path_selector.
557 .RS
558 .TP
559 The default is: \fB1\fR
560 .RE
561 .
562 .
563 .TP
564 .B max_fds
565 Specify the maximum number of file descriptors that can be opened by multipath
566 and multipathd. This is equivalent to ulimit \-n. A value of \fImax\fR will set
567 this to the system limit from \fI/proc/sys/fs/nr_open\fR. If this is not set, the
568 maximum number of open fds is taken from the calling process. It is usually
569 1024. To be safe, this should be set to the maximum number of paths plus 32,
570 if that number is greated than 1024.
571 .RS
572 .TP
573 The default is: \fBmax\fR
574 .RE
575 .
576 .
577 .TP
578 .B rr_weight
579 If set to \fIpriorities\fR the multipath configurator will assign path weights
580 as "path prio * rr_min_io". Possible values are
581 .I priorities
582 or
583 .I uniform .
584 Only apply to \fIround-robin\fR path_selector.
585 .RS
586 .TP
587 The default is: \fBuniform\fR
588 .RE
589 .
590 .
591 .TP
592 .B no_path_retry
593 Specify what to do when all paths are down. Possible values are:
594 .RS
595 .TP 12
596 .I value > 0
597 Number of retries until disable I/O queueing.
598 .TP
599 .I fail
600 For immediate failure (no I/O queueing).
601 .TP
602 .I queue
603 For never stop I/O queueing, similar to \fIqueue_if_no_path\fR. See KNOWN ISSUES.
604 .TP
605 The default is: \fBfail\fR
606 .RE
607 .
608 .
609 .TP
610 .B queue_without_daemon
611 If set to
612 .I no
613 , when multipathd stops, queueing will be turned off for all devices.
614 This is useful for devices that set no_path_retry. If a machine is
615 shut down while all paths to a device are down, it is possible to hang waiting
616 for I/O to return from the device after multipathd has been stopped. Without
617 multipathd running, access to the paths cannot be restored, and the kernel
618 cannot be told to stop queueing I/O. Setting queue_without_daemon to
619 .I no
620 , avoids this problem.
621 .RS
622 .TP
623 The default is: \fBno\fR
624 .RE
625 .
626 .
627 .TP
628 .B checker_timeout
629 Specify the timeout to use for path checkers and prioritizers that issue SCSI
630 commands with an explicit timeout, in seconds.
631 .RS
632 .TP
633 The default is: in \fB/sys/block/sd<x>/device/timeout\fR
634 .RE
635 .
636 .
637 .TP
638 .B flush_on_last_del
639 If set to
640 .I yes
641 , multipathd will disable queueing when the last path to a device has been
642 deleted.
643 .RS
644 .TP
645 The default is: \fBno\fR
646 .RE
647 .
648 .
649 .TP
650 .B user_friendly_names
651 If set to
652 .I yes
653 , using the bindings file \fI/etc/multipath/bindings\fR to assign a persistent
654 and unique alias to the multipath, in the form of mpath<n>. If set to
655 .I no
656 use the WWID as the alias. In either case this be will
657 be overridden by any specific aliases in the \fImultipaths\fR section.
658 .RS
659 .TP
660 The default is: \fBno\fR
661 .RE
662 .
663 .
664 .TP
665 .B fast_io_fail_tmo
666 Specify the number of seconds the SCSI layer will wait after a problem has been
667 detected on a FC remote port before failing I/O to devices on that remote port.
668 This should be smaller than dev_loss_tmo. Setting this to
669 .I off
670 will disable the timeout.
671 .RS
672 .TP
673 The default is: in \fB5\fR
674 .RE
675 .
676 .
677 .TP
678 .B dev_loss_tmo
679 Specify the number of seconds the SCSI layer will wait after a problem has
680 been detected on a FC remote port before removing it from the system. This
681 can be set to "infinity" which sets it to the max value of 2147483647
682 seconds, or 68 years. It will be automatically adjusted to the overall
683 retry interval \fIno_path_retry\fR * \fIpolling_interval\fR
684 if a number of retries is given with \fIno_path_retry\fR and the
685 overall retry interval is longer than the specified \fIdev_loss_tmo\fR value.
686 The Linux kernel will cap this value to \fI600\fR if \fIfast_io_fail_tmo\fR
687 is not set. See KNOWN ISSUES.
688 .RS
689 .TP
690 The default is: \fB600\fR
691 .RE
692 .
693 .
694 .TP
695 .B bindings_file
696 The full pathname of the binding file to be used when the user_friendly_names
697 option is set.
698 .RS
699 .TP
700 The default is: \fB/etc/multipath/bindings\fR
701 .RE
702 .
703 .
704 .TP
705 .B wwids_file
706 The full pathname of the WWIDs file, which is used by multipath to keep track
707 of the WWIDs for LUNs it has created multipath devices on in the past.
708 .RS
709 .TP
710 The default is: \fB/etc/multipath/wwids\fR
711 .RE
712 .
713 .
714 .TP
715 .B prkeys_file
716 The full pathname of the prkeys file, which is used by multipathd to keep
717 track of the persistent reservation key used for a specific WWID, when
718 \fIreservation_key\fR is set to \fBfile\fR.
719 .RS
720 .TP
721 The default is \fB/etc/multipath/prkeys\fR
722 .RE
723 .
724 .
725 .TP
726 .B log_checker_err
727 If set to
728 .I once
729 , multipathd logs the first path checker error at logging level 2. Any later
730 errors are logged at level 3 until the device is restored. If set to
731 .I always
732 , multipathd always logs the path checker error at logging level 2.
733 .RS
734 .TP
735 The default is: \fBalways\fR
736 .RE
737 .
738 .
739 .TP
740 .B reservation_key
741 This is the service action reservation key used by mpathpersist. It must be
742 set for all multipath devices using persistent reservations, and it must be
743 the same as the RESERVATION KEY field of the PERSISTENT RESERVE OUT parameter
744 list which contains an 8-byte value provided by the application client to the
745 device server to identify the I_T nexus. If the \fI--param-aptpl\fR option is
746 used when registering the key with mpathpersist, \fB:aptpl\fR must be appended
747 to the end of the reservation key.
748 .RS
749 .PP
750 Alternatively, this can be set to \fBfile\fR, which will store the RESERVATION
751 KEY registered by mpathpersist in the \fIprkeys_file\fR. multipathd will then
752 use this key to register additional paths as they appear.  When the
753 registration is removed, the RESERVATION KEY is removed from the
754 \fIprkeys_file\fR. The prkeys file will automatically keep track of whether
755 the key was registered with \fI--param-aptpl\fR.
756 .TP
757 The default is: \fB<unset>\fR
758 .RE
759 .
760 .
761 .TP
762 .B all_tg_pt
763 Set the 'all targets ports' flag when registering keys with mpathpersist. Some
764 arrays automatically set and clear registration keys on all target ports from a
765 host, instead of per target port per host. The ALL_TG_PT flag must be set to
766 successfully use mpathpersist on these arrays. Setting this option is identical
767 to calling mpathpersist with \fI--param-alltgpt\fR
768 .RS
769 .TP
770 The default is: \fBno\fR
771 .RE
772 .
773 .
774 .TP
775 .B retain_attached_hw_handler
776 (Obsolete for kernels >= 4.3) If set to
777 .I yes
778 and the SCSI layer has already attached a hardware_handler to the device,
779 multipath will not force the device to use the hardware_handler specified by
780 mutipath.conf. If the SCSI layer has not attached a hardware handler,
781 multipath will continue to use its configured hardware handler.
782 .RS
783 .PP
784 The default is: \fByes\fR
785 .PP
786 \fBImportant Note:\fR Linux kernel 4.3 or newer always behaves as if
787 \fB"retain_attached_hw_handler yes"\fR was set.
788 .RE
789 .
790 .
791 .TP
792 .B detect_prio
793 If set to
794 .I yes
795 , multipath will try to detect if the device supports SCSI-3 ALUA. If so, the
796 device will automatically use the \fIsysfs\fR prioritizer if the required sysf
797 attributes \fIaccess_state\fR and \fIpreferred_path\fR are supported, or the
798 \fIalua\fR prioritizer if not. If set to
799 .I no
800 , the prioritizer will be selected as usual.
801 .RS
802 .TP
803 The default is: \fByes\fR
804 .RE
805 .
806 .
807 .TP
808 .B detect_checker
809 if set to
810 .I yes
811 , multipath will try to detect if the device supports SCSI-3 ALUA. If so, the
812 device will automatically use the \fItur\fR checker. If set to
813 .I no
814 , the checker will be selected as usual.
815 .RS
816 .TP
817 The default is: \fByes\fR
818 .RE
819 .
820 .
821 .TP
822 .B force_sync
823 If set to
824 .I yes
825 , multipathd will call the path checkers in sync mode only.  This means that
826 only one checker will run at a time.  This is useful in the case where many
827 multipathd checkers running in parallel causes significant CPU pressure.
828 .RS
829 .TP
830 The default is: \fBno\fR
831 .RE
832 .
833 .
834 .TP
835 .B strict_timing
836 If set to
837 .I yes
838 , multipathd will start a new path checker loop after exactly one second,
839 so that each path check will occur at exactly \fIpolling_interval\fR
840 seconds. On busy systems path checks might take longer than one second;
841 here the missing ticks will be accounted for on the next round.
842 A warning will be printed if path checks take longer than \fIpolling_interval\fR
843 seconds.
844 .RS
845 .TP
846 The default is: \fBno\fR
847 .RE
848 .
849 .
850 .TP
851 .B deferred_remove
852 If set to
853 .I yes
854 , multipathd will do a deferred remove instead of a regular remove when the
855 last path device has been deleted.  This means that if the multipath device is
856 still in use, it will be freed when the last user closes it.  If path is added
857 to the multipath device before the last user closes it, the deferred remove
858 will be canceled.
859 .RS
860 .TP
861 The default is: \fBno\fR
862 .RE
863 .
864 .
865 .TP
866 .B partition_delimiter
867 This parameter controls how multipath chooses the names of partition devices
868 of multipath maps if a multipath map is renamed (e.g. if a map alias is added
869 or changed). If this parameter is set to a string other than "/UNSET/" (even
870 the empty string), multipath inserts that string between device name and
871 partition number to construct the partition device name.
872 Otherwise (i.e. if this parameter is unset or has the value "/UNSET/"),
873 the behavior depends on the map name: if it ends in a digit, a \fI"p"\fR is
874 inserted between name and partition number; otherwise, the partition number is
875 simply appended.
876 Distributions may use a non-null default value for this option; in this case,
877 the user must set it to "/UNSET/" to obtain the original \fB<unset>\fR
878 behavior. Use \fImultipath -T\fR to check the current settings.
879 .RS
880 .TP
881 The default is: \fB<unset>\fR
882 .RE
883 .
884 .
885 .TP
886 .B config_dir
887 If set to anything other than "", multipath will search this directory
888 alphabetically for file ending in ".conf" and it will read configuration
889 information from them, just as if it was in \fI/etc/multipath.conf\fR.
890 config_dir must either be "" or a fully qualified directory name.
891 .RS
892 .TP
893 The default is: \fB/etc/multipath/conf.d/\fR
894 .RE
895 .
896 .
897 .TP
898 .B san_path_err_threshold
899 If set to a value greater than 0, multipathd will watch paths and check how many
900 times a path has been failed due to errors.If the number of failures on a particular
901 path is greater then the san_path_err_threshold, then the path will not reinstate
902 till san_path_err_recovery_time. These path failures should occur within a
903 san_path_err_forget_rate checks, if not we will consider the path is good enough
904 to reinstantate. See "Shaky paths detection" below.
905 .RS
906 .TP
907 The default is: \fBno\fR
908 .RE
909 .
910 .
911 .TP
912 .B san_path_err_forget_rate
913 If set to a value greater than 0, multipathd will check whether the path failures
914 has exceeded  the san_path_err_threshold within this many checks i.e
915 san_path_err_forget_rate . If so we will not reinstante the path till
916 san_path_err_recovery_time. See "Shaky paths detection" below.
917 .RS
918 .TP
919 The default is: \fBno\fR
920 .RE
921 .
922 .
923 .TP
924 .B san_path_err_recovery_time
925 If set to a value greater than 0, multipathd will make sure that when path failures
926 has exceeded the san_path_err_threshold within san_path_err_forget_rate then the path
927 will be placed in failed state for san_path_err_recovery_time duration.Once san_path_err_recovery_time
928 has timeout  we will reinstante the failed path .
929 san_path_err_recovery_time value should be in secs.
930 See "Shaky paths detection" below.
931 .RS
932 .TP
933 The default is: \fBno\fR
934 .RE
935 .
936 .
937 .TP
938 .B marginal_path_double_failed_time
939 One of the four parameters of supporting path check based on accounting IO
940 error such as intermittent error. When a path failed event occurs twice in
941 \fImarginal_path_double_failed_time\fR seconds due to an IO error and all the
942 other three parameters are set, multipathd will fail the path and enqueue
943 this path into a queue of which members are sent a couple of continuous
944 direct reading asynchronous IOs at a fixed sample rate of 10HZ to start IO
945 error accounting process. See "Shaky paths detection" below.
946 .RS
947 .TP
948 The default is: \fBno\fR
949 .RE
950 .
951 .
952 .TP
953 .B marginal_path_err_sample_time
954 One of the four parameters of supporting path check based on accounting IO
955 error such as intermittent error. If it is set to a value no less than 120,
956 when a path fail event occurs twice in \fImarginal_path_double_failed_time\fR
957 second due to an IO error, multipathd will fail the path and enqueue this
958 path into a queue of which members are sent a couple of continuous direct
959 reading asynchronous IOs at a fixed sample rate of 10HZ to start the IO
960 accounting process for the path will last for
961 \fImarginal_path_err_sample_time\fR.
962 If the rate of IO error on a particular path is greater than the
963 \fImarginal_path_err_rate_threshold\fR, then the path will not reinstate for
964 \fImarginal_path_err_recheck_gap_time\fR seconds unless there is only one
965 active path. After \fImarginal_path_err_recheck_gap_time\fR expires, the path
966 will be requeueed for rechecking. If checking result is good enough, the
967 path will be reinstated. See "Shaky paths detection" below.
968 .RS
969 .TP
970 The default is: \fBno\fR
971 .RE
972 .
973 .
974 .TP
975 .B marginal_path_err_rate_threshold
976 The error rate threshold as a permillage (1/1000). One of the four parameters
977 of supporting path check based on accounting IO error such as intermittent
978 error. Refer to \fImarginal_path_err_sample_time\fR. If the rate of IO errors
979 on a particular path is greater than this parameter, then the path will not
980 reinstate for \fImarginal_path_err_recheck_gap_time\fR seconds unless there is
981 only one active path. See "Shaky paths detection" below.
982 .RS
983 .TP
984 The default is: \fBno\fR
985 .RE
986 .
987 .
988 .TP
989 .B marginal_path_err_recheck_gap_time
990 One of the four parameters of supporting path check based on accounting IO
991 error such as intermittent error. Refer to
992 \fImarginal_path_err_sample_time\fR. If this parameter is set to a positive
993 value, the failed path of  which the IO error rate is larger than
994 \fImarginal_path_err_rate_threshold\fR will be kept in failed state for
995 \fImarginal_path_err_recheck_gap_time\fR seconds. When
996 \fImarginal_path_err_recheck_gap_time\fR seconds expires, the path will be
997 requeueed for checking. If checking result is good enough, the path will be
998 reinstated, or else it will keep failed. See "Shaky paths detection" below.
999 .RS
1000 .TP
1001 The default is: \fBno\fR
1002 .RE
1003 .
1004 .
1005 .TP
1006 .B delay_watch_checks
1007 If set to a value greater than 0, multipathd will watch paths that have
1008 recently become valid for this many checks. If they fail again while they are
1009 being watched, when they next become valid, they will not be used until they
1010 have stayed up for \fIdelay_wait_checks\fR checks. See "Shaky paths detection" below.
1011 .RS
1012 .TP
1013 The default is: \fBno\fR
1014 .RE
1015 .
1016 .
1017 .TP
1018 .B delay_wait_checks
1019 If set to a value greater than 0, when a device that has recently come back
1020 online fails again within \fIdelay_watch_checks\fR checks, the next time it
1021 comes back online, it will marked and delayed, and not used until it has passed
1022 \fIdelay_wait_checks\fR checks. See "Shaky paths detection" below.
1023 .RS
1024 .TP
1025 The default is: \fBno\fR
1026 .RE
1027 .
1028 .
1029 .TP
1030 .B find_multipaths
1031 This option controls whether multipath and multipathd try to create multipath
1032 maps over non-blacklisted devices they encounter. This matters a) when a device is
1033 encountered by \fBmultipath -u\fR during udev rule processing (a device is
1034 blocked from further processing by higher layers - such as LVM - if and only
1035 if it\'s considered a valid multipath device path), and b) when multipathd
1036 detects a new device. The following values are possible:
1037 .RS
1038 .TP 10
1039 .I strict
1040 Both multipath and multipathd treat only such devices as multipath devices
1041 which have been part of a multipath map previously, and which are therefore
1042 listed in the \fBwwids_file\fR. Users can manually set up multipath maps using the
1043 \fBmultipathd add map\fR command. Once set up manually, the map is
1044 remembered in the wwids file and will be set up automatically in the future.
1045 .TP
1046 .I no
1047 Multipath behaves like \fBstrict\fR. Multipathd behaves like \fBgreedy\fR.
1048 .TP
1049 .I yes
1050 Both multipathd and multipath treat a device as multipath device if the
1051 conditions for \fBstrict\fR are met, or if at least two non-blacklisted paths
1052 with the same WWID have been detected.
1053 .TP
1054 .I greedy
1055 Both multipathd and multipath treat every non-blacklisted device as multipath
1056 device path.
1057 .TP
1058 .I smart
1059 This differs from \fIfind_multipaths yes\fR only in
1060 the way it treats new devices for which only one path has been
1061 detected yet. When such a device is first encounted in udev rules, it is
1062 treated as a multipath device. multipathd waits whether additional paths with
1063 the same WWID appears. If that happens, it sets up a multipath map. If it
1064 doesn\'t happen until a
1065 timeout expires, or if setting up the map fails, a new uevent is triggered for
1066 the device; at second encounter in the udev rules, the device will be treated
1067 as non-multipath and passed on to upper layers.
1068 \fBNote:\fR this may cause delays during device detection if
1069 there are single-path devices which aren\'t blacklisted.
1070 .TP
1071 The default is: \fBstrict\fR
1072 .RE
1073 .
1074 .
1075 .TP
1076 .B find_multipaths_timeout
1077 Timeout, in seconds, to wait for additional paths after detecting the first
1078 one, if \fIfind_multipaths
1079 "smart"\fR (see above) is set. If the value is \fBpositive\fR, this timeout is used for all
1080 unknown, non-blacklisted devices encountered. If the value is \fBnegative\fR
1081 (recommended), it's only
1082 applied to "known" devices that have an entry in multipath's hardware table,
1083 either in the built-in table or in a \fIdevice\fR section; other ("unknown") devices will
1084 use a timeout of only 1 second to avoid booting delays. The value 0 means
1085 "use the built-in default". If \fIfind_multipath\fR has a value
1086 other than \fIsmart\fR, this option has no effect.
1087 .RS
1088 .TP
1089 The default is: \fB-10\fR (10s for known and 1s for unknown hardware)
1090 .RE
1091 .
1092 .
1093 .TP
1094 .B uxsock_timeout
1095 CLI receive timeout in milliseconds. For larger systems CLI commands
1096 might timeout before the multipathd lock is released and the CLI command
1097 can be processed. This will result in errors like
1098 "timeout receiving packet" to be returned from CLI commands.
1099 In these cases it is recommended to increase the CLI timeout to avoid
1100 those issues.
1101 .RS
1102 .TP
1103 The default is: \fB1000\fR
1104 .RE
1105 .
1106 .
1107 .TP
1108 .B retrigger_tries
1109 Sets the number of times multipathd will try to retrigger a uevent to get the
1110 WWID.
1111 .RS
1112 .TP
1113 The default is: \fB3\fR
1114 .RE
1115 .
1116 .
1117 .TP
1118 .B retrigger_delay
1119 Sets the amount of time, in seconds, to wait between retriggers.
1120 .RS
1121 .TP
1122 The default is: \fB10\fR
1123 .RE
1124 .
1125 .
1126 .TP
1127 .B missing_uev_wait_timeout
1128 Controls how many seconds multipathd will wait, after a new multipath device
1129 is created, to receive a change event from udev for the device, before
1130 automatically enabling device reloads. Usually multipathd will delay reloads
1131 on a device until it receives a change uevent from the initial table load.
1132 .RS
1133 .TP
1134 The default is: \fB30\fR
1135 .RE
1136 .
1137 .
1138 .TP
1139 .B skip_kpartx
1140 If set to
1141 .I yes
1142 , kpartx will not automatically create partitions on the device.
1143 .RS
1144 .TP
1145 The default is: \fBno\fR
1146 .RE
1147 .
1148 .
1149 .TP
1150 .B disable_changed_wwids
1151 If set to \fIyes\fR, multipathd will check the path wwid on change events, and
1152 if it has changed from the wwid of the multipath device, multipathd will
1153 disable access to the path until the wwid changes back.
1154 .RS
1155 .TP
1156 The default is: \fBno\fR
1157 .RE
1158 .
1159 .
1160 .TP
1161 .B remove_retries
1162 This sets how may times multipath will retry removing a device that is in-use.
1163 Between each attempt, multipath will sleep 1 second.
1164 .RS
1165 .TP
1166 The default is: \fB0\fR
1167 .RE
1168 .
1169 .
1170 .TP
1171 .B max_sectors_kb
1172 Sets the max_sectors_kb device parameter on all path devices and the multipath
1173 device to the specified value.
1174 .RS
1175 .TP
1176 The default is: \fB<device dependent>\fR
1177 .RE
1178 .
1179 .
1180 .TP
1181 .B ghost_delay
1182 Sets the number of seconds that multipath will wait after creating a device
1183 with only ghost paths before marking it ready for use in systemd. This gives
1184 the active paths time to appear before the multipath runs the hardware handler
1185 to switch the ghost paths to active ones. Setting this to \fI0\fR or \fIon\fR
1186 makes multipath immediately mark a device with only ghost paths as ready.
1187 .RS
1188 .TP
1189 The default is \fBno\fR
1190 .RE
1191 .
1192 .
1193 .\" ----------------------------------------------------------------------------
1194 .SH "blacklist and blacklist_exceptions sections"
1195 .\" ----------------------------------------------------------------------------
1196 .
1197 The \fIblacklist\fR section is used to exclude specific devices from
1198 the multipath topology. It is most commonly used to exclude local disks or
1199 non-disk devices (such as LUNs for the storage array controller) from
1200 being handled by multipath-tools.
1201 .LP
1202 .
1203 .
1204 The \fIblacklist_exceptions\fR section is used to revert the actions of the
1205 \fIblacklist\fR section. This allows one to selectively include ("whitelist") devices which
1206 would normally be excluded via the \fIblacklist\fR section. A common usage is
1207 to blacklist "everything" using a catch-all regular expression, and create
1208 specific blacklist_exceptions entries for those devices that should be handled
1209 by multipath-tools.
1210 .LP
1211 .
1212 .
1213 The following keywords are recognized in both sections. The defaults are empty
1214 unless explicitly stated.
1215 .TP 17
1216 .B devnode
1217 Regular expression matching the device nodes to be excluded/included.
1218 .RS
1219 .PP
1220 The default \fIblacklist\fR consists of the regular expressions
1221 "^(ram|zram|raw|loop|fd|md|dm-|sr|scd|st|dcssblk)[0-9]" and
1222 "^(td|hd|vd)[a-z]". This causes virtual devices, non-disk devices, and some other
1223 device types to be excluded from multipath handling by default.
1224 .RE
1225 .TP
1226 .B wwid
1227 Regular expression for the \fIWorld Wide Identifier\fR of a device to be excluded/included.
1228 .
1229 .TP
1230 .B device
1231 Subsection for the device description. This subsection recognizes the
1232 .B vendor
1233 and
1234 .B product
1235 keywords. Both are regular expressions. For a full description of these keywords please see the
1236 \fIdevices\fR section description.
1237 .TP
1238 .B property
1239 Regular expression for an udev property. All
1240 devices that have matching udev properties will be excluded/included.
1241 The handling of the \fIproperty\fR keyword is special,
1242 because devices \fBmust\fR have at least one whitelisted udev property;
1243 otherwise they're treated as blacklisted, and the message
1244 "\fIblacklisted, udev property missing\fR" is displayed in the logs.
1245 .
1246 .RS
1247 .PP
1248 The default \fIblacklist exception\fR is: \fB(SCSI_IDENT_|ID_WWN)\fR, causing
1249 well-behaved SCSI devices and devices that provide a WWN (World Wide Number)
1250 to be included, and all others to be excluded.
1251 .RE
1252 .TP
1253 .B protocol
1254 Regular expression for the protocol of a device to be excluded/included.
1255 .RS
1256 .PP
1257 The protocol strings that multipath recognizes are \fIscsi:fcp\fR,
1258 \fIscsi:spi\fR, \fIscsi:ssa\fR, \fIscsi:sbp\fR, \fIscsi:srp\fR,
1259 \fIscsi:iscsi\fR, \fIscsi:sas\fR, \fIscsi:adt\fR, \fIscsi:ata\fR,
1260 \fIscsi:unspec\fR, \fIccw\fR, \fIcciss\fR, \fInvme\fR, and \fIundef\fR.
1261 The protocol that a path is using can be viewed by running
1262 \fBmultipathd show paths format "%d %P"\fR
1263 .RE
1264 .LP
1265 For every device, these 5 blacklist criteria are evaluated in the the order
1266 "property, dev\%node, device, protocol, wwid". If a device turns out to be
1267 blacklisted by any criterion, it's excluded from handling by multipathd, and
1268 the later criteria aren't evaluated any more. For each
1269 criterion, the whitelist takes precedence over the blacklist if a device
1270 matches both.
1271 .LP
1272 .B
1273 Note:
1274 Besides the blacklist and whitelist, other configuration options such as
1275 \fIfind_multipaths\fR have an impact on
1276 whether or not a given device is handled by multipath-tools.
1277 .
1278 .
1279 .\" ----------------------------------------------------------------------------
1280 .SH "multipaths section"
1281 .\" ----------------------------------------------------------------------------
1282 .
1283 The \fImultipaths\fR section allows setting attributes of multipath maps. The
1284 attributes that are set via the multipaths section (see list below) take
1285 precedence over all other configuration settings, including those from the
1286 \fIoverrides\fR section.
1287 .LP
1288 The only recognized attribute for the \fImultipaths\fR section is the
1289 \fImultipath\fR subsection. If there are multiple \fImultipath\fR subsections
1290 matching a given WWID, the contents of these sections are merged, and settings
1291 from later entries take precedence.
1292 .LP
1293 .
1294 .
1295 The \fImultipath\fR subsection recognizes the following attributes:
1296 .TP 17
1297 .B wwid
1298 (Mandatory) World Wide Identifier. Detected multipath maps are matched agains this attribute.
1299 Note that, unlike the \fIwwid\fR attribute in the \fIblacklist\fR section,
1300 this is \fBnot\fR a regular expression or a substring; WWIDs must match
1301 exactly inside the multipaths section.
1302 .TP
1303 .B alias
1304 Symbolic name for the multipath map. This takes precedence over a an entry for
1305 the same WWID in the \fIbindings_file\fR.
1306 .LP
1307 .
1308 .
1309 The following attributes are optional; if not set the default values
1310 are taken from the \fIoverrides\fR, \fIdevices\fR, or \fIdefaults\fR
1311 section:
1312 .sp 1
1313 .PD .1v
1314 .RS
1315 .TP 18
1316 .B path_grouping_policy
1317 .TP
1318 .B path_selector
1319 .TP
1320 .B prio
1321 .TP
1322 .B prio_args
1323 .TP
1324 .B failback
1325 .TP
1326 .B rr_weight
1327 .TP
1328 .B no_path_retry
1329 .TP
1330 .B rr_min_io
1331 .TP
1332 .B rr_min_io_rq
1333 .TP
1334 .B flush_on_last_del
1335 .TP
1336 .B features
1337 .TP
1338 .B reservation_key
1339 .TP
1340 .B user_friendly_names
1341 .TP
1342 .B deferred_remove
1343 .TP
1344 .B san_path_err_threshold
1345 .TP
1346 .B san_path_err_forget_rate
1347 .TP
1348 .B san_path_err_recovery_time
1349 .TP
1350 .B marginal_path_err_sample_time
1351 .TP
1352 .B marginal_path_err_rate_threshold
1353 .TP
1354 .B marginal_path_err_recheck_gap_time
1355 .TP
1356 .B marginal_path_double_failed_time
1357 .TP
1358 .B delay_watch_checks
1359 .TP
1360 .B delay_wait_checks
1361 .TP
1362 .B skip_kpartx
1363 .TP
1364 .B max_sectors_kb
1365 .TP
1366 .B ghost_delay
1367 .RE
1368 .PD
1369 .LP
1370 .
1371 .
1372 .\" ----------------------------------------------------------------------------
1373 .SH "devices section"
1374 .\" ----------------------------------------------------------------------------
1375 .
1376 \fImultipath-tools\fR have a built-in device table with reasonable defaults
1377 for more than 100 known multipath-capable storage devices. The devices section
1378 can be used to override these settings. If there are multiple matches for a
1379 given device, the attributes of all matching entries are applied to it.
1380 If an attribute is specified in several matching device subsections,
1381 later entries take precedence. Thus, entries in files under \fIconfig_dir\fR (in
1382 reverse alphabetical order) have the highest precedence, followed by entries
1383 in \fImultipath.conf\fR; the built-in hardware table has the lowest
1384 precedence. Inside a configuration file, later entries have higher precedence
1385 than earlier ones.
1386 .LP
1387 The only recognized attribute for the \fIdevices\fR section is the \fIdevice\fR
1388 subsection. Devices detected in the system are matched against the device entries
1389 using the \fBvendor\fR, \fBproduct\fR, and \fBrevision\fR fields, which are
1390 all POSIX Extended regular expressions (see \fBregex\fR(7)).
1391 .LP
1392 The vendor, product, and revision fields that multipath or multipathd detect for
1393 devices in a system depend on the device type. For SCSI devices, they correspond to the
1394 respective fields of the SCSI INQUIRY page. In general, the command '\fImultipathd show
1395 paths format "%d %s"\fR' command can be used to see the detected properties
1396 for all devices in the system.
1397 .LP
1398 .
1399 The \fIdevice\fR subsection recognizes the following attributes:
1400 .TP 17
1401 .B vendor
1402 (Mandatory) Regular expression to match the vendor name.
1403 .TP
1404 .B product
1405 (Mandatory) Regular expression to match the product name.
1406 .TP
1407 .B revision
1408 Regular expression to match the product revision. If not specified, any
1409 revision matches.
1410 .TP
1411 .B product_blacklist
1412 Products with the given \fBvendor\fR matching this string are
1413 blacklisted. This is equivalent to a \fBdevice\fR entry in the \fIblacklist\fR
1414 section with the \fIvendor\fR attribute set to this entry's \fIvendor\fR, and
1415 the \fIproduct\fR attribute set to the value of \fIproduct_blacklist\fR.
1416 .TP
1417 .B alias_prefix
1418 The user_friendly_names prefix to use for this
1419 device type, instead of the default "mpath".
1420 .TP
1421 .B hardware_handler
1422 The hardware handler to use for this device type.
1423 The following hardware handler are implemented:
1424 .RS
1425 .TP 12
1426 .I 1 emc
1427 (Hardware-dependent)
1428 Hardware handler for DGC class arrays as CLARiiON CX/AX and EMC VNX and Unity
1429 families.
1430 .TP
1431 .I 1 rdac
1432 (Hardware-dependent)
1433 Hardware handler for LSI/Engenio/NetApp RDAC class as NetApp SANtricity E/EF
1434 Series, and OEM arrays from IBM DELL SGI STK and SUN.
1435 .TP
1436 .I 1 hp_sw
1437 (Hardware-dependent)
1438 Hardware handler for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
1439 Active/Standby mode exclusively.
1440 .TP
1441 .I 1 alua
1442 (Hardware-dependent)
1443 Hardware handler for SCSI-3 ALUA compatible arrays.
1444 .TP
1445 .I 1 ana
1446 (Hardware-dependent)
1447 Hardware handler for NVMe ANA compatible arrays.
1448 .PP
1449 The default is: \fB<unset>\fR
1450 .PP
1451 \fBImportant Note:\fR Linux kernels 4.3 and newer automatically attach a device
1452 handler to known devices (which includes all devices supporting SCSI-3 ALUA)
1453 and disallow changing the handler
1454 afterwards. Setting \fBhardware_handler\fR for such devices on these kernels
1455 has no effect.
1456 .RE
1457 .
1458 .
1459 .LP
1460 The following attributes are optional; if not set the default values
1461 are taken from the \fIdefaults\fR
1462 section:
1463 .sp 1
1464 .PD .1v
1465 .RS
1466 .TP 18
1467 .B path_grouping_policy
1468 .TP
1469 .B uid_attribute
1470 .TP
1471 .B path_selector
1472 .TP
1473 .B path_checker
1474 .TP
1475 .B prio
1476 .TP
1477 .B prio_args
1478 .TP
1479 .B features
1480 .TP
1481 .B failback
1482 .TP
1483 .B rr_weight
1484 .TP
1485 .B no_path_retry
1486 .TP
1487 .B rr_min_io
1488 .TP
1489 .B rr_min_io_rq
1490 .TP
1491 .B fast_io_fail_tmo
1492 .TP
1493 .B dev_loss_tmo
1494 .TP
1495 .B flush_on_last_del
1496 .TP
1497 .B retain_attached_hw_handler
1498 .TP
1499 .B detect_prio
1500 .TP
1501 .B detect_checker
1502 .TP
1503 .B deferred_remove
1504 .TP
1505 .B san_path_err_threshold
1506 .TP
1507 .B san_path_err_forget_rate
1508 .TP
1509 .B san_path_err_recovery_time
1510 .TP
1511 .B marginal_path_err_sample_time
1512 .TP
1513 .B marginal_path_err_rate_threshold
1514 .TP
1515 .B marginal_path_err_recheck_gap_time
1516 .TP
1517 .B marginal_path_double_failed_time
1518 .TP
1519 .B delay_watch_checks
1520 .TP
1521 .B delay_wait_checks
1522 .TP
1523 .B skip_kpartx
1524 .TP
1525 .B max_sectors_kb
1526 .TP
1527 .B ghost_delay
1528 .RE
1529 .PD
1530 .LP
1531 .
1532 .
1533 .\" ----------------------------------------------------------------------------
1534 .SH "overrides section"
1535 .\" ----------------------------------------------------------------------------
1536 .
1537 The overrides section recognizes the following optional attributes; if not set
1538 the values are taken from the \fIdevices\fR or \fIdefaults\fR sections:
1539 .sp 1
1540 .PD .1v
1541 .RS
1542 .TP 18
1543 .B path_grouping_policy
1544 .TP
1545 .B uid_attribute
1546 .TP
1547 .B getuid_callout
1548 .TP
1549 .B path_selector
1550 .TP
1551 .B path_checker
1552 .TP
1553 .B alias_prefix
1554 .TP
1555 .B features
1556 .TP
1557 .B prio
1558 .TP
1559 .B prio_args
1560 .TP
1561 .B failback
1562 .TP
1563 .B rr_weight
1564 .TP
1565 .B no_path_retry
1566 .TP
1567 .B rr_min_io
1568 .TP
1569 .B rr_min_io_rq
1570 .TP
1571 .B flush_on_last_del
1572 .TP
1573 .B fast_io_fail_tmo
1574 .TP
1575 .B dev_loss_tmo
1576 .TP
1577 .B user_friendly_names
1578 .TP
1579 .B retain_attached_hw_handler
1580 .TP
1581 .B detect_prio
1582 .TP
1583 .B detect_checker
1584 .TP
1585 .B deferred_remove
1586 .TP
1587 .B san_path_err_threshold
1588 .TP
1589 .B san_path_err_forget_rate
1590 .TP
1591 .B san_path_err_recovery_time
1592 .TP
1593 .B marginal_path_err_sample_time
1594 .TP
1595 .B marginal_path_err_rate_threshold
1596 .TP
1597 .B marginal_path_err_recheck_gap_time
1598 .TP
1599 .B marginal_path_double_failed_time
1600 .TP
1601 .B delay_watch_checks
1602 .TP
1603 .B delay_wait_checks
1604 .TP
1605 .B skip_kpartx
1606 .TP
1607 .B ghost_delay
1608 .RE
1609 .PD
1610 .LP
1611 .
1612 .
1613 .\" ----------------------------------------------------------------------------
1614 .SH "WWID generation"
1615 .\" ----------------------------------------------------------------------------
1616 .
1617 Multipath uses a \fIWorld Wide Identification\fR (WWID) to determine
1618 which paths belong to the same device. Each path presenting the same
1619 WWID is assumed to point to the same device.
1620 .LP
1621 The WWID is generated by four methods (in the order of preference):
1622 .TP 17
1623 .B uid_attrs
1624 The WWID is derived from udev attributes by matching the device node name. See
1625 description of \fIuid_attrs\fR in the defaults section above.
1626 .TP
1627 .B getuid_callout
1628 Use the specified external program; cf \fIgetuid_callout\fR above.
1629 Care should be taken when using this method; the external program
1630 needs to be loaded from disk for execution, which might lead to
1631 deadlock situations in an all-paths-down scenario.
1632 .TP
1633 .B uid_attribute
1634 Use the value of the specified udev attribute; cf \fIuid_attribute\fR
1635 above. This method is preferred to \fIgetuid_callout\fR as multipath
1636 does not need to call any external programs here. However, under
1637 certain circumstances udev might not be able to generate the requested
1638 variable.
1639 .TP
1640 .B vpd_pg83
1641 If none of the \fIgetuid_callout\fR or \fIuid_attribute\fR parameters
1642 are present multipath will try to use the sysfs attribute
1643 \fIvpd_pg83\fR to generate the WWID.
1644 .
1645 .
1646 .\" ----------------------------------------------------------------------------
1647 .SH "Shaky paths detection"
1648 .\" ----------------------------------------------------------------------------
1649 .
1650 A common problem in SAN setups is the occurence of intermittent errors: a
1651 path is unreachable, then reachable again for a short time, disappears again,
1652 and so forth. This happens typically on unstable interconnects. It is
1653 undesirable to switch pathgroups unnecessarily on such frequent, unreliable
1654 events. \fImultipathd\fR supports three different methods for detecting this
1655 situation and dealing with it. All methods share the same basic mode of
1656 operation: If a path is found to be \(dqshaky\(dq or \(dqflipping\(dq,
1657 and appears to be in healthy status, it is not reinstated (put back to use)
1658 immediately. Instead, it is watched for some time, and only reinstated
1659 if the healthy state appears to be stable. The logic of determining
1660 \(dqshaky\(dq condition, as well as the logic when to reinstate,
1661 differs between the three methods.
1662 .TP 8
1663 .B \(dqdelay_checks\(dq failure tracking
1664 If a path fails again within a
1665 \fIdelay_watch_checks\fR interval after a failure, don't
1666 reinstate it until it passes a \fIdelay_wait_checks\fR interval
1667 in always good status.
1668 The intervals are measured in \(dqticks\(dq, i.e. the
1669 time between path checks by multipathd, which is variable and controlled by the
1670 \fIpolling_interval\fR and \fImax_polling_interval\fR parameters.
1671 .TP
1672 .B \(dqmarginal_path\(dq failure tracking
1673 If a second failure event (good->bad transition) occurs within
1674 \fImarginal_path_double_failed_time\fR seconds after a failure, high-frequency
1675 monitoring is started for the affected path: I/O is sent at a rate of 10 per
1676 second. This is done for \fImarginal_path_err_sample_time\fR seconds. During
1677 this period, the path is not reinstated. If the
1678 rate of errors remains below \fImarginal_path_err_rate_threshold\fR during the
1679 monitoring period, the path is reinstated. Otherwise, it
1680 is kept in failed state for \fImarginal_path_err_recheck_gap_time\fR, and
1681 after that, it is monitored again. For this method, time intervals are measured
1682 in seconds.
1683 .TP
1684 .B \(dqsan_path_err\(dq failure tracking
1685 multipathd counts path failures for each path. Once the number of failures
1686 exceeds the value given by \fIsan_path_err_threshold\fR, the path is not
1687 reinstated for \fIsan_path_err_recovery_time\fR ticks. While counting
1688 failures, multipathd \(dqforgets\(dq one past failure every
1689 \(dqsan_path_err_forget_rate\(dq ticks; thus if errors don't occur more
1690 often then once in the forget rate interval, the failure count doesn't
1691 increase and the threshold is never reached. As for the \fIdelay_xy\fR method,
1692 intervals are measured in \(dqticks\(dq.
1693 .
1694 .RS 8
1695 .LP
1696 This method is \fBdeprecated\fR in favor of the \(dqmarginal_path\(dq failure
1697 tracking method, and only offered for backward compatibility.
1698 .
1699 .RE
1700 .LP
1701 See the documentation
1702 of the individual options above for details.
1703 It is \fBstrongly discouraged\fR to use more than one of these methods for any
1704 given multipath map, because the two concurrent methods may interact in
1705 unpredictable ways. If the \(dqmarginal_path\(dq method is active, the
1706 \(dqsan_path_err\(dq parameters are implicitly set to 0.
1707 .
1708 .
1709 .\" ----------------------------------------------------------------------------
1710 .SH "KNOWN ISSUES"
1711 .\" ----------------------------------------------------------------------------
1712 .
1713 The usage of \fIqueue_if_no_path\fR option can lead to \fID state\fR
1714 processes being hung and not killable in situations where all the paths to the
1715 LUN go offline. It is advisable to use the \fIno_path_retry\fR option instead.
1716 .P
1717 The use of \fIqueue_if_no_path\fR or \fIno_path_retry\fR might lead to a
1718 deadlock if the \fIdev_loss_tmo\fR setting results in a device being removed
1719 while I/O is still queued. The multipath daemon will update the \fIdev_loss_tmo\fR
1720 setting accordingly to avoid this deadlock. Hence if both values are
1721 specified the order of precedence is \fIno_path_retry, queue_if_no_path, dev_loss_tmo\fR.
1722 .
1723 .
1724 .\" ----------------------------------------------------------------------------
1725 .SH "SEE ALSO"
1726 .\" ----------------------------------------------------------------------------
1727 .
1728 .BR udev (8),
1729 .BR dmsetup (8),
1730 .BR multipath (8),
1731 .BR multipathd (8).
1732 .
1733 .
1734 .\" ----------------------------------------------------------------------------
1735 .SH AUTHORS
1736 .\" ----------------------------------------------------------------------------
1737 .
1738 \fImultipath-tools\fR was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com>
1739 and others.
1740 .\" EOF