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