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 verbosity
  86 default verbosity. Higher values increase the verbosity level. Valid
  87 levels are between 0 and 6; default is
  88 .I 2
  89 .TP
  90 .B path_selector
  91 The default path selector algorithm to use; they are offered by the
  92 kernel multipath target. There are three selector algorithms.
  93 .RS
  94 .TP 12
  95 .B "round-robin 0"
  96 Loop through every path in the path group, sending the same amount of IO to
  97 each.
  98 .TP
  99 .B "queue-length 0"
 100 Send the next bunch of IO down the path with the least amount of outstanding IO.
 101 .TP
 102 .B "service-time 0"
 103 Choose the path for the next bunch of IO based on the amount of outstanding IO
 104 to the path and its relative throughput.
 105 .RE
 106 .TP
 107 .B path_grouping_policy
 108 The default path grouping policy to apply to unspecified
 109 multipaths. Possible values are
 110 .RS
 111 .TP 12
 112 .B failover
 113 1 path per priority group
 114 .TP
 115 .B multibus
 116 all paths in 1 priority group
 117 .TP
 118 .B group_by_serial
 119 1 priority group per serial number
 120 .TP
 121 .B group_by_prio
 122 1 priority group per priority value. Priorities are determined by
 123 callout programs specified as a global, per-controller or
 124 per-multipath option in the configuration file.
 125 .TP
 126 .B group_by_node_name
 127 1 priority group per target node name. Target node names are fetched
 128 in /sys/class/fc_transport/target*/node_name.
 129 .TP
 130 Default value is \fImultibus\fR.
 131 .RE
 132 .TP
 133 .B getuid_callout
 134 The default program and args to callout to obtain a unique path
 135 identifier. Should be specified with an absolute path. Default value
 136 is
 137 .I /lib/udev/scsi_id --whitelisted --device=/dev/%n
 138 .TP
 139 .B prio_callout
 140 The default program and args to callout to obtain a path priority
 141 value. The specified program will be executed and should return a
 142 numeric value specifying the relative priority of this path. Higher
 143 number have a higher priority. A '%n' in the command line will be expanded
 144 to the device name, a '%b' will be expanded to the device number in
 145 .I major:minor
 146 format.
 147 .I "none"
 148 is a valid value. Currently the following path priority programs are
 149 implemented:
 150 .RS
 151 .TP 12
 152 .B mpath_prio_emc /dev/%n
 153 Generate the path priority for EMC arrays
 154 .TP
 155 .B mpath_prio_alua /dev/%n
 156 Generate the path priority based on the SCSI-3 ALUA settings.
 157 .TP
 158 .B mpath_prio_ontap /dev/%n
 159 Generate the path priority for NetApp arrays.
 160 .TP
 161 .B mpath_prio_rdac /dev/%n
 162 Generate the path priority for LSI/Engenio RDAC controller.
 163 .TP
 164 .B mpath_prio_hp_sw /dev/%n
 165 Generate the path priority for Compaq/HP controller in
 166 active/standby mode.
 167 .TP
 168 .B mpath_prio_hds_modular %b
 169 Generate the path priority for Hitachi HDS Modular storage arrays.
 170 .TP
 171 Default value is \fBnone\fR.
 172 .RE
 173 .TP
 174 .B features
 175 Specify any device-mapper features to be used. Syntax is
 176 .I num list
 177 where
 178 .I num
 179 is the number of features in
 180 .I list.
 181 Possible values for the feature list are
 182 .RS
 183 .TP 12
 184 .B queue_if_no_path
 185 Queue IO if no path is active; identical to the
 186 .I no_path_retry
 187 keyword.
 188 .TP
 189 .B no_partitions
 190 Disable automatic partitions generation via kpartx.
 191 .RE
 192 .TP
 193 .B path_checker
 194 The default method used to determine the paths' state. Possible values
 195 are
 196 .RS
 197 .TP 12
 198 .B readsector0
 199 Read the first sector of the device
 200 .TP
 201 .B tur
 202 Issue a
 203 .I TEST UNIT READY
 204 command to the device.
 205 .TP
 206 .B emc_clariion
 207 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
 208 state.
 209 .TP
 210 .B hp_sw
 211 Check the path state for HP storage arrays with Active/Standby firmware.
 212 .TP
 213 .B rdac
 214 Check the path state for LSI/Engenio RDAC storage controller.
 215 .TP
 216 .B directio
 217 Read the first sector with direct I/O.
 218 .TP
 219 Default value is \fIreadsector0\fR.
 220 .RE
 221 .TP
 222 .B failback
 223 Tell the daemon to manage path group failback, or not to. 0 or
 224 .I immediate
 225 means immediate failback, values >0 means deferred failback (in
 226 seconds).
 227 .I manual
 228 means no failback. Default value is
 229 .I manual
 230 .TP
 231 .B  rr_min_io
 232 The number of IO to route to a path before switching to the next in
 233 the same path group. Default is
 234 .I 1000
 235 .TP
 236 .B rr_weight
 237 If set to \fIpriorities\fR the multipath configurator will assign
 238 path weights as "path prio * rr_min_io". Possible values are
 239 .I priorities
 240 or
 241 .IR uniform .
 242 Default is
 243 .IR uniform .
 244 .TP
 245 .B no_path_retry
 246 Specify the number of retries until disable queueing, or
 247 .I fail
 248 for immediate failure (no queueing),
 249 .I queue
 250 for never stop queueing. Default is 0.
 251 .TP
 252 .B user_friendly_names
 253 If set to
 254 .I yes
 255 , using the bindings file
 256 .I /etc/multipath/bindings
 257 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
 258 If set to
 259 .I no
 260 use the WWID as the alias. In either case this be will
 261 be overriden by any specific aliases in the \fImultipaths\fR section.
 262 Default is
 263 .I no
 264 .TP
 265 .B max_fds
 266 Specify the maximum number of file descriptors that can be opened by multipath
 267 and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
 268 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
 269 maximum number of open fds is taken from the calling process. It is usually
 270 1024. To be safe, this should be set to the maximum number of paths plus 32,
 271 if that number is greated than 1024.
 272 .TP
 273 .B checker_timeout
 274 Specify the timeout to user for path checkers that issue scsi commands with an
 275 explict timeout, in seconds; default taken from
 276 .I /sys/block/sd<x>/device/timeout
 277 .TP
 278 .B fast_io_fail_tmo
 279 Specify the number of seconds the scsi layer will wait after a problem has been
 280 detected on a FC remote port before failing IO to devices on that remote port.
 281 This should be smaller than dev_loss_tmo. Setting this to
 282 .I off
 283 will disable the timeout.
 284 .TP
 285 .B dev_loss_tmo
 286 Specify the number of seconds the scsi layer will wait after a problem has
 287 been detected on a FC remote port before removing it from the system.
 288 .TP
 289 .B queue_without_daemon
 290 If set to
 291 .I no
 292 , when multipathd stops, queueing will be turned off for all devices.
 293 This is useful for devices that set no_path_retry.  If a machine is
 294 shut down while all paths to a device are down, it is possible to hang waiting
 295 for IO to return from the device after multipathd has been stopped. Without
 296 multipathd running, access to the paths cannot be restored, and the kernel
 297 cannot be told to stop queueing IO. Setting queue_without_daemon to
 298 .I no
 299 , avoids this problem. Default is
 300 .I yes
 301 .
 302 .SH "blacklist section"
 303 The
 304 .I blacklist
 305 section is used to exclude specific device from inclusion in the
 306 multipath topology. It is most commonly used to exclude local disks or
 307 LUNs for the array controller.
 308 .LP
 309 The following keywords are recognized:
 310 .TP 17
 311 .B wwid
 312 The \fIWorld Wide Identification\fR of a device.
 313 .TP
 314 .B devnode
 315 Regular expression of the device nodes to be excluded.
 316 .TP
 317 .B device
 318 Subsection for the device description. This subsection recognizes the
 319 .I vendor
 320 and
 321 .I product
 322 keywords. For a full description of these keywords please see the
 323 .I devices
 324 section description.
 325 .SH "blacklist_exceptions section"
 326 The
 327 .I blacklist_exceptions
 328 section is used to revert the actions of the
 329 .I blacklist
 330 section, ie to include specific device in the
 331 multipath topology. This allows to selectively include devices which
 332 would normally be excluded via the
 333 .I blacklist
 334 section.
 335 .LP
 336 The following keywords are recognized:
 337 .TP 17
 338 .B wwid
 339 The \fIWorld Wide Identification\fR of a device.
 340 .TP
 341 .B devnode
 342 Regular expression of the device nodes to be excluded.
 343 .TP
 344 .B device
 345 Subsection for the device description. This subsection recognizes the
 346 .I vendor
 347 and
 348 .I product
 349 keywords. For a full description of these keywords please see the
 350 .I devices
 351 section description.
 352 .SH "multipaths section"
 353 The only recognized attribute for the
 354 .B multipaths
 355 section is the
 356 .I multipath
 357 subsection.
 358 .LP
 359 The
 360 .B multipath
 361 subsection recognizes the following attributes:
 362 .TP 17
 363 .B wwid
 364 Index of the container. Mandatory for this subsection.
 365 .TP
 366 .B alias
 367 (Optional) symbolic name for the multipath map.
 368 .LP
 369 The following attributes are optional; if not set the default values
 370 are taken from the
 371 .I defaults
 372 or
 373 .I devices
 374 section:
 375 .sp 1
 376 .PD .1v
 377 .RS
 378 .TP 18
 379 .B path_grouping_policy
 380 .TP
 381 .B path_selector
 382 .TP
 383 .B failback
 384 .TP
 385 .B no_path_retry
 386 .TP
 387 .B rr_min_io
 388 .TP
 389 .B features
 390 .RE
 391 .PD
 392 .LP
 393 .SH "devices section"
 394 The only recognized attribute for the
 395 .B devices
 396 section is the
 397 .I device
 398 subsection.
 399 .LP
 400 The
 401 .I device
 402 subsection recognizes the following attributes:
 403 .TP 17
 404 .B vendor
 405 (Mandatory) Vendor identifier
 406 .TP
 407 .B product
 408 (Mandatory) Product identifier
 409 .TP
 410 .B revision
 411 (Optional) Revision identfier
 412 .TP
 413 .B product_blacklist
 414 (Optional) Product strings to blacklist for this vendor
 415 .TP
 416 .B hardware_handler
 417 (Optional) The hardware handler to use for this device type.
 418 The following hardware handler are implemented:
 419 .RS
 420 .TP 12
 421 .B 1 emc
 422 Hardware handler for EMC storage arrays.
 423 .RE
 424 .LP
 425 The following attributes are optional; if not set the default values
 426 are taken from the
 427 .I defaults
 428 section:
 429 .sp 1
 430 .PD .1v
 431 .RS
 432 .TP 18
 433 .B path_grouping_policy
 434 .TP
 435 .B getuid_callout
 436 .TP
 437 .B path_selector
 438 .TP
 439 .B path_checker
 440 .TP
 441 .B features
 442 .TP
 443 .B prio_callout
 444 .TP
 445 .B failback
 446 .TP
 447 .B rr_weight
 448 .TP
 449 .B no_path_retry
 450 .TP
 451 .B rr_min_io
 452 .TP
 453 .B fast_io_fail_tmo
 454 .TP
 455 .B dev_loss_tmo
 456 .RE
 457 .PD
 458 .LP
 459 .SH "KNOWN ISSUES"
 460 The usage of
 461 .B queue_if_no_path
 462 option can lead to
 463 .B D state
 464 processes being hung and not killable in situations where all the paths to the LUN go offline.
 465 It is advisable to use the
 466 .B no_path_retry
 467 option instead.
 468 .SH "SEE ALSO"
 469 .BR udev (8),
 470 .BR dmsetup (8)
 471 .BR multipath (8)
 472 .BR multipathd (8)
 473 .SH AUTHORS
 474 .B multipath
 475 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.