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