3fe56bc090710d082546624f37118d26fcdfde32
[multipath-tools/.git] / multipath / multipath.conf.5
1 .TH MULTIPATH.CONF 5 "30 November 2006"
2 .SH NAME
3 multipath.conf \- multipath daemon configuration file
4 .SH DESCRIPTION
5 .B "multipath.conf"
6 is the configuration file for the multipath daemon. It is used to
7 overwrite the built-in configuration table of \fBmultipathd\fP.
8 Any line whose first non-white-space character is a '#' is considered
9 a comment line. Empty lines are ignored.
10 .SH SYNTAX
11 The configuration file contains entries of the form:
12 .RS
13 .nf
14 .ft B
15 .sp
16 <section> {
17 .RS
18 .ft B
19 <attribute> <value>
20 .I "..."
21 .ft B
22 <subsection> {
23 .RS
24 .ft B
25 <attribute> <value>
26 .I "..."
27 .RE
28 }
29 .RE
30 }
31 .ft R
32 .fi
33 .RE
34 .LP
35 Each \fIsection\fP contains one or more attributes or subsections. The
36 recognized keywords for attributes or subsections depend on the
37 section in which they occur.
38 .LP
39 The following \fIsection\fP keywords are recognized:
40 .TP 17
41 .B defaults
42 This section defines default values for attributes which are used
43 whenever no values are given in the appropriate device or multipath
44 sections.
45 .TP
46 .B blacklist
47 This section defines which devices should be excluded from the
48 multipath topology discovery.
49 .TP
50 .B blacklist_exceptions
51 This section defines which devices should be included in the
52 multipath topology discovery, despite being listed in the
53 .I blacklist
54 section.
55 .TP
56 .B multipaths
57 This section defines the multipath topologies. They are indexed by a
58 \fIWorld Wide Identifier\fR(wwid), which is taken to be the value of
59 the udev attribute given by the
60 \fIuid_attribute\fR keyword.
61 .TP
62 .B devices
63 This section defines the device-specific settings.
64 .TP
65 .B overrides
66 This section defines values for attributes that should override the
67 device-specific settings for all devices.
68 .RE
69 .LP
70 .SH "defaults section"
71 The
72 .B defaults
73 section recognizes the following keywords:
74 .TP 17
75 .B polling_interval
76 interval between two path checks in seconds. For properly functioning paths,
77 the interval between checks will gradually increase to
78 .B max_polling_interval.
79 This value will be overridden by the
80 .B WatchdogSec
81 setting in the multipathd.service definition if systemd is used.
82 Default is
83 .I 5
84 .TP
85 .B max_polling_interval
86 maximal interval between two path checks in seconds; default is
87 .I 4 * polling_interval
88 .TP
89 .B multipath_dir
90 directory where the dynamic shared objects are stored; default is system
91 dependent, commonly
92 .I /lib/multipath
93 .TP
94 .B verbosity
95 default verbosity. Higher values increase the verbosity level. Valid
96 levels are between 0 and 6; default is
97 .I 2
98 .TP
99 .B reassign_maps
100 enable reassigning of device-mapper maps. With this option multipathd
101 will remap existing device-mapper maps to always point to multipath
102 device, not the underlying block devices. Possible values are
103 \fIyes\fR and \fIno\fR. Default is
104 .I yes
105 .TP
106 .B path_selector
107 The default path selector algorithm to use; they are offered by the
108 kernel multipath target. There are three selector algorithms.
109 .RS
110 .TP 12
111 .B "round-robin 0"
112 Loop through every path in the path group, sending the same amount of IO to
113 each.
114 .TP
115 .B "queue-length 0"
116 Send the next bunch of IO down the path with the least amount of outstanding IO.
117 .TP
118 .B "service-time 0"
119 Choose the path for the next bunch of IO based on the amount of outstanding IO
120 to the path and its relative throughput.
121 .RE
122 .TP
123 .B path_grouping_policy
124 The default path grouping policy to apply to unspecified
125 multipaths. Possible values are
126 .RS
127 .TP 12
128 .B failover
129 1 path per priority group
130 .TP
131 .B multibus
132 all paths in 1 priority group
133 .TP
134 .B group_by_serial
135 1 priority group per serial number
136 .TP
137 .B group_by_prio
138 1 priority group per priority value. Priorities are determined by
139 callout programs specified as a global, per-controller or
140 per-multipath option in the configuration file.
141 .TP
142 .B group_by_node_name
143 1 priority group per target node name. Target node names are fetched
144 in /sys/class/fc_transport/target*/node_name.
145 .TP
146 Default value is \fIfailover\fR.
147 .RE
148 .TP
149 .B uid_attribute
150 The udev attribute providing a unique path
151 identifier. Default value is
152 .I ID_SERIAL
153 .TP
154 .B getuid_callout
155 The default program and args to callout to obtain a unique path
156 identifier. Should be specified with an absolute path.
157 This parameter is deprecated; \fIuid_attribute\fR should be used instead.
158 .TP
159 .B prio
160 The name of the path priority routine. The specified routine
161 should return a numeric value specifying the relative priority
162 of this path. Higher number have a higher priority.
163 .I "none"
164 is a valid value. Currently the following path priority routines
165 are implemented:
166 .RS
167 .TP 12
168 .B const
169 Return a constant priority of \fI1\fR.
170 .TP
171 .B emc
172 Generate the path priority for EMC arrays.
173 .TP
174 .B alua
175 Generate the path priority based on the SCSI-3 ALUA settings.
176 .TP
177 .B ontap
178 Generate the path priority for NetApp arrays.
179 .TP
180 .B rdac
181 Generate the path priority for LSI/Engenio/NetApp E-Series RDAC controller.
182 .TP
183 .B hp_sw
184 Generate the path priority for Compaq/HP controller in
185 active/standby mode.
186 .TP
187 .B hds
188 Generate the path priority for Hitachi HDS Modular storage arrays.
189 .TP
190 .B random
191 Generate a random priority between 1 and 10.
192 .TP 12
193 .B weightedpath
194 Generate the path priority based on the regular expression and the 
195 priority provided as argument. requires prio_args keyword.
196 .TP
197 Default value is \fBnone\fR.
198 .RE
199 .TP
200 .B prio_args
201 Arguments to pass to to the prio function.  Currently only used with
202 .I weighted, which needs a value of the form
203 .I "<hbtl|devname> <regex1> <prio1> <regex2> <prio2> ..."
204 .I hbtl
205 regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
206 .I devname
207 regex can be of device name format  Ex: sda , sd.e
208 .TP
209 .B features
210 Specify any device-mapper features to be used. Syntax is
211 .I num list
212 where
213 .I num
214 is the number of features in
215 .I list.
216 Possible values for the feature list are
217 .RS
218 .TP 12
219 .B queue_if_no_path
220 Queue IO if no path is active; identical to the
221 .I no_path_retry
222 keyword.
223 .TP
224 .B no_partitions
225 Disable automatic partitions generation via kpartx.
226 .RE
227 .TP
228 .B path_checker
229 The default method used to determine the paths state. Possible values
230 are
231 .RS
232 .TP 12
233 .B readsector0
234 (Deprecated) Read the first sector of the device. This checker is being
235 deprecated, please use \fIdirectio\fR instead
236 .TP
237 .B tur
238 Issue a
239 .I TEST UNIT READY
240 command to the device.
241 .TP
242 .B emc_clariion
243 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
244 state.
245 .TP
246 .B hp_sw
247 Check the path state for HP storage arrays with Active/Standby firmware.
248 .TP
249 .B rdac
250 Check the path state for LSI/Engenio/NetApp E-Series RDAC storage controller.
251 .TP
252 .B directio
253 Read the first sector with direct I/O.
254 .TP
255 Default value is \fIdirectio\fR.
256 .RE
257 .TP
258 .B failback
259 Tell multipathd how to manage path group failback.
260 .RS
261 .TP 12
262 .B immediate
263 Immediately failback to the highest priority pathgroup that contains
264 active paths.
265 .TP
266 .B manual
267 Do not perform automatic failback.
268 .TP
269 .B followover
270 Only perform automatic failback when the first path of a pathgroup
271 becomes active. This keeps a node from automatically failing back when
272 another node requested the failover.
273 .TP
274 .B values > 0
275 deferred failback (time to defer in seconds)
276 .TP
277 Default value is \fImanual\fR.
278 .RE
279 .TP
280 .B  rr_min_io
281 The number of IO to route to a path before switching to the next in
282 the same path group. This is only for BIO based multipath. Default is
283 .I 1000
284 .TP
285 .B rr_min_io_rq
286 The number of IO requests to route to a path before switching to the
287 next in the same path group. This is only for request based multipath.
288 Default is
289 .I 1
290 .TP
291 .B rr_weight
292 If set to \fIpriorities\fR the multipath configurator will assign
293 path weights as "path prio * rr_min_io". Possible values are
294 .I priorities
295 or
296 .IR uniform .
297 Default is
298 .IR uniform .
299 .TP
300 .B no_path_retry
301 Specify the number of retries until disable queueing, or
302 .I fail
303 for immediate failure (no queueing),
304 .I queue
305 for never stop queueing. If unset no queueing is attempted.
306 Default is unset.
307 .TP
308 .B user_friendly_names
309 If set to 
310 .I yes
311 , using the bindings file
312 .I /etc/multipath/bindings
313 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
314 If set to 
315 .I no
316 use the WWID as the alias. In either case this be will
317 be overridden by any specific aliases in the \fImultipaths\fR section.
318 Default is
319 .I no
320 .TP
321 .B flush_on_last_del
322 If set to
323 .I yes
324 , multipathd will disable queueing when the last path to a device has been
325 deleted. Default is
326 .I no
327 .TP
328 .B max_fds
329 Specify the maximum number of file descriptors that can be opened by multipath
330 and multipathd.  This is equivalent to ulimit \-n. A value of \fImax\fR will set
331 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
332 maximum number of open fds is taken from the calling process. It is usually
333 1024. To be safe, this should be set to the maximum number of paths plus 32,
334 if that number is greated than 1024.
335 .TP
336 .B checker_timeout
337 Specify the timeout to use for path checkers and prioritizers that issue scsi
338 commands with an explicit timeout, in seconds; default taken from
339 .I /sys/block/sd<x>/device/timeout
340 .TP
341 .B fast_io_fail_tmo
342 Specify the number of seconds the scsi layer will wait after a problem has been
343 detected on a FC remote port before failing IO to devices on that remote port.
344 This should be smaller than dev_loss_tmo. Setting this to
345 .I off
346 will disable the timeout.
347 .TP
348 .B dev_loss_tmo
349 Specify the number of seconds the scsi layer will wait after a problem has
350 been detected on a FC remote port before removing it from the system. This
351 can be set to "infinity" which sets it to the max value of 2147483647
352 seconds, or 68 years. It will be automatically adjusted to the overall
353 retry interval
354 \fIno_path_retry\fR * \fIpolling_interval\fR
355 if a number of retries is given with \fIno_path_retry\fR and the
356 overall retry interval is longer than the specified \fIdev_loss_tmo\fR value.
357 The linux kernel will cap this value to \fI300\fR if \fBfast_io_fail_tmo\fR
358 is not set.
359 .TP
360 .B queue_without_daemon
361 If set to
362 .I no
363 , when multipathd stops, queueing will be turned off for all devices.
364 This is useful for devices that set no_path_retry.  If a machine is
365 shut down while all paths to a device are down, it is possible to hang waiting
366 for IO to return from the device after multipathd has been stopped. Without
367 multipathd running, access to the paths cannot be restored, and the kernel
368 cannot be told to stop queueing IO. Setting queue_without_daemon to
369 .I no
370 , avoids this problem. Default is
371 .I yes
372 .TP
373 .B bindings_file
374 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
375 .I /etc/multipath/bindings
376 .TP
377 .B wwids_file
378 The full pathname of the wwids file, which is used by multipath to keep track
379 of the wwids for LUNs it has created multipath devices on in the past.
380 Defaults to
381 .I /etc/multipath/wwids
382 .TP
383 .B log_checker_err
384 If set to
385 .I once
386 , multipathd logs the first path checker error at logging level 2. Any later
387 errors are logged at level 3 until the device is restored. If set to
388 .I always
389 , multipathd always logs the path checker error at logging level 2. Default is
390 .I always
391 .TP
392 .B reservation_key
393 This is the service action reservation key used by mpathpersist.  It must be
394 set for all multipath devices using persistent reservations, and it must be
395 the same as the RESERVATION KEY field of the PERSISTENT RESERVE OUT parameter
396 list which contains an 8-byte value provided by the application client to the
397 device server to identify the I_T nexus. It is unset by default.
398 .TP
399 .B retain_attached_hw_handler
400 If set to
401 .I yes
402 and the scsi layer has already attached a hardware_handler to the device,
403 multipath will not force the device to use the hardware_handler specified by
404 mutipath.conf. If the scsi layer has not attached a hardware handler,
405 multipath will continue to use its configured hardware handler. Default is
406 .I no
407 .TP
408 .B detect_prio
409 If set to
410 .I yes
411 , multipath will try to detect if the device supports ALUA. If so, the device
412 will automatically use the
413 .I alua
414 prioritizer. If not, the prioritizer will be selected as usual. Default is
415 .I no
416 .TP
417 .B force_sync
418 If set to
419 .I yes
420 , multipathd will call the path checkers in sync mode only.  This means that
421 only one checker will run at a time.  This is useful in the case where many
422 multipathd checkers running in parallel causes significant CPU pressure. The
423 Default is
424 .I no
425 .TP
426 .B deferred_remove
427 If set to
428 .I yes
429 , multipathd will do a deferred remove instead of a regular remove when the
430 last path device has been deleted.  This means that if the multipath device is
431 still in use, it will be freed when the last user closes it.  If path is added
432 to the multipath device before the last user closes it, the deferred remove
433 will be canceled. Default is
434 .I no
435 .TP
436 .B config_dir
437 If set to anything other than "", multipath will search this directory
438 alphabetically for file ending in ".conf" and it will read configuration
439 information from them, just as if it was in /etc/multipath.conf.  config_dir
440 must either be "" or a fully qualified directory name. Default is
441 .I "/etc/multipath/conf.d"
442 .TP
443 .B delay_watch_checks
444 If set to a value greater than 0, multipathd will watch paths that have
445 recently become valid for this many checks.  If they fail again while they are
446 being watched, when they next become valid, they will not be used until they
447 have stayed up for
448 .I delay_wait_checks
449 checks. Default is
450 .I no
451 .TP
452 .B delay_wait_checks
453 If set to a value greater than 0, when a device that has recently come back
454 online fails again within
455 .I delay_watch_checks
456 checks, the next time it comes back online, it will marked and delayed, and not
457 used until it has passed
458 .I delay_wait_checks
459 checks. Default is
460 .I no
461 .
462 .SH "blacklist section"
463 The
464 .I blacklist
465 section is used to exclude specific device from inclusion in the
466 multipath topology. It is most commonly used to exclude local disks or
467 LUNs for the array controller.
468 .LP
469 The following keywords are recognized:
470 .TP 17
471 .B wwid
472 The \fIWorld Wide Identification\fR of a device.
473 .TP
474 .B devnode
475 Regular expression of the device nodes to be excluded.
476 .TP
477 .B property
478 Regular expression of the udev property to be excluded.
479 .TP
480 .B device
481 Subsection for the device description. This subsection recognizes the
482 .I vendor
483 and
484 .I product
485 keywords. For a full description of these keywords please see the
486 .I devices
487 section description.
488 .SH "blacklist_exceptions section"
489 The
490 .I blacklist_exceptions
491 section is used to revert the actions of the
492 .I blacklist
493 section, ie to include specific device in the
494 multipath topology. This allows one to selectively include devices which
495 would normally be excluded via the
496 .I blacklist
497 section.
498 .LP
499 The following keywords are recognized:
500 .TP 17
501 .B wwid
502 The \fIWorld Wide Identification\fR of a device.
503 .TP
504 .B property
505 Regular expression of the udev property to be whitelisted. Defaults to
506 .I (ID_WWN|ID_SCSI_VPD)
507 .TP
508 .B devnode
509 Regular expression of the device nodes to be whitelisted.
510 .TP
511 .B device
512 Subsection for the device description. This subsection recognizes the
513 .I vendor
514 and
515 .I product
516 keywords. For a full description of these keywords please see the
517 .I devices
518 section description.
519 .LP
520 The
521 .I property
522 blacklist and whitelist handling is different from the usual handling
523 in the sense that the whitelist
524 .B has
525 to be set, otherwise the device will be blacklisted.
526 In these cases the message
527 .I blacklisted, udev property missing
528 will be displayed.
529 .SH "multipaths section"
530 The only recognized attribute for the
531 .B multipaths
532 section is the
533 .I multipath
534 subsection.
535 .LP
536 The
537 .B multipath
538 subsection recognizes the following attributes:
539 .TP 17
540 .B wwid
541 Index of the container. Mandatory for this subsection.
542 .TP
543 .B alias
544 (Optional) symbolic name for the multipath map.
545 .LP
546 The following attributes are optional; if not set the default values
547 are taken from the
548 .I defaults
549 or
550 .I devices
551 section:
552 .sp 1
553 .PD .1v
554 .RS
555 .TP 18
556 .B path_grouping_policy
557 .TP
558 .B path_selector
559 .TP
560 .B prio
561 .TP
562 .B prio_args
563 .TP
564 .B failback
565 .TP
566 .B rr_weight
567 .TP
568 .B flush_on_last_del
569 .TP
570 .B no_path_retry
571 .TP
572 .B rr_min_io
573 .TP
574 .B rr_min_io_rq
575 .TP
576 .B features
577 .TP
578 .B reservation_key
579 .TP
580 .B deferred_remove
581 .TP
582 .B delay_watch_checks
583 .TP
584 .B delay_wait_checks
585 .RE
586 .PD
587 .LP
588 .SH "devices section"
589 The only recognized attribute for the
590 .B devices
591 section is the
592 .I device
593 subsection.
594 .LP
595 The
596 .I device
597 subsection recognizes the following attributes:
598 .TP 17
599 .B vendor
600 (Mandatory) Vendor identifier
601 .TP
602 .B product
603 (Mandatory) Product identifier
604 .TP
605 .B revision
606 (Optional) Revision identfier
607 .TP
608 .B product_blacklist
609 (Optional) Product strings to blacklist for this vendor
610 .TP
611 .B alias_prefix
612 (Optional) The user_friendly_names prefix to use for this
613 device type, instead of the default "mpath"
614 .TP
615 .B hardware_handler
616 (Optional) The hardware handler to use for this device type.
617 The following hardware handler are implemented:
618 .RS
619 .TP 12
620 .B 1 emc
621 Hardware handler for EMC storage arrays.
622 .TP
623 .B 1 rdac
624 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
625 .TP
626 .B 1 hp_sw
627 Hardware handler for Compaq/HP storage arrays in active/standby
628 mode.
629 .TP
630 .B 1 alua
631 Hardware handler for SCSI-3 ALUA compatible arrays.
632 .RE
633 .LP
634 The following attributes are optional; if not set the default values
635 are taken from the
636 .I defaults
637 section:
638 .sp 1
639 .PD .1v
640 .RS
641 .TP 18
642 .B path_grouping_policy
643 .TP
644 .B uid_attribute
645 .TP
646 .B path_selector
647 .TP
648 .B path_checker
649 .TP
650 .B prio
651 .TP
652 .B prio_args
653 .TP
654 .B features
655 .TP
656 .B failback
657 .TP
658 .B rr_weight
659 .TP
660 .B no_path_retry
661 .TP
662 .B rr_min_io
663 .TP
664 .B rr_min_io_rq
665 .TP
666 .B fast_io_fail_tmo
667 .TP
668 .B dev_loss_tmo
669 .TP
670 .B flush_on_last_del
671 .TP
672 .B retain_attached_hw_handler
673 .TP
674 .B detect_prio
675 .TP
676 .B deferred_remove
677 .TP
678 .B delay_watch_checks
679 .TP
680 .B delay_wait_checks
681 .RE
682 .PD
683 .LP
684 .SH "overrides section"
685 The overrides section recognizes the following optional attributes; if not set
686 the values are taken from the
687 .I devices
688 or
689 .I defaults
690 sections:
691 .sp 1
692 .PD .1v
693 .RS
694 .TP 18
695 .B path_grouping_policy
696 .TP
697 .B uid_attribute
698 .TP
699 .B getuid_callout
700 .TP
701 .B path_selector
702 .TP
703 .B path_checker
704 .TP
705 .B alias_prefix
706 .TP
707 .B features
708 .TP
709 .B prio
710 .TP
711 .B prio_args
712 .TP
713 .B failback
714 .TP
715 .B rr_weight
716 .TP
717 .B no_path_retry
718 .TP
719 .B rr_min_io
720 .TP
721 .B rr_min_io_rq
722 .TP
723 .B flush_on_last_del
724 .TP
725 .B fast_io_fail_tmo
726 .TP
727 .B dev_loss_tmo
728 .TP
729 .B user_friendly_names
730 .TP
731 .B retain_attached_hw_handler
732 .TP
733 .B detect_prio
734 .TP
735 .B deferred_remove
736 .TP
737 .B delay_watch_checks
738 .TP
739 .B delay_wait_checks
740 .RE
741 .PD
742 .LP
743 .SH "KNOWN ISSUES"
744 The usage of
745 .B queue_if_no_path
746 option can lead to
747 .B D state
748 processes being hung and not killable in situations where all the paths to the LUN go offline.
749 It is advisable to use the
750 .B no_path_retry
751 option instead.
752 .P
753 The use of
754 .B queue_if_no_path
755 or
756 .B no_path_retry
757 might lead to a deadlock if the
758 .B dev_loss_tmo
759 setting results in a device being removed while I/O is still queued.
760 The multipath daemon will update the
761 .B dev_loss_tmo
762 setting accordingly to avoid this deadlock. Hence if both values are
763 specified the order of precedence is
764 .I no_path_retry, queue_if_no_path, dev_loss_tmo
765
766 .SH "SEE ALSO"
767 .BR udev (8),
768 .BR dmsetup (8)
769 .BR multipath (8)
770 .BR multipathd (8)
771 .SH AUTHORS
772 .B multipath
773 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.