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