multipath/multipath.conf.5

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