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 fast_io_fail_tmo
 246 Specify the number of seconds the scsi layer will wait after a problem has been
 247 detected on a FC remote port before failing IO to devices on that remote port.
 248 This should be smaller than dev_loss_tmo. Setting this to
 249 .I off
 250 will disable the timeout.
 251 .TP
 252 .B dev_loss_tmo
 253 Specify the number of seconds the scsi layer will wait after a problem has
 254 been detected on a FC remote port before removing it from the system.
 255 .TP
 256 .B queue_without_daemon
 257 If set to
 258 .I no
 259 , when multipathd stops, queueing will be turned off for all devices.
 260 This is useful for devices that set no_path_retry.  If a machine is
 261 shut down while all paths to a device are down, it is possible to hang waiting
 262 for IO to return from the device after multipathd has been stopped. Without
 263 multipathd running, access to the paths cannot be restored, and the kernel
 264 cannot be told to stop queueing IO. Setting queue_without_daemon to
 265 .I no
 266 , avoids this problem. Default is
 267 .I yes
 268 .
 269 .SH "blacklist section"
 270 The
 271 .I blacklist
 272 section is used to exclude specific device from inclusion in the
 273 multipath topology. It is most commonly used to exclude local disks or
 274 LUNs for the array controller.
 275 .LP
 276 The following keywords are recognized:
 277 .TP 17
 278 .B wwid
 279 The \fIWorld Wide Identification\fR of a device.
 280 .TP
 281 .B devnode
 282 Regular expression of the device nodes to be excluded.
 283 .TP
 284 .B device
 285 Subsection for the device description. This subsection recognizes the
 286 .I vendor
 287 and
 288 .I product
 289 keywords. For a full description of these keywords please see the
 290 .I devices
 291 section description.
 292 .SH "blacklist_exceptions section"
 293 The
 294 .I blacklist_exceptions
 295 section is used to revert the actions of the
 296 .I blacklist
 297 section, ie to include specific device in the
 298 multipath topology. This allows to selectively include devices which
 299 would normally be excluded via the
 300 .I blacklist
 301 section.
 302 .LP
 303 The following keywords are recognized:
 304 .TP 17
 305 .B wwid
 306 The \fIWorld Wide Identification\fR of a device.
 307 .TP
 308 .B devnode
 309 Regular expression of the device nodes to be excluded.
 310 .TP
 311 .B device
 312 Subsection for the device description. This subsection recognizes the
 313 .I vendor
 314 and
 315 .I product
 316 keywords. For a full description of these keywords please see the
 317 .I devices
 318 section description.
 319 .SH "multipaths section"
 320 The only recognized attribute for the
 321 .B multipaths
 322 section is the
 323 .I multipath
 324 subsection.
 325 .LP
 326 The
 327 .B multipath
 328 subsection recognizes the following attributes:
 329 .TP 17
 330 .B wwid
 331 Index of the container. Mandatory for this subsection.
 332 .TP
 333 .B alias
 334 (Optional) symbolic name for the multipath map.
 335 .LP
 336 The following attributes are optional; if not set the default values
 337 are taken from the
 338 .I defaults
 339 section:
 340 .sp 1
 341 .PD .1v
 342 .RS
 343 .TP 18
 344 .B path_grouping_policy
 345 .TP
 346 .B path_selector
 347 .TP
 348 .B failback
 349 .TP
 350 .B no_path_retry
 351 .TP
 352 .B rr_min_io
 353 .RE
 354 .PD
 355 .LP
 356 .SH "devices section"
 357 The only recognized attribute for the
 358 .B devices
 359 section is the
 360 .I device
 361 subsection.
 362 .LP
 363 The
 364 .I device
 365 subsection recognizes the following attributes:
 366 .TP 17
 367 .B vendor
 368 (Mandatory) Vendor identifier
 369 .TP
 370 .B product
 371 (Mandatory) Product identifier
 372 .TP
 373 .B product_blacklist
 374 Product strings to blacklist for this vendor
 375 .TP
 376 .B hardware_handler
 377 (Optional) The hardware handler to use for this device type.
 378 The following hardware handler are implemented:
 379 .RS
 380 .TP 12
 381 .B 1 emc
 382 Hardware handler for EMC storage arrays.
 383 .RE
 384 .LP
 385 The following attributes are optional; if not set the default values
 386 are taken from the
 387 .I defaults
 388 section:
 389 .sp 1
 390 .PD .1v
 391 .RS
 392 .TP 18
 393 .B path_grouping_policy
 394 .TP
 395 .B getuid_callout
 396 .TP
 397 .B path_selector
 398 .TP
 399 .B path_checker
 400 .TP
 401 .B features
 402 .TP
 403 .B prio_callout
 404 .TP
 405 .B failback
 406 .TP
 407 .B rr_weight
 408 .TP
 409 .B no_path_retry
 410 .TP
 411 .B rr_min_io
 412 .TP
 413 .B fast_io_fail_tmo
 414 .TP
 415 .B dev_loss_tmo
 416 .RE
 417 .PD
 418 .LP
 419 .SH "KNOWN ISSUES"
 420 The usage of
 421 .B queue_if_no_path
 422 option can lead to
 423 .B D state
 424 processes being hung and not killable in situations where all the paths to the LUN go offline.
 425 It is advisable to use the
 426 .B no_path_retry
 427 option instead.
 428 .SH "SEE ALSO"
 429 .BR udev (8),
 430 .BR dmsetup (8)
 431 .BR multipath (8)
 432 .BR multipathd (8)
 433 .SH AUTHORS
 434 .B multipath
 435 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.