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