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