multipathd: add deferred_remove support
[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 .
436 .SH "blacklist section"
437 The
438 .I blacklist
439 section is used to exclude specific device from inclusion in the
440 multipath topology. It is most commonly used to exclude local disks or
441 LUNs for the array controller.
442 .LP
443 The following keywords are recognized:
444 .TP 17
445 .B wwid
446 The \fIWorld Wide Identification\fR of a device.
447 .TP
448 .B devnode
449 Regular expression of the device nodes to be excluded.
450 .TP
451 .B property
452 Regular expression of the udev property to be excluded.
453 .TP
454 .B device
455 Subsection for the device description. This subsection recognizes the
456 .I vendor
457 and
458 .I product
459 keywords. For a full description of these keywords please see the
460 .I devices
461 section description.
462 .SH "blacklist_exceptions section"
463 The
464 .I blacklist_exceptions
465 section is used to revert the actions of the
466 .I blacklist
467 section, ie to include specific device in the
468 multipath topology. This allows one to selectively include devices which
469 would normally be excluded via the
470 .I blacklist
471 section.
472 .LP
473 The following keywords are recognized:
474 .TP 17
475 .B wwid
476 The \fIWorld Wide Identification\fR of a device.
477 .TP
478 .B property
479 Regular expression of the udev property to be whitelisted. Defaults to
480 .I (ID_WWN|ID_SCSI_VPD)
481 .TP
482 .B devnode
483 Regular expression of the device nodes to be whitelisted.
484 .TP
485 .B device
486 Subsection for the device description. This subsection recognizes the
487 .I vendor
488 and
489 .I product
490 keywords. For a full description of these keywords please see the
491 .I devices
492 section description.
493 .LP
494 The
495 .I property
496 blacklist and whitelist handling is different from the usual handling
497 in the sense that the whitelist
498 .B has
499 to be set, otherwise the device will be blacklisted.
500 In these cases the message
501 .I blacklisted, udev property missing
502 will be displayed.
503 .SH "multipaths section"
504 The only recognized attribute for the
505 .B multipaths
506 section is the
507 .I multipath
508 subsection.
509 .LP
510 The
511 .B multipath
512 subsection recognizes the following attributes:
513 .TP 17
514 .B wwid
515 Index of the container. Mandatory for this subsection.
516 .TP
517 .B alias
518 (Optional) symbolic name for the multipath map.
519 .LP
520 The following attributes are optional; if not set the default values
521 are taken from the
522 .I defaults
523 or
524 .I devices
525 section:
526 .sp 1
527 .PD .1v
528 .RS
529 .TP 18
530 .B path_grouping_policy
531 .TP
532 .B path_selector
533 .TP
534 .B prio
535 .TP
536 .B prio_args
537 .TP
538 .B failback
539 .TP
540 .B rr_weight
541 .TP
542 .B flush_on_last_del
543 .TP
544 .B no_path_retry
545 .TP
546 .B rr_min_io
547 .TP
548 .B rr_min_io_rq
549 .TP
550 .B features
551 .TP
552 .B reservation_key
553 .TP
554 .B deferred_remove
555 .RE
556 .PD
557 .LP
558 .SH "devices section"
559 The only recognized attribute for the
560 .B devices
561 section is the
562 .I device
563 subsection.
564 .LP
565 The
566 .I device
567 subsection recognizes the following attributes:
568 .TP 17
569 .B vendor
570 (Mandatory) Vendor identifier
571 .TP
572 .B product
573 (Mandatory) Product identifier
574 .TP
575 .B revision
576 (Optional) Revision identfier
577 .TP
578 .B product_blacklist
579 (Optional) Product strings to blacklist for this vendor
580 .TP
581 .B alias_prefix
582 (Optional) The user_friendly_names prefix to use for this
583 device type, instead of the default "mpath"
584 .TP
585 .B hardware_handler
586 (Optional) The hardware handler to use for this device type.
587 The following hardware handler are implemented:
588 .RS
589 .TP 12
590 .B 1 emc
591 Hardware handler for EMC storage arrays.
592 .TP
593 .B 1 rdac
594 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
595 .TP
596 .B 1 hp_sw
597 Hardware handler for Compaq/HP storage arrays in active/standby
598 mode.
599 .TP
600 .B 1 alua
601 Hardware handler for SCSI-3 ALUA compatible arrays.
602 .RE
603 .LP
604 The following attributes are optional; if not set the default values
605 are taken from the
606 .I defaults
607 section:
608 .sp 1
609 .PD .1v
610 .RS
611 .TP 18
612 .B path_grouping_policy
613 .TP
614 .B uid_attribute
615 .TP
616 .B path_selector
617 .TP
618 .B path_checker
619 .TP
620 .B prio
621 .TP
622 .B prio_args
623 .TP
624 .B features
625 .TP
626 .B failback
627 .TP
628 .B rr_weight
629 .TP
630 .B no_path_retry
631 .TP
632 .B rr_min_io
633 .TP
634 .B rr_min_io_rq
635 .TP
636 .B fast_io_fail_tmo
637 .TP
638 .B dev_loss_tmo
639 .TP
640 .B flush_on_last_del
641 .TP
642 .B retain_attached_hw_handler
643 .TP
644 .B detect_prio
645 .TP
646 .B deferred_remove
647 .RE
648 .PD
649 .LP
650 .SH "overrides section"
651 The overrides section recognizes the following optional attributes; if not set
652 the values are taken from the
653 .I devices
654 or
655 .I defaults
656 sections:
657 .sp 1
658 .PD .1v
659 .RS
660 .TP 18
661 .B path_grouping_policy
662 .TP
663 .B uid_attribute
664 .TP
665 .B getuid_callout
666 .TP
667 .B path_selector
668 .TP
669 .B path_checker
670 .TP
671 .B alias_prefix
672 .TP
673 .B features
674 .TP
675 .B prio
676 .TP
677 .B prio_args
678 .TP
679 .B failback
680 .TP
681 .B rr_weight
682 .TP
683 .B no_path_retry
684 .TP
685 .B rr_min_io
686 .TP
687 .B rr_min_io_rq
688 .TP
689 .B flush_on_last_del
690 .TP
691 .B fast_io_fail_tmo
692 .TP
693 .B dev_loss_tmo
694 .TP
695 .B user_friendly_names
696 .TP
697 .B retain_attached_hw_handler
698 .TP
699 .B detect_prio
700 .TP
701 .B deferred_remove
702 .RE
703 .PD
704 .LP
705 .SH "KNOWN ISSUES"
706 The usage of
707 .B queue_if_no_path
708 option can lead to
709 .B D state
710 processes being hung and not killable in situations where all the paths to the LUN go offline.
711 It is advisable to use the
712 .B no_path_retry
713 option instead.
714 .P
715 The use of
716 .B queue_if_no_path
717 or
718 .B no_path_retry
719 might lead to a deadlock if the
720 .B dev_loss_tmo
721 setting results in a device being removed while I/O is still queued.
722 The multipath daemon will update the
723 .B dev_loss_tmo
724 setting accordingly to avoid this deadlock. Hence if both values are
725 specified the order of precedence is
726 .I no_path_retry, queue_if_no_path, dev_loss_tmo
727
728 .SH "SEE ALSO"
729 .BR udev (8),
730 .BR dmsetup (8)
731 .BR multipath (8)
732 .BR multipathd (8)
733 .SH AUTHORS
734 .B multipath
735 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.