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