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