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