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