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.
 337 .TP
 338 .B queue_without_daemon
 339 If set to
 340 .I no
 341 , when multipathd stops, queueing will be turned off for all devices.
 342 This is useful for devices that set no_path_retry.  If a machine is
 343 shut down while all paths to a device are down, it is possible to hang waiting
 344 for IO to return from the device after multipathd has been stopped. Without
 345 multipathd running, access to the paths cannot be restored, and the kernel
 346 cannot be told to stop queueing IO. Setting queue_without_daemon to
 347 .I no
 348 , avoids this problem. Default is
 349 .I yes
 350 .TP
 351 .B bindings_file
 352 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
 353 .I /var/lib/multipath/bindings
 354 .TP
 355 .B log_checker_err
 356 If set to
 357 .I once
 358 , multipathd logs the first path checker error at logging level 2. Any later
 359 errors are logged at level 3 until the device is restored. If set to
 360 .I always
 361 , multipathd always logs the path checker error at logging level 2. Default is
 362 .I always
 363 .
 364 .SH "blacklist section"
 365 The
 366 .I blacklist
 367 section is used to exclude specific device from inclusion in the
 368 multipath topology. It is most commonly used to exclude local disks or
 369 LUNs for the array controller.
 370 .LP
 371 The following keywords are recognized:
 372 .TP 17
 373 .B wwid
 374 The \fIWorld Wide Identification\fR of a device.
 375 .TP
 376 .B devnode
 377 Regular expression of the device nodes to be excluded.
 378 .TP
 379 .B device
 380 Subsection for the device description. This subsection recognizes the
 381 .I vendor
 382 and
 383 .I product
 384 keywords. For a full description of these keywords please see the
 385 .I devices
 386 section description.
 387 .SH "blacklist_exceptions section"
 388 The
 389 .I blacklist_exceptions
 390 section is used to revert the actions of the
 391 .I blacklist
 392 section, ie to include specific device in the
 393 multipath topology. This allows to selectively include devices which
 394 would normally be excluded via the
 395 .I blacklist
 396 section.
 397 .LP
 398 The following keywords are recognized:
 399 .TP 17
 400 .B wwid
 401 The \fIWorld Wide Identification\fR of a device.
 402 .TP
 403 .B devnode
 404 Regular expression of the device nodes to be excluded.
 405 .TP
 406 .B device
 407 Subsection for the device description. This subsection recognizes the
 408 .I vendor
 409 and
 410 .I product
 411 keywords. For a full description of these keywords please see the
 412 .I devices
 413 section description.
 414 .SH "multipaths section"
 415 The only recognized attribute for the
 416 .B multipaths
 417 section is the
 418 .I multipath
 419 subsection.
 420 .LP
 421 The
 422 .B multipath
 423 subsection recognizes the following attributes:
 424 .TP 17
 425 .B wwid
 426 Index of the container. Mandatory for this subsection.
 427 .TP
 428 .B alias
 429 (Optional) symbolic name for the multipath map.
 430 .LP
 431 The following attributes are optional; if not set the default values
 432 are taken from the
 433 .I defaults
 434 or
 435 .I devices
 436 section:
 437 .sp 1
 438 .PD .1v
 439 .RS
 440 .TP 18
 441 .B path_grouping_policy
 442 .TP
 443 .B path_selector
 444 .TP
 445 .B prio
 446 .TP
 447 .B prio_args
 448 .TP
 449 .B failback
 450 .TP
 451 .B rr_weight
 452 .TP
 453 .B flush_on_last_del
 454 .TP
 455 .B no_path_retry
 456 .TP
 457 .B rr_min_io
 458 .TP
 459 .B rr_min_io_q
 460 .TP
 461 .B features
 462 .RE
 463 .PD
 464 .LP
 465 .SH "devices section"
 466 The only recognized attribute for the
 467 .B devices
 468 section is the
 469 .I device
 470 subsection.
 471 .LP
 472 The
 473 .I device
 474 subsection recognizes the following attributes:
 475 .TP 17
 476 .B vendor
 477 (Mandatory) Vendor identifier
 478 .TP
 479 .B product
 480 (Mandatory) Product identifier
 481 .TP
 482 .B revision
 483 (Optional) Revision identfier
 484 .TP
 485 .B product_blacklist
 486 (Optional) Product strings to blacklist for this vendor
 487 .TP
 488 .B alias_prefix
 489 (Optional) The user_friendly_names prefix to use for this
 490 device type, instead of the default "mpath"
 491 .TP
 492 .B hardware_handler
 493 (Optional) The hardware handler to use for this device type.
 494 The following hardware handler are implemented:
 495 .RS
 496 .TP 12
 497 .B 1 emc
 498 Hardware handler for EMC storage arrays.
 499 .TP
 500 .B 1 rdac
 501 Hardware handler for LSI/Engenio/NetApp E-Series RDAC storage controller.
 502 .TP
 503 .B 1 hp_sw
 504 Hardware handler for Compaq/HP storage arrays in active/standby
 505 mode.
 506 .TP
 507 .B 1 alua
 508 Hardware handler for SCSI-3 ALUA compatible arrays.
 509 .RE
 510 .LP
 511 The following attributes are optional; if not set the default values
 512 are taken from the
 513 .I defaults
 514 section:
 515 .sp 1
 516 .PD .1v
 517 .RS
 518 .TP 18
 519 .B path_grouping_policy
 520 .TP
 521 .B getuid_callout
 522 .TP
 523 .B path_selector
 524 .TP
 525 .B path_checker
 526 .TP
 527 .B prio
 528 .TP
 529 .B prio_args
 530 .TP
 531 .B features
 532 .TP
 533 .B failback
 534 .TP
 535 .B rr_weight
 536 .TP
 537 .B no_path_retry
 538 .TP
 539 .B rr_min_io
 540 .TP
 541 .B rr_min_io_rq
 542 .TP
 543 .B fast_io_fail_tmo
 544 .TP
 545 .B dev_loss_tmo
 546 .TP
 547 .B flush_on_last_del
 548 .RE
 549 .PD
 550 .LP
 551 .SH "KNOWN ISSUES"
 552 The usage of
 553 .B queue_if_no_path
 554 option can lead to
 555 .B D state
 556 processes being hung and not killable in situations where all the paths to the LUN go offline.
 557 It is advisable to use the
 558 .B no_path_retry
 559 option instead.
 560 .P
 561 The use of
 562 .B queue_if_no_path
 563 or
 564 .B no_path_retry
 565 might lead to a deadlock if the
 566 .B dev_loss_tmo
 567 setting results in a device being removed while I/O is still queued.
 568 The multipath daemon will update the
 569 .B dev_loss_tmo
 570 setting accordingly to avoid this deadlock. Hence if both values are
 571 specified the order of precedence is
 572 .I no_path_retry, queue_if_no_path, dev_loss_tmo
 573
 574 .SH "SEE ALSO"
 575 .BR udev (8),
 576 .BR dmsetup (8)
 577 .BR multipath (8)
 578 .BR multipathd (8)
 579 .SH AUTHORS
 580 .B multipath
 581 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.