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