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