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