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