multipath/multipath.conf.5

   1 .TH MULTIPATH.CONF 5 "30 November 2006"
   2 .SH NAME
   3 multipath.conf \- multipath daemon configuration file
   4 .SH DESCRIPTION
   5 .B "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 }
  29 .RE
  30 }
  31 .ft R
  32 .fi
  33 .RE
  34 .LP
  35 Each \fIsection\fP contains one or more attributes or subsections. The
  36 recognized keywords for attributes or subsections depend on the
  37 section in which they occor.
  38 .LP
  39 The following \fIsection\fP keywords are recognized:
  40 .TP 17
  41 .B defaults
  42 This section defines default values for attributes which are used
  43 whenever no values are given in the appropriate device or multipath
  44 sections.
  45 .TP
  46 .B blacklist
  47 This section defines which devices should be excluded from the
  48 multipath topology discovery.
  49 .TP
  50 .B blacklist_exceptions
  51 This section defines which devices should be included in the
  52 multipath topology discovery, despite being listed in the
  53 .I blacklist
  54 section.
  55 .TP
  56 .B multipaths
  57 This section defines the multipath topologies. They are indexed by a
  58 \fIWorld Wide Identifier\fR(wwid), which is the result of the
  59 \fIgetuid_callout\fR program.
  60 .TP
  61 .B devices
  62 This section defines the device-specific settings.
  63 .RE
  64 .LP
  65 .SH "defaults section"
  66 The
  67 .B defaults
  68 section recognizes the following keywords:
  69 .TP 17
  70 .B polling_interval
  71 interval between two path checks in seconds. For properly functioning paths,
  72 the interval between checks will gradually increase to
  73 .B max_polling_interval;
  74 default is
  75 .I 5
  76 .TP
  77 .B max_polling_interval
  78 maximal interval between two path checks in seconds; default is
  79 .I 4 * polling_interval
  80 .TP
  81 .B udev_dir
  82 directory where udev creates its device nodes; default is
  83 .I /dev
  84 .TP
  85 .B multipath_dir
  86 directory where the dynamic shared objects are stored; default is system
  87 dependent, commonly
  88 .I /lib/multipath
  89 .TP
  90 .B verbosity
  91 default verbosity. Higher values increase the verbosity level. Valid
  92 levels are between 0 and 6; default is
  93 .I 2
  94 .TP
  95 .B reassign_maps
  96 enable reassigning of device-mapper maps. With this option multipathd
  97 will remap existing device-mapper maps to always point to multipath
  98 device, not the underlying block devices. Possible values are
  99 \fIyes\fR and \fIno\fR. Default is
 100 .I yes
 101 .TP
 102 .B path_selector
 103 The default path selector algorithm to use; they are offered by the
 104 kernel multipath target. There are three selector algorithms.
 105 .RS
 106 .TP 12
 107 .B "round-robin 0"
 108 Loop through every path in the path group, sending the same amount of IO to
 109 each.
 110 .TP
 111 .B "queue-length 0"
 112 Send the next bunch of IO down the path with the least amount of outstanding IO.
 113 .TP
 114 .B "service-time 0"
 115 Choose the path for the next bunch of IO based on the amount of outstanding IO
 116 to the path and its relative throughput.
 117 .RE
 118 .TP
 119 .B path_grouping_policy
 120 The default path grouping policy to apply to unspecified
 121 multipaths. Possible values are
 122 .RS
 123 .TP 12
 124 .B failover
 125 1 path per priority group
 126 .TP
 127 .B multibus
 128 all paths in 1 priority group
 129 .TP
 130 .B group_by_serial
 131 1 priority group per serial number
 132 .TP
 133 .B group_by_prio
 134 1 priority group per priority value. Priorities are determined by
 135 callout programs specified as a global, per-controller or
 136 per-multipath option in the configuration file.
 137 .TP
 138 .B group_by_node_name
 139 1 priority group per target node name. Target node names are fetched
 140 in /sys/class/fc_transport/target*/node_name.
 141 .TP
 142 Default value is \fImultibus\fR.
 143 .RE
 144 .TP
 145 .B getuid_callout
 146 The default program and args to callout to obtain a unique path
 147 identifier. Should be specified with an absolute path. Default value
 148 is
 149 .I /lib/udev/scsi_id --whitelisted --replace-whitespace --device=/dev/%n
 150 .TP
 151 .B prio
 152 The name of the path priority routine. The specified routine
 153 should return a numeric value specifying the relative priority
 154 of this path. Higher number have a higher priority.
 155 .I "none"
 156 is a valid value. Currently the following path priority routines
 157 are implemented:
 158 .RS
 159 .TP 12
 160 .B const
 161 Return a constant priority of \fI1\fR.
 162 .TP
 163 .B emc
 164 Generate the path priority for EMC arrays.
 165 .TP
 166 .B alua
 167 Generate the path priority based on the SCSI-3 ALUA settings.
 168 .TP
 169 .B ontap
 170 Generate the path priority for NetApp arrays.
 171 .TP
 172 .B rdac
 173 Generate the path priority for LSI/Engenio/NetApp E-Series RDAC controller.
 174 .TP
 175 .B hp_sw
 176 Generate the path priority for Compaq/HP controller in
 177 active/standby mode.
 178 .TP
 179 .B hds
 180 Generate the path priority for Hitachi HDS Modular storage arrays.
 181 .TP
 182 .B random
 183 Generate a random priority between 1 and 10.
 184 .TP 12
 185 .B weightedpath
 186 Generate the path priority based on the regular expression and the
 187 priority provided as argument. requires prio_args keyword.
 188 .TP
 189 Default value is \fBnone\fR.
 190 .RE
 191 .TP
 192 .B prio_args
 193 Arguments to pass to to the prio function.  Currently only used with
 194 .I weighted, which needs a value of the form
 195 .I "<hbtl|devname> <regex1> <prio1> <regex2> <prio2> ..."
 196 .I hbtl
 197 regex can be of SCSI H:B:T:L format  Ex: 1:0:.:. , *:0:0:.
 198 .I devname
 199 regex can be of device name format  Ex: sda , sd.e
 200 .TP
 201 .B features
 202 Specify any device-mapper features to be used. Syntax is
 203 .I num list
 204 where
 205 .I num
 206 is the number of features in
 207 .I list.
 208 Possible values for the feature list are
 209 .RS
 210 .TP 12
 211 .B queue_if_no_path
 212 Queue IO if no path is active; identical to the
 213 .I no_path_retry
 214 keyword.
 215 .TP
 216 .B no_partitions
 217 Disable automatic partitions generation via kpartx.
 218 .RE
 219 .TP
 220 .B path_checker
 221 The default method used to determine the paths state. Possible values
 222 are
 223 .RS
 224 .TP 12
 225 .B readsector0
 226 (Deprecated) Read the first sector of the device. This checker is being
 227 deprecated, please use \fIdirectio\fR instead
 228 .TP
 229 .B tur
 230 Issue a
 231 .I TEST UNIT READY
 232 command to the device.
 233 .TP
 234 .B emc_clariion
 235 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
 236 state.
 237 .TP
 238 .B hp_sw
 239 Check the path state for HP storage arrays with Active/Standby firmware.
 240 .TP
 241 .B rdac
 242 Check the path state for LSI/Engenio/NetApp E-Series RDAC storage controller.
 243 .TP
 244 .B directio
 245 Read the first sector with direct I/O.
 246 .TP
 247 Default value is \fIdirectio\fR.
 248 .RE
 249 .TP
 250 .B failback
 251 Tell multipathd how to manage path group failback.
 252 .RS
 253 .TP 12
 254 .B immediate
 255 Immediately failback to the highest priority pathgroup that contains
 256 active paths.
 257 .TP
 258 .B manual
 259 Do not perform automatic failback.
 260 .TP
 261 .B values > 0
 262 deferred failback (time to defer in seconds)
 263 .TP
 264 Default value is \fImanual\fR.
 265 .RE
 266 .TP
 267 .B  rr_min_io
 268 The number of IO to route to a path before switching to the next in
 269 the same path group. This is only for BIO based multipath. Default is
 270 .I 1000
 271 .TP
 272 .B rr_min_io_q
 273 The number of IO requests to route to a path before switching to the
 274 next in the same path group. This is only for request based multipath.
 275 Default is
 276 .I 1
 277 .TP
 278 .B rr_weight
 279 If set to \fIpriorities\fR the multipath configurator will assign
 280 path weights as "path prio * rr_min_io". Possible values are
 281 .I priorities
 282 or
 283 .IR uniform .
 284 Default is
 285 .IR uniform .
 286 .TP
 287 .B no_path_retry
 288 Specify the number of retries until disable queueing, or
 289 .I fail
 290 for immediate failure (no queueing),
 291 .I queue
 292 for never stop queueing. Default is 0.
 293 .TP
 294 .B user_friendly_names
 295 If set to
 296 .I yes
 297 , using the bindings file
 298 .I /etc/multipath/bindings
 299 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
 300 If set to
 301 .I no
 302 use the WWID as the alias. In either case this be will
 303 be overriden by any specific aliases in the \fImultipaths\fR section.
 304 Default is
 305 .I no
 306 .TP
 307 .B flush_on_last_del
 308 If set to
 309 .I yes
 310 , multipathd will disable queueing when the last path to a device has been
 311 deleted. Default is
 312 .I no
 313 .TP
 314 .B max_fds
 315 Specify the maximum number of file descriptors that can be opened by multipath
 316 and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
 317 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
 318 maximum number of open fds is taken from the calling process. It is usually
 319 1024. To be safe, this should be set to the maximum number of paths plus 32,
 320 if that number is greated than 1024.
 321 .TP
 322 .B checker_timeout
 323 Specify the timeout to user for path checkers that issue scsi commands with an
 324 explict timeout, in seconds; default taken from
 325 .I /sys/block/sd<x>/device/timeout
 326 .TP
 327 .B fast_io_fail_tmo
 328 Specify the number of seconds the scsi layer will wait after a problem has been
 329 detected on a FC remote port before failing IO to devices on that remote port.
 330 This should be smaller than dev_loss_tmo. Setting this to
 331 .I off
 332 will disable the timeout.
 333 .TP
 334 .B dev_loss_tmo
 335 Specify the number of seconds the scsi layer will wait after a problem has
 336 been detected on a FC remote port before removing it from the system. This
 337 can be set to "infinity" which sets it to the max value of 2147483647
 338 seconds, or 68 years.
 339 .TP
 340 .B queue_without_daemon
 341 If set to
 342 .I no
 343 , when multipathd stops, queueing will be turned off for all devices.
 344 This is useful for devices that set no_path_retry.  If a machine is
 345 shut down while all paths to a device are down, it is possible to hang waiting
 346 for IO to return from the device after multipathd has been stopped. Without
 347 multipathd running, access to the paths cannot be restored, and the kernel
 348 cannot be told to stop queueing IO. Setting queue_without_daemon to
 349 .I no
 350 , avoids this problem. Default is
 351 .I yes
 352 .TP
 353 .B bindings_file
 354 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
 355 .I /var/lib/multipath/bindings
 356 .TP
 357 .B log_checker_err
 358 If set to
 359 .I once
 360 , multipathd logs the first path checker error at logging level 2. Any later
 361 errors are logged at level 3 until the device is restored. If set to
 362 .I always
 363 , multipathd always logs the path checker error at logging level 2. Default is
 364 .I always
 365 .
 366 .SH "blacklist section"
 367 The
 368 .I blacklist
 369 section is used to exclude specific device from inclusion in the
 370 multipath topology. It is most commonly used to exclude local disks or
 371 LUNs for the array controller.
 372 .LP
 373 The following keywords are recognized:
 374 .TP 17
 375 .B wwid
 376 The \fIWorld Wide Identification\fR of a device.
 377 .TP
 378 .B devnode
 379 Regular expression of the device nodes to be excluded.
 380 .TP
 381 .B device
 382 Subsection for the device description. This subsection recognizes the
 383 .I vendor
 384 and
 385 .I product
 386 keywords. For a full description of these keywords please see the
 387 .I devices
 388 section description.
 389 .SH "blacklist_exceptions section"
 390 The
 391 .I blacklist_exceptions
 392 section is used to revert the actions of the
 393 .I blacklist
 394 section, ie to include specific device in the
 395 multipath topology. This allows to selectively include devices which
 396 would normally be excluded via the
 397 .I blacklist
 398 section.
 399 .LP
 400 The following keywords are recognized:
 401 .TP 17
 402 .B wwid
 403 The \fIWorld Wide Identification\fR of a device.
 404 .TP
 405 .B devnode
 406 Regular expression of the device nodes to be excluded.
 407 .TP
 408 .B device
 409 Subsection for the device description. This subsection recognizes the
 410 .I vendor
 411 and
 412 .I product
 413 keywords. For a full description of these keywords please see the
 414 .I devices
 415 section description.
 416 .SH "multipaths section"
 417 The only recognized attribute for the
 418 .B multipaths
 419 section is the
 420 .I multipath
 421 subsection.
 422 .LP
 423 The
 424 .B multipath
 425 subsection recognizes the following attributes:
 426 .TP 17
 427 .B wwid
 428 Index of the container. Mandatory for this subsection.
 429 .TP
 430 .B alias
 431 (Optional) symbolic name for the multipath map.
 432 .LP
 433 The following attributes are optional; if not set the default values
 434 are taken from the
 435 .I defaults
 436 or
 437 .I devices
 438 section:
 439 .sp 1
 440 .PD .1v
 441 .RS
 442 .TP 18
 443 .B path_grouping_policy
 444 .TP
 445 .B path_selector
 446 .TP
 447 .B prio
 448 .TP
 449 .B prio_args
 450 .TP
 451 .B failback
 452 .TP
 453 .B rr_weight
 454 .TP
 455 .B flush_on_last_del
 456 .TP
 457 .B no_path_retry
 458 .TP
 459 .B rr_min_io
 460 .TP
 461 .B rr_min_io_q
 462 .TP
 463 .B features
 464 .RE
 465 .PD
 466 .LP
 467 .SH "devices section"
 468 The only recognized attribute for the
 469 .B devices
 470 section is the
 471 .I device
 472 subsection.
 473 .LP
 474 The
 475 .I device
 476 subsection recognizes the following attributes:
 477 .TP 17
 478 .B vendor
 479 (Mandatory) Vendor identifier
 480 .TP
 481 .B product
 482 (Mandatory) Product identifier
 483 .TP
 484 .B revision
 485 (Optional) Revision identfier
 486 .TP
 487 .B product_blacklist
 488 (Optional) Product strings to blacklist for this vendor
 489 .TP
 490 .B alias_prefix
 491 (Optional) The user_friendly_names prefix to use for this
 492 device type, instead of the default "mpath"
 493 .TP
 494 .B hardware_handler
 495 (Optional) The hardware handler to use for this device type.
 496 The following hardware handler are implemented:
 497 .RS
 498 .TP 12
 499 .B 1 emc
 500 Hardware handler for EMC storage arrays.
 501 .TP
 502 .B 1 rdac
 503 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
 504 .TP
 505 .B 1 hp_sw
 506 Hardware handler for Compaq/HP storage arrays in active/standby
 507 mode.
 508 .TP
 509 .B 1 alua
 510 Hardware handler for SCSI-3 ALUA compatible arrays.
 511 .RE
 512 .LP
 513 The following attributes are optional; if not set the default values
 514 are taken from the
 515 .I defaults
 516 section:
 517 .sp 1
 518 .PD .1v
 519 .RS
 520 .TP 18
 521 .B path_grouping_policy
 522 .TP
 523 .B getuid_callout
 524 .TP
 525 .B path_selector
 526 .TP
 527 .B path_checker
 528 .TP
 529 .B prio
 530 .TP
 531 .B prio_args
 532 .TP
 533 .B features
 534 .TP
 535 .B failback
 536 .TP
 537 .B rr_weight
 538 .TP
 539 .B no_path_retry
 540 .TP
 541 .B rr_min_io
 542 .TP
 543 .B rr_min_io_rq
 544 .TP
 545 .B fast_io_fail_tmo
 546 .TP
 547 .B dev_loss_tmo
 548 .TP
 549 .B flush_on_last_del
 550 .RE
 551 .PD
 552 .LP
 553 .SH "KNOWN ISSUES"
 554 The usage of
 555 .B queue_if_no_path
 556 option can lead to
 557 .B D state
 558 processes being hung and not killable in situations where all the paths to the LUN go offline.
 559 It is advisable to use the
 560 .B no_path_retry
 561 option instead.
 562 .P
 563 The use of
 564 .B queue_if_no_path
 565 or
 566 .B no_path_retry
 567 might lead to a deadlock if the
 568 .B dev_loss_tmo
 569 setting results in a device being removed while I/O is still queued.
 570 The multipath daemon will update the
 571 .B dev_loss_tmo
 572 setting accordingly to avoid this deadlock. Hence if both values are
 573 specified the order of precedence is
 574 .I no_path_retry, queue_if_no_path, dev_loss_tmo
 575
 576 .SH "SEE ALSO"
 577 .BR udev (8),
 578 .BR dmsetup (8)
 579 .BR multipath (8)
 580 .BR multipathd (8)
 581 .SH AUTHORS
 582 .B multipath
 583 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.