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