de54b88b57d2d6d52e8ee6a38d87c41a139fd49a
[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 2017-08-18 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 .
71 The following \fIsection\fP keywords are recognized:
72 .TP 17
73 .B defaults
74 This section defines default values for attributes which are used
75 whenever no values are given in the appropriate device or multipath
76 sections.
77 .TP
78 .B blacklist
79 This section defines which devices should be excluded from the
80 multipath topology discovery.
81 .TP
82 .B blacklist_exceptions
83 This section defines which devices should be included in the
84 multipath topology discovery, despite being listed in the
85 \fIblacklist\fR section.
86 .TP
87 .B multipaths
88 This section defines the multipath topologies. They are indexed by a
89 \fIWorld Wide Identifier\fR(WWID). For details on the WWID generation
90 see section \fIWWID generation\fR below.
91 .TP
92 .B devices
93 This section defines the device-specific settings.
94 .TP
95 .B overrides
96 This section defines values for attributes that should override the
97 device-specific settings for all devices.
98 .RE
99 .LP
100 .
101 .
102 .\" ----------------------------------------------------------------------------
103 .SH "defaults section"
104 .\" ----------------------------------------------------------------------------
105 .
106 The \fIdefaults\fR section recognizes the following keywords:
107 .
108 .
109 .TP 17
110 .B verbosity
111 Default verbosity. Higher values increase the verbosity level. Valid
112 levels are between 0 and 6.
113 .RS
114 .TP
115 The default is: \fB2\fR
116 .RE
117 .
118 .
119 .TP
120 .B polling_interval
121 Interval between two path checks in seconds. For properly functioning paths,
122 the interval between checks will gradually increase to \fImax_polling_interval\fR.
123 This value will be overridden by the \fIWatchdogSec\fR
124 setting in the multipathd.service definition if systemd is used.
125 .RS
126 .TP
127 The default is: \fB5\fR
128 .RE
129 .
130 .
131 .TP
132 .B max_polling_interval
133 Maximal interval between two path checks in seconds.
134 .RS
135 .TP
136 The default is: \fB4 * polling_interval\fR
137 .RE
138 .
139 .
140 .TP
141 .B reassign_maps
142 Enable reassigning of device-mapper maps. With this option multipathd
143 will remap existing device-mapper maps to always point to multipath
144 device, not the underlying block devices. Possible values are
145 \fIyes\fR and \fIno\fR.
146 .RS
147 .TP
148 The default is: \fBno\fR
149 .RE
150 .
151 .
152 .TP
153 .B multipath_dir
154 Directory where the dynamic shared objects are stored. Defined at compile time,
155 commonly \fI/lib64/multipath/\fR or \fI/lib/multipath/\fR.
156 .RS
157 .TP
158 The default is: \fB<system dependent>\fR
159 .RE
160 .
161 .
162 .TP
163 .B path_selector
164 The default path selector algorithm to use; they are offered by the
165 kernel multipath target. There are three selector algorithms:
166 .RS
167 .TP 12
168 .I "round-robin 0"
169 Loop through every path in the path group, sending the same amount of I/O to
170 each. Some aspects of behavior can be controlled with the attributes:
171 \fIrr_min_io\fR, \fIrr_min_io_rq\fR and \fIrr_weight\fR.
172 .TP
173 .I "queue-length 0"
174 (Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on the amount
175 of outstanding I/O to the path.
176 .TP
177 .I "service-time 0"
178 (Since 2.6.31 kernel) Choose the path for the next bunch of I/O based on the amount
179 of outstanding I/O to the path and its relative throughput.
180 .TP
181 The default is: \fBservice-time 0\fR
182 .RE
183 .
184 .
185 .TP
186 .B path_grouping_policy
187 The default path grouping policy to apply to unspecified
188 multipaths. Possible values are:
189 .RS
190 .TP 12
191 .I failover
192 One path per priority group.
193 .TP
194 .I multibus
195 All paths in one priority group.
196 .TP
197 .I group_by_serial
198 One priority group per serial number.
199 .TP
200 .I group_by_prio
201 One priority group per priority value. Priorities are determined by
202 callout programs specified as a global, per-controller or
203 per-multipath option in the configuration file.
204 .TP
205 .I group_by_node_name
206 One priority group per target node name. Target node names are fetched
207 in \fI/sys/class/fc_transport/target*/node_name\fR.
208 .TP
209 The default is: \fBfailover\fR
210 .RE
211 .
212 .
213 .TP
214 .B uid_attrs
215 The udev attribute providing a unique path identifier for corresponding
216 type of path devices. If this field is configured and matched with type
217 of device, it would override any other methods providing for device
218 unique identifier in config file, and it would activate merging uevents
219 according to the identifier to promote effiecncy in processing uevents.
220 It has no default value, if you want to identify path by udev attribute
221 and to activate merging uevents for SCSI and DASD devices, you can set
222 its value as: \fIuid_attrs "sd:ID_SERIAL dasd:ID_UID"\fR.
223 .RS
224 .TP
225 The default is: \fB<unset>\fR
226 .RE
227 .
228 .
229 .TP
230 .B uid_attribute
231 The udev attribute providing a unique path identifier.
232 .RS
233 .TP
234 The default is: for SCSI devices \fBID_SERIAL\fR
235 .TP
236 The default is: for DASD devices \fBID_UID\fR
237 .TP
238 The default is: for NVME devices \fBID_WWN\fR
239 .RE
240 .
241 .
242 .TP
243 .B getuid_callout
244 (Superseded by \fIuid_attribute\fR) The default program and args to callout
245 to obtain a unique path identifier. Should be specified with an absolute path.
246 .RS
247 .TP
248 The default is: \fB<unset>\fR
249 .RE
250 .
251 .
252 .TP
253 .B prio
254 The name of the path priority routine. The specified routine
255 should return a numeric value specifying the relative priority
256 of this path. Higher number have a higher priority.
257 \fI"none"\fR is a valid value. Currently the following path priority routines
258 are implemented:
259 .RS
260 .TP 12
261 .I const
262 Return a constant priority of \fI1\fR.
263 .TP
264 .I sysfs
265 Use the sysfs attributes \fIaccess_state\fR and \fIpreferred_path\fR to
266 generate the path priority. This prioritizer accepts the optional prio_arg
267 \fIexclusive_pref_bit\fR.
268 .TP
269 .I emc
270 (Hardware-dependent)
271 Generate the path priority for DGC class arrays as CLARiiON CX/AX and
272 EMC VNX and Unity families.
273 .TP
274 .I alua
275 (Hardware-dependent)
276 Generate the path priority based on the SCSI-3 ALUA settings. This prioritizer
277 accepts the optional prio_arg \fIexclusive_pref_bit\fR.
278 .TP
279 .I ontap
280 (Hardware-dependent)
281 Generate the path priority for NetApp ONTAP class and OEM arrays as IBM NSeries.
282 .TP
283 .I rdac
284 (Hardware-dependent)
285 Generate the path priority for LSI/Engenio/NetApp RDAC class as NetApp SANtricity
286 E/EF Series, and OEM arrays from IBM DELL SGI STK and SUN.
287 .TP
288 .I hp_sw
289 (Hardware-dependent)
290 Generate the path priority for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
291 Active/Standby mode exclusively.
292 .TP
293 .I hds
294 (Hardware-dependent)
295 Generate the path priority for Hitachi AMS 2000 and HUS 100 families of arrays.
296 .TP
297 .I random
298 Generate a random priority between 1 and 10.
299 .TP
300 .I weightedpath
301 Generate the path priority based on the regular expression and the
302 priority provided as argument. Requires prio_args keyword.
303 .TP
304 .I path_latency
305 Generate the path priority based on a latency algorithm.
306 Requires prio_args keyword.
307 .TP
308 .I datacore
309 (Hardware-dependent)
310 Generate the path priority for some DataCore storage arrays. Requires prio_args
311 keyword.
312 .TP
313 .I iet
314 (iSCSI only)
315 Generate path priority for iSCSI targets based on IP address. Requires
316 prio_args keyword.
317 .PP
318 The default depends on the \fBdetect_prio\fR setting: If \fBdetect_prio\fR is
319 \fByes\fR (default), the default priority algorithm is \fBsysfs\fR (except for
320 NetAPP E-Series, where it is \fBalua\fR). If \fBdetect_prio\fR is
321 \fBno\fR, the default priority algorithm is \fBconst\fR.
322 .RE
323 .
324 .
325 .TP
326 .B prio_args
327 Arguments to pass to to the prio function. This only applies to certain
328 prioritizers:
329 .RS
330 .TP 12
331 .I weighted
332 Needs a value of the form
333 \fI"<hbtl|devname|serial|wwn> <regex1> <prio1> <regex2> <prio2> ..."\fR
334 .RS
335 .TP 8
336 .I hbtl
337 Regex can be of SCSI H:B:T:L format. For example: 1:0:.:. , *:0:0:.
338 .TP
339 .I devname
340 Regex can be of device name format. For example: sda , sd.e
341 .TP
342 .I serial
343 Regex can be of serial number format. For example: .*J1FR.*324 . The serial can
344 be looked up through sysfs or by running multipathd show paths format "%z". For
345 example: 0395J1FR904324
346 .TP
347 .I wwn
348 Regex can be of the form \fI"host_wwnn:host_wwpn:target_wwnn:target_wwpn"\fR
349 these values can be looked up through sysfs or by running \fImultipathd show paths format
350 "%N:%R:%n:%r"\fR. For example: 0x200100e08ba0aea0:0x210100e08ba0aea0:.*:.* , .*:.*:iqn.2009-10.com.redhat.msp.lab.ask-06:.*
351 .RE
352 .TP 12
353 .I path_latency
354 Needs a value of the form "io_num=\fI<20>\fR base_num=\fI<10>\fR"
355 .RS
356 .TP 8
357 .I io_num
358 The number of read IOs sent to the current path continuously, used to calculate the average path latency.
359 Valid Values: Integer, [2, 200].
360 .TP
361 .I base_num
362 The base number value of logarithmic scale, used to partition different priority ranks. Valid Values: Integer,
363 [2, 10]. And Max average latency value is 100s, min average latency value is 1us.
364 For example: If base_num=10, the paths will be grouped in priority groups with path latency <=1us, (1us, 10us],
365 (10us, 100us], (100us, 1ms], (1ms, 10ms], (10ms, 100ms], (100ms, 1s], (1s, 10s], (10s, 100s], >100s.
366 .RE
367 .TP 12
368 .I alua
369 If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
370 set will always be in their own path group.
371 .TP
372 .I sysfs
373 If \fIexclusive_pref_bit\fR is set, paths with the \fIpreferred path\fR bit
374 set will always be in their own path group.
375 .TP
376 .I datacore
377 .RS
378 .TP 8
379 .I preferredsds
380 (Mandatory) The preferred "SDS name".
381 .TP
382 .I timeout
383 (Optional) The timeout for the INQUIRY, in ms.
384 .RE
385 .TP 12
386 .I iet
387 .RS
388 .TP 8
389 .I preferredip=...
390 (Mandatory) Th preferred IP address, in dotted decimal notation, for iSCSI targets.
391 .RE
392 .TP
393 The default is: \fB<unset>\fR
394 .RE
395 .
396 .
397 .TP
398 .B features
399 Specify any device-mapper features to be used. Syntax is \fInum list\fR
400 where \fInum\fR is the number, between 0 and 8, of features in \fIlist\fR.
401 Possible values for the feature list are:
402 .RS
403 .TP 12
404 .I queue_if_no_path
405 (Deprecated, superseded by \fIno_path_retry\fR) Queue I/O if no path is active.
406 Identical to the \fIno_path_retry\fR with \fIqueue\fR value. If both this
407 feature and \fIno_path_retry\fR are set, the latter value takes
408 precedence. See KNOWN ISSUES.
409 .TP
410 .I pg_init_retries <times>
411 (Since kernel 2.6.24) Number of times to retry pg_init, it must be between 1 and 50.
412 .TP
413 .I pg_init_delay_msecs <msecs>
414 (Since kernel 2.6.38) Number of msecs before pg_init retry, it must be between 0 and 60000.
415 .TP
416 .I queue_mode <mode>
417 (Since kernel 4.8) Select the the queueing mode per multipath device.
418 <mode> can be \fIbio\fR, \fIrq\fR or \fImq\fR, which corresponds to
419 bio-based, request-based, and block-multiqueue (blk-mq) request-based,
420 respectively.
421 The default depends on the kernel parameter \fBdm_mod.use_blk_mq\fR. It is
422 \fImq\fR if the latter is set, and \fIrq\fR otherwise.
423 .TP
424 The default is: \fB<unset>\fR
425 .RE
426 .
427 .
428 .TP
429 .B path_checker
430 The default method used to determine the paths state. Possible values
431 are:
432 .RS
433 .TP 12
434 .I readsector0
435 (Deprecated) Read the first sector of the device. This checker is being
436 deprecated, please use \fItur\fR instead.
437 .TP
438 .I tur
439 Issue a \fITEST UNIT READY\fR command to the device.
440 .TP
441 .I emc_clariion
442 (Hardware-dependent)
443 Query the DGC/EMC specific EVPD page 0xC0 to determine the path state
444 for CLARiiON CX/AX and EMC VNX and Unity arrays families.
445 .TP
446 .I hp_sw
447 (Hardware-dependent)
448 Check the path state for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
449 Active/Standby mode exclusively.
450 .TP
451 .I rdac
452 (Hardware-dependent)
453 Check the path state for LSI/Engenio/NetApp RDAC class as NetApp SANtricity E/EF
454 Series, and OEM arrays from IBM DELL SGI STK and SUN.
455 .TP
456 .I directio
457 (Deprecated) Read the first sector with direct I/O. This checker is being
458 deprecated, it could cause spurious path failures under high load.
459 Please use \fItur\fR instead.
460 .TP
461 .I cciss_tur
462 (Hardware-dependent)
463 Check the path state for HP/COMPAQ Smart Array(CCISS) controllers.
464 .TP
465 .I none
466 Do not check the device, fallback to use the values retrieved from sysfs
467 .TP
468 .I rbd
469 Check if the path is in the Ceph blacklist and remap the path if it is.
470 .TP
471 The default is: \fBtur\fR
472 .RE
473 .
474 .
475 .TP
476 .B alias_prefix
477 The \fIuser_friendly_names\fR prefix.
478 .RS
479 .TP
480 The default is: \fBmpath\fR
481 .RE
482 .
483 .
484 .TP
485 .B failback
486 Tell multipathd how to manage path group failback.
487 To select \fIimmediate\fR or a \fIvalue\fR, it's mandatory that the device
488 has support for a working prioritizer.
489 .RS
490 .TP 12
491 .I immediate
492 Immediately failback to the highest priority pathgroup that contains
493 active paths.
494 .TP
495 .I manual
496 Do not perform automatic failback.
497 .TP
498 .I followover
499 Used to deal with multiple computers accessing the same Active/Passive storage
500 devices. Only perform automatic failback when the first path of a pathgroup
501 becomes active. This keeps a cluster node from automatically failing back when
502 another node requested the failover.
503 .TP
504 .I values > 0
505 Deferred failback (time to defer in seconds).
506 .TP
507 The default is: \fBmanual\fR
508 .RE
509 .
510 .
511 .TP
512 .B  rr_min_io
513 Number of I/O requests to route to a path before switching to the next in the
514 same path group. This is only for \fIBlock I/O\fR(BIO) based multipath and
515 only apply to \fIround-robin\fR path_selector.
516 .RS
517 .TP
518 The default is: \fB1000\fR
519 .RE
520 .
521 .
522 .TP
523 .B rr_min_io_rq
524 Number of I/O requests to route to a path before switching to the next in the
525 same path group. This is only for \fIRequest\fR based multipath and
526 only apply to \fIround-robin\fR path_selector.
527 .RS
528 .TP
529 The default is: \fB1\fR
530 .RE
531 .
532 .
533 .TP
534 .B max_fds
535 Specify the maximum number of file descriptors that can be opened by multipath
536 and multipathd. This is equivalent to ulimit \-n. A value of \fImax\fR will set
537 this to the system limit from \fI/proc/sys/fs/nr_open\fR. If this is not set, the
538 maximum number of open fds is taken from the calling process. It is usually
539 1024. To be safe, this should be set to the maximum number of paths plus 32,
540 if that number is greated than 1024.
541 .RS
542 .TP
543 The default is: \fBmax\fR
544 .RE
545 .
546 .
547 .TP
548 .B rr_weight
549 If set to \fIpriorities\fR the multipath configurator will assign path weights
550 as "path prio * rr_min_io". Possible values are
551 .I priorities
552 or
553 .I uniform .
554 Only apply to \fIround-robin\fR path_selector.
555 .RS
556 .TP
557 The default is: \fBuniform\fR
558 .RE
559 .
560 .
561 .TP
562 .B no_path_retry
563 Specify what to do when all paths are down. Possible values are:
564 .RS
565 .TP 12
566 .I value > 0
567 Number of retries until disable I/O queueing.
568 .TP
569 .I fail
570 For immediate failure (no I/O queueing).
571 .TP
572 .I queue
573 For never stop I/O queueing, similar to \fIqueue_if_no_path\fR. See KNOWN ISSUES.
574 .TP
575 The default is: \fBfail\fR
576 .RE
577 .
578 .
579 .TP
580 .B queue_without_daemon
581 If set to
582 .I no
583 , when multipathd stops, queueing will be turned off for all devices.
584 This is useful for devices that set no_path_retry. If a machine is
585 shut down while all paths to a device are down, it is possible to hang waiting
586 for I/O to return from the device after multipathd has been stopped. Without
587 multipathd running, access to the paths cannot be restored, and the kernel
588 cannot be told to stop queueing I/O. Setting queue_without_daemon to
589 .I no
590 , avoids this problem.
591 .RS
592 .TP
593 The default is: \fBno\fR
594 .RE
595 .
596 .
597 .TP
598 .B checker_timeout
599 Specify the timeout to use for path checkers and prioritizers that issue SCSI
600 commands with an explicit timeout, in seconds.
601 .RS
602 .TP
603 The default is: in \fB/sys/block/sd<x>/device/timeout\fR
604 .RE
605 .
606 .
607 .TP
608 .B flush_on_last_del
609 If set to
610 .I yes
611 , multipathd will disable queueing when the last path to a device has been
612 deleted.
613 .RS
614 .TP
615 The default is: \fBno\fR
616 .RE
617 .
618 .
619 .TP
620 .B user_friendly_names
621 If set to
622 .I yes
623 , using the bindings file \fI/etc/multipath/bindings\fR to assign a persistent
624 and unique alias to the multipath, in the form of mpath<n>. If set to
625 .I no
626 use the WWID as the alias. In either case this be will
627 be overridden by any specific aliases in the \fImultipaths\fR section.
628 .RS
629 .TP
630 The default is: \fBno\fR
631 .RE
632 .
633 .
634 .TP
635 .B fast_io_fail_tmo
636 Specify the number of seconds the SCSI layer will wait after a problem has been
637 detected on a FC remote port before failing I/O to devices on that remote port.
638 This should be smaller than dev_loss_tmo. Setting this to
639 .I off
640 will disable the timeout.
641 .RS
642 .TP
643 The default is: in \fB5\fR
644 .RE
645 .
646 .
647 .TP
648 .B dev_loss_tmo
649 Specify the number of seconds the SCSI layer will wait after a problem has
650 been detected on a FC remote port before removing it from the system. This
651 can be set to "infinity" which sets it to the max value of 2147483647
652 seconds, or 68 years. It will be automatically adjusted to the overall
653 retry interval \fIno_path_retry\fR * \fIpolling_interval\fR
654 if a number of retries is given with \fIno_path_retry\fR and the
655 overall retry interval is longer than the specified \fIdev_loss_tmo\fR value.
656 The Linux kernel will cap this value to \fI300\fR if \fIfast_io_fail_tmo\fR
657 is not set. See KNOWN ISSUES.
658 .RS
659 .TP
660 The default is: \fB600\fR
661 .RE
662 .
663 .
664 .TP
665 .B bindings_file
666 The full pathname of the binding file to be used when the user_friendly_names
667 option is set.
668 .RS
669 .TP
670 The default is: \fB/etc/multipath/bindings\fR
671 .RE
672 .
673 .
674 .TP
675 .B wwids_file
676 The full pathname of the WWIDs file, which is used by multipath to keep track
677 of the WWIDs for LUNs it has created multipath devices on in the past.
678 .RS
679 .TP
680 The default is: \fB/etc/multipath/wwids\fR
681 .RE
682 .
683 .
684 .TP
685 .B prkeys_file
686 The full pathname of the prkeys file, which is used by multipathd to keep
687 track of the persistent reservation key used for a specific WWID, when
688 \fIreservation_key\fR is set to \fBfile\fR.
689 .RS
690 .TP
691 The default is \fB/etc/multipath/prkeys\fR
692 .RE
693 .
694 .
695 .TP
696 .B log_checker_err
697 If set to
698 .I once
699 , multipathd logs the first path checker error at logging level 2. Any later
700 errors are logged at level 3 until the device is restored. If set to
701 .I always
702 , multipathd always logs the path checker error at logging level 2.
703 .RS
704 .TP
705 The default is: \fBalways\fR
706 .RE
707 .
708 .
709 .TP
710 .B reservation_key
711 This is the service action reservation key used by mpathpersist. It must be
712 set for all multipath devices using persistent reservations, and it must be
713 the same as the RESERVATION KEY field of the PERSISTENT RESERVE OUT parameter
714 list which contains an 8-byte value provided by the application client to the
715 device server to identify the I_T nexus.
716 .RS
717 .PP
718 Alternatively, this can be set to \fBfile\fR, which will store the RESERVATION
719 KEY registered by mpathpersist in the \fIprkeys_file\fR. multipathd will then
720 use this key to register additional paths as they appear.  When the
721 registration is removed, the RESERVATION KEY is removed from the
722 \fIprkeys_file\fR.
723 .TP
724 The default is: \fB<unset>\fR
725 .RE
726 .
727 .
728 .TP
729 .B retain_attached_hw_handler
730 (Obsolete for kernels >= 4.3) If set to
731 .I yes
732 and the SCSI layer has already attached a hardware_handler to the device,
733 multipath will not force the device to use the hardware_handler specified by
734 mutipath.conf. If the SCSI layer has not attached a hardware handler,
735 multipath will continue to use its configured hardware handler.
736 .RS
737 .PP
738 The default is: \fByes\fR
739 .PP
740 \fBImportant Note:\fR Linux kernel 4.3 or newer always behaves as if
741 \fB"retain_attached_hw_handler yes"\fR was set.
742 .RE
743 .
744 .
745 .TP
746 .B detect_prio
747 If set to
748 .I yes
749 , multipath will try to detect if the device supports SCSI-3 ALUA. If so, the
750 device will automatically use the \fIsysfs\fR prioritizer if the required sysf
751 attributes \fIaccess_state\fR and \fIpreferred_path\fR are supported, or the
752 \fIalua\fR prioritizer if not. If set to
753 .I no
754 , the prioritizer will be selected as usual.
755 .RS
756 .TP
757 The default is: \fByes\fR
758 .RE
759 .
760 .
761 .TP
762 .B detect_checker
763 if set to
764 .I yes
765 , multipath will try to detect if the device supports SCSI-3 ALUA. If so, the
766 device will automatically use the \fItur\fR checker. If set to
767 .I no
768 , the checker will be selected as usual.
769 .RS
770 .TP
771 The default is: \fByes\fR
772 .RE
773 .
774 .
775 .TP
776 .B force_sync
777 If set to
778 .I yes
779 , multipathd will call the path checkers in sync mode only.  This means that
780 only one checker will run at a time.  This is useful in the case where many
781 multipathd checkers running in parallel causes significant CPU pressure.
782 .RS
783 .TP
784 The default is: \fBno\fR
785 .RE
786 .
787 .
788 .TP
789 .B strict_timing
790 If set to
791 .I yes
792 , multipathd will start a new path checker loop after exactly one second,
793 so that each path check will occur at exactly \fIpolling_interval\fR
794 seconds. On busy systems path checks might take longer than one second;
795 here the missing ticks will be accounted for on the next round.
796 A warning will be printed if path checks take longer than \fIpolling_interval\fR
797 seconds.
798 .RS
799 .TP
800 The default is: \fBno\fR
801 .RE
802 .
803 .
804 .TP
805 .B deferred_remove
806 If set to
807 .I yes
808 , multipathd will do a deferred remove instead of a regular remove when the
809 last path device has been deleted.  This means that if the multipath device is
810 still in use, it will be freed when the last user closes it.  If path is added
811 to the multipath device before the last user closes it, the deferred remove
812 will be canceled.
813 .RS
814 .TP
815 The default is: \fBno\fR
816 .RE
817 .
818 .
819 .TP
820 .B partition_delimiter
821 If this value is not set, when multipath renames a device, it will act just
822 like the kpartx default does, only adding a \fI"p"\fR to names ending in a
823 number. If this parameter is set, multipath will act like kpartx does with
824 the \fI-p\fR option is used, and always add delimiter.
825 .RS
826 .TP
827 The default is: \fB<unset>\fR
828 .RE
829 .
830 .
831 .TP
832 .B config_dir
833 If set to anything other than "", multipath will search this directory
834 alphabetically for file ending in ".conf" and it will read configuration
835 information from them, just as if it was in \fI/etc/multipath.conf\fR.
836 config_dir must either be "" or a fully qualified directory name.
837 .RS
838 .TP
839 The default is: \fB/etc/multipath/conf.d/\fR
840 .RE
841 .
842 .
843 .TP
844 .B marginal_path_double_failed_time
845 One of the four parameters of supporting path check based on accounting IO
846 error such as intermittent error. When a path failed event occurs twice in
847 \fImarginal_path_double_failed_time\fR seconds due to an IO error and all the
848 other three parameters are set, multipathd will fail the path and enqueue
849 this path into a queue of which members are sent a couple of continuous
850 direct reading asynchronous IOs at a fixed sample rate of 10HZ to start IO
851 error accounting process.
852 .RS
853 .TP
854 The default is: \fBno\fR
855 .RE
856 .
857 .
858 .TP
859 .B marginal_path_err_sample_time
860 One of the four parameters of supporting path check based on accounting IO
861 error such as intermittent error. If it is set to a value no less than 120,
862 when a path fail event occurs twice in \fImarginal_path_double_failed_time\fR
863 second due to an IO error, multipathd will fail the path and enqueue this
864 path into a queue of which members are sent a couple of continuous direct
865 reading asynchronous IOs at a fixed sample rate of 10HZ to start the IO
866 accounting process for the path will last for
867 \fImarginal_path_err_sample_time\fR.
868 If the rate of IO error on a particular path is greater than the
869 \fImarginal_path_err_rate_threshold\fR, then the path will not reinstate for
870 \fImarginal_path_err_rate_threshold\fR seconds unless there is only one
871 active path. After \fImarginal_path_err_recheck_gap_time\fR expires, the path
872 will be requeueed for rechecking. If checking result is good enough, the
873 path will be reinstated.
874 .RS
875 .TP
876 The default is: \fBno\fR
877 .RE
878 .
879 .
880 .TP
881 .B marginal_path_err_rate_threshold
882 The error rate threshold as a permillage (1/1000). One of the four parameters
883 of supporting path check based on accounting IO error such as intermittent
884 error. Refer to \fImarginal_path_err_sample_time\fR. If the rate of IO errors
885 on a particular path is greater than this parameter, then the path will not
886 reinstate for \fImarginal_path_err_rate_threshold\fR seconds unless there is
887 only one active path.
888 .RS
889 .TP
890 The default is: \fBno\fR
891 .RE
892 .
893 .
894 .TP
895 .B marginal_path_err_recheck_gap_time
896 One of the four parameters of supporting path check based on accounting IO
897 error such as intermittent error. Refer to
898 \fImarginal_path_err_sample_time\fR. If this parameter is set to a positive
899 value, the failed path of  which the IO error rate is larger than
900 \fImarginal_path_err_rate_threshold\fR will be kept in failed state for
901 \fImarginal_path_err_recheck_gap_time\fR seconds. When
902 \fImarginal_path_err_recheck_gap_time\fR seconds expires, the path will be
903 requeueed for checking. If checking result is good enough, the path will be
904 reinstated, or else it will keep failed.
905 .RS
906 .TP
907 The default is: \fBno\fR
908 .RE
909 .
910 .
911 .TP
912 .B delay_watch_checks
913 If set to a value greater than 0, multipathd will watch paths that have
914 recently become valid for this many checks. If they fail again while they are
915 being watched, when they next become valid, they will not be used until they
916 have stayed up for \fIdelay_wait_checks\fR checks.
917 .RS
918 .TP
919 The default is: \fBno\fR
920 .RE
921 .
922 .
923 .TP
924 .B delay_wait_checks
925 If set to a value greater than 0, when a device that has recently come back
926 online fails again within \fIdelay_watch_checks\fR checks, the next time it
927 comes back online, it will marked and delayed, and not used until it has passed
928 \fIdelay_wait_checks\fR checks.
929 .RS
930 .TP
931 The default is: \fBno\fR
932 .RE
933 .
934 .
935 .TP
936 .B find_multipaths
937 If set to
938 .I yes
939 , instead of trying to create a multipath device for every non-blacklisted
940 path, multipath will only create a device if one of three condidions are
941 met.
942 .I 1
943 There are at least two non-blacklisted paths with the same WWID,
944 .I 2
945 the user manually forces the creation, by specifying a device with the multipath
946 command, or
947 .I 3
948 a path has the same WWID as a multipath device that was previously created
949 while find_multipaths was set (even if that multipath device doesn't currently
950 exist).
951 Whenever a multipath device is created with find_multipaths set, multipath will
952 remember the WWID of the device, so that it will automatically create the
953 device again, as soon as it sees a path with that WWID. This should allow most
954 users to have multipath automatically choose the correct paths to make into
955 multipath devices, without having to edit the blacklist.
956 .RS
957 .TP
958 The default is: \fBno\fR
959 .RE
960 .
961 .
962 .TP
963 .B uxsock_timeout
964 CLI receive timeout in milliseconds. For larger systems CLI commands
965 might timeout before the multipathd lock is released and the CLI command
966 can be processed. This will result in errors like
967 "timeout receiving packet" to be returned from CLI commands.
968 In these cases it is recommended to increase the CLI timeout to avoid
969 those issues.
970 .RS
971 .TP
972 The default is: \fB1000\fR
973 .RE
974 .
975 .
976 .TP
977 .B retrigger_tries
978 Sets the number of times multipathd will try to retrigger a uevent to get the
979 WWID.
980 .RS
981 .TP
982 The default is: \fB3\fR
983 .RE
984 .
985 .
986 .TP
987 .B retrigger_delay
988 Sets the amount of time, in seconds, to wait between retriggers.
989 .RS
990 .TP
991 The default is: \fB10\fR
992 .RE
993 .
994 .
995 .TP
996 .B missing_uev_wait_timeout
997 Controls how many seconds multipathd will wait, after a new multipath device
998 is created, to receive a change event from udev for the device, before
999 automatically enabling device reloads. Usually multipathd will delay reloads
1000 on a device until it receives a change uevent from the initial table load.
1001 .RS
1002 .TP
1003 The default is: \fB30\fR
1004 .RE
1005 .
1006 .
1007 .TP
1008 .B skip_kpartx
1009 If set to
1010 .I yes
1011 , kpartx will not automatically create partitions on the device.
1012 .RS
1013 .TP
1014 The default is: \fBno\fR
1015 .RE
1016 .
1017 .
1018 .TP
1019 .B disable_changed_wwids
1020 If set to \fIyes\fR, multipathd will check the path wwid on change events, and
1021 if it has changed from the wwid of the multipath device, multipathd will
1022 disable access to the path until the wwid changes back.
1023 .RS
1024 .TP
1025 The default is: \fBno\fR
1026 .RE
1027 .
1028 .
1029 .TP
1030 .B remove_retries
1031 This sets how may times multipath will retry removing a device that is in-use.
1032 Between each attempt, multipath will sleep 1 second.
1033 .RS
1034 .TP
1035 The default is: \fB0\fR
1036 .RE
1037 .
1038 .
1039 .TP
1040 .B max_sectors_kb
1041 Sets the max_sectors_kb device parameter on all path devices and the multipath
1042 device to the specified value.
1043 .RS
1044 .TP
1045 The default is: \fB<device dependent>\fR
1046 .RE
1047 .
1048 .
1049 .\" ----------------------------------------------------------------------------
1050 .SH "blacklist section"
1051 .\" ----------------------------------------------------------------------------
1052 .
1053 The \fIblacklist\fR section is used to exclude specific device from inclusion in
1054 the multipath topology. It is most commonly used to exclude local disks or LUNs
1055 for the array controller.
1056 .LP
1057 .
1058 .
1059 The following keywords are recognized:
1060 .TP 17
1061 .B devnode
1062 Regular expression of the device nodes to be excluded.
1063 .RS
1064 .TP
1065 The default is: \fB^(ram|raw|loop|fd|md|dm-|sr|scd|st|dcssblk)[0-9]\fR and \fB^(td|hd|vd)[a-z]\fR
1066 .RE
1067 .TP
1068 .B wwid
1069 The \fIWorld Wide Identification\fR of a device.
1070 .TP
1071 .B property
1072 Regular expression of the udev property to be excluded.
1073 .TP
1074 .B device
1075 Subsection for the device description. This subsection recognizes the
1076 .B vendor
1077 and
1078 .B product
1079 keywords. For a full description of these keywords please see the
1080 \fIdevices\fR section description.
1081 .
1082 .
1083 .\" ----------------------------------------------------------------------------
1084 .SH "blacklist_exceptions section"
1085 .\" ----------------------------------------------------------------------------
1086 .
1087 The \fIblacklist_exceptions\fR section is used to revert the actions of the
1088 \fIblacklist\fR section. For example to include specific device in the
1089 multipath topology. This allows one to selectively include devices which
1090 would normally be excluded via the \fIblacklist\fR section.
1091 .LP
1092 .
1093 .
1094 The following keywords are recognized:
1095 .TP 17
1096 .B devnode
1097 Regular expression of the device nodes to be whitelisted.
1098 .TP
1099 .B wwid
1100 The \fIWorld Wide Identification\fR of a device.
1101 .TP
1102 .B property
1103 Regular expression of the udev property to be whitelisted.
1104 .RS
1105 .TP
1106 The default is: \fB(SCSI_IDENT_|ID_WWN)\fR
1107 .RE
1108 .TP
1109 .B device
1110 Subsection for the device description. This subsection recognizes the
1111 .B vendor
1112 and
1113 .B product
1114 keywords. For a full description of these keywords please see the \fIdevices\fR
1115 section description.
1116 .LP
1117 The \fIproperty\fR blacklist and whitelist handling is different from the usual
1118 handling in the sense that the whitelist \fIhas\fR to be set, otherwise the
1119 device will be blacklisted. In these cases the message \fIblacklisted, udev
1120 property missing\fR will be displayed.
1121 .
1122 .
1123 .\" ----------------------------------------------------------------------------
1124 .SH "multipaths section"
1125 .\" ----------------------------------------------------------------------------
1126 .
1127 The only recognized attribute for the \fImultipaths\fR section is the
1128 \fImultipath\fR subsection.
1129 .LP
1130 .
1131 .
1132 The \fImultipath\fR subsection recognizes the following attributes:
1133 .TP 17
1134 .B wwid
1135 (Mandatory) Index of the container.
1136 .TP
1137 .B alias
1138 Symbolic name for the multipath map.
1139 .LP
1140 .
1141 .
1142 The following attributes are optional; if not set the default values
1143 are taken from the \fIdefaults\fR or \fIdevices\fR section:
1144 .sp 1
1145 .PD .1v
1146 .RS
1147 .TP 18
1148 .B path_grouping_policy
1149 .TP
1150 .B path_selector
1151 .TP
1152 .B prio
1153 .TP
1154 .B prio_args
1155 .TP
1156 .B failback
1157 .TP
1158 .B rr_weight
1159 .TP
1160 .B no_path_retry
1161 .TP
1162 .B rr_min_io
1163 .TP
1164 .B rr_min_io_rq
1165 .TP
1166 .B flush_on_last_del
1167 .TP
1168 .B features
1169 .TP
1170 .B reservation_key
1171 .TP
1172 .B user_friendly_names
1173 .TP
1174 .B deferred_remove
1175 .TP
1176 .B marginal_path_err_sample_time
1177 .TP
1178 .B marginal_path_err_rate_threshold
1179 .TP
1180 .B marginal_path_err_recheck_gap_time
1181 .TP
1182 .B marginal_path_double_failed_time
1183 .TP
1184 .B delay_watch_checks
1185 .TP
1186 .B delay_wait_checks
1187 .TP
1188 .B skip_kpartx
1189 .TP
1190 .B max_sectors_kb
1191 .RE
1192 .PD
1193 .LP
1194 .
1195 .
1196 .\" ----------------------------------------------------------------------------
1197 .SH "devices section"
1198 .\" ----------------------------------------------------------------------------
1199 .
1200 The only recognized attribute for the \fIdevices\fR section is the \fIdevice\fR
1201 subsection.
1202 .LP
1203 .
1204 .
1205 The \fIdevice\fR subsection recognizes the following attributes:
1206 .TP
1207 vendor, product, revision and product_blacklist are POSIX Extended regex.
1208 .TP 17
1209 .B vendor
1210 (Mandatory) Vendor identifier.
1211 .TP
1212 .B product
1213 (Mandatory) Product identifier.
1214 .TP
1215 .B revision
1216 Revision identfier.
1217 .TP
1218 .B product_blacklist
1219 Product strings to blacklist for this vendor.
1220 .TP
1221 .B alias_prefix
1222 The user_friendly_names prefix to use for this
1223 device type, instead of the default "mpath".
1224 .TP
1225 .B hardware_handler
1226 The hardware handler to use for this device type.
1227 The following hardware handler are implemented:
1228 .RS
1229 .TP 12
1230 .I 1 emc
1231 (Hardware-dependent)
1232 Hardware handler for DGC class arrays as CLARiiON CX/AX and EMC VNX and Unity
1233 families.
1234 .TP
1235 .I 1 rdac
1236 (Hardware-dependent)
1237 Hardware handler for LSI/Engenio/NetApp RDAC class as NetApp SANtricity E/EF
1238 Series, and OEM arrays from IBM DELL SGI STK and SUN.
1239 .TP
1240 .I 1 hp_sw
1241 (Hardware-dependent)
1242 Hardware handler for HP/COMPAQ/DEC HSG80 and MSA/HSV arrays with
1243 Active/Standby mode exclusively.
1244 .TP
1245 .I 1 alua
1246 (Hardware-dependent)
1247 Hardware handler for SCSI-3 ALUA compatible arrays.
1248 .PP
1249 The default is: \fB<unset>\fR
1250 .PP
1251 \fBImportant Note:\fR Linux kernels 4.3 and newer automatically attach a device
1252 handler to known devices (which includes all devices supporting SCSI-3 ALUA)
1253 and disallow changing the handler
1254 afterwards. Setting \fBhardware_handler\fR for such devices on these kernels
1255 has no effect.
1256 .RE
1257 .
1258 .
1259 .LP
1260 The following attributes are optional; if not set the default values
1261 are taken from the \fIdefaults\fR
1262 section:
1263 .sp 1
1264 .PD .1v
1265 .RS
1266 .TP 18
1267 .B path_grouping_policy
1268 .TP
1269 .B uid_attribute
1270 .TP
1271 .B path_selector
1272 .TP
1273 .B path_checker
1274 .TP
1275 .B prio
1276 .TP
1277 .B prio_args
1278 .TP
1279 .B features
1280 .TP
1281 .B failback
1282 .TP
1283 .B rr_weight
1284 .TP
1285 .B no_path_retry
1286 .TP
1287 .B rr_min_io
1288 .TP
1289 .B rr_min_io_rq
1290 .TP
1291 .B fast_io_fail_tmo
1292 .TP
1293 .B dev_loss_tmo
1294 .TP
1295 .B flush_on_last_del
1296 .TP
1297 .B retain_attached_hw_handler
1298 .TP
1299 .B detect_prio
1300 .TP
1301 .B detect_checker
1302 .TP
1303 .B deferred_remove
1304 .TP
1305 .B marginal_path_err_sample_time
1306 .TP
1307 .B marginal_path_err_rate_threshold
1308 .TP
1309 .B marginal_path_err_recheck_gap_time
1310 .TP
1311 .B marginal_path_double_failed_time
1312 .TP
1313 .B delay_watch_checks
1314 .TP
1315 .B delay_wait_checks
1316 .TP
1317 .B skip_kpartx
1318 .TP
1319 .B max_sectors_kb
1320 .RE
1321 .PD
1322 .LP
1323 .
1324 .
1325 .\" ----------------------------------------------------------------------------
1326 .SH "overrides section"
1327 .\" ----------------------------------------------------------------------------
1328 .
1329 The overrides section recognizes the following optional attributes; if not set
1330 the values are taken from the \fIdevices\fR or \fIdefaults\fR sections:
1331 .sp 1
1332 .PD .1v
1333 .RS
1334 .TP 18
1335 .B path_grouping_policy
1336 .TP
1337 .B uid_attribute
1338 .TP
1339 .B getuid_callout
1340 .TP
1341 .B path_selector
1342 .TP
1343 .B path_checker
1344 .TP
1345 .B alias_prefix
1346 .TP
1347 .B features
1348 .TP
1349 .B prio
1350 .TP
1351 .B prio_args
1352 .TP
1353 .B failback
1354 .TP
1355 .B rr_weight
1356 .TP
1357 .B no_path_retry
1358 .TP
1359 .B rr_min_io
1360 .TP
1361 .B rr_min_io_rq
1362 .TP
1363 .B flush_on_last_del
1364 .TP
1365 .B fast_io_fail_tmo
1366 .TP
1367 .B dev_loss_tmo
1368 .TP
1369 .B user_friendly_names
1370 .TP
1371 .B retain_attached_hw_handler
1372 .TP
1373 .B detect_prio
1374 .TP
1375 .B detect_checker
1376 .TP
1377 .B deferred_remove
1378 .TP
1379 .B marginal_path_err_sample_time
1380 .TP
1381 .B marginal_path_err_rate_threshold
1382 .TP
1383 .B marginal_path_err_recheck_gap_time
1384 .TP
1385 .B marginal_path_double_failed_time
1386 .TP
1387 .B delay_watch_checks
1388 .TP
1389 .B delay_wait_checks
1390 .TP
1391 .B skip_kpartx
1392 .RE
1393 .PD
1394 .LP
1395 .
1396 .
1397 .\" ----------------------------------------------------------------------------
1398 .SH "WWID generation"
1399 .\" ----------------------------------------------------------------------------
1400 .
1401 Multipath uses a \fIWorld Wide Identification\fR (WWID) to determine
1402 which paths belong to the same device. Each path presenting the same
1403 WWID is assumed to point to the same device.
1404 .LP
1405 The WWID is generated by three methods (in the order of preference):
1406 .TP 17
1407 .B getuid_callout
1408 Use the specified external program; cf \fIgetuid_callout\fR above.
1409 Care should be taken when using this method; the external program
1410 needs to be loaded from disk for execution, which might lead to
1411 deadlock situations in an all-paths-down scenario.
1412 .TP
1413 .B uid_attribute
1414 Use the value of the specified udev attribute; cf \fIuid_attribute\fR
1415 above. This method is preferred to \fIgetuid_callout\fR as multipath
1416 does not need to call any external programs here. However, under
1417 certain circumstances udev might not be able to generate the requested
1418 variable.
1419 .TP
1420 .B vpd_pg83
1421 If none of the \fIgetuid_callout\fR or \fIuid_attribute\fR parameters
1422 are present multipath will try to use the sysfs attribute
1423 \fIvpd_pg83\fR to generate the WWID.
1424 .
1425 .
1426 .\" ----------------------------------------------------------------------------
1427 .SH "KNOWN ISSUES"
1428 .\" ----------------------------------------------------------------------------
1429 .
1430 The usage of \fIqueue_if_no_path\fR option can lead to \fID state\fR
1431 processes being hung and not killable in situations where all the paths to the
1432 LUN go offline. It is advisable to use the \fIno_path_retry\fR option instead.
1433 .P
1434 The use of \fIqueue_if_no_path\fR or \fIno_path_retry\fR might lead to a
1435 deadlock if the \fIdev_loss_tmo\fR setting results in a device being removed
1436 while I/O is still queued. The multipath daemon will update the \fIdev_loss_tmo\fR
1437 setting accordingly to avoid this deadlock. Hence if both values are
1438 specified the order of precedence is \fIno_path_retry, queue_if_no_path, dev_loss_tmo\fR.
1439 .
1440 .
1441 .\" ----------------------------------------------------------------------------
1442 .SH "SEE ALSO"
1443 .\" ----------------------------------------------------------------------------
1444 .
1445 .BR udev (8),
1446 .BR dmsetup (8),
1447 .BR multipath (8),
1448 .BR multipathd (8).
1449 .
1450 .
1451 .\" ----------------------------------------------------------------------------
1452 .SH AUTHORS
1453 .\" ----------------------------------------------------------------------------
1454 .
1455 \fImultipath-tools\fR was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com>
1456 and others.
1457 .\" EOF