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 .I uniform
 213 . Default is
 214 .I 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 /var/lib/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 .
 244 .SH "blacklist section"
 245 The
 246 .I blacklist
 247 section is used to exclude specific device from inclusion in the
 248 multipath topology. It is most commonly used to exclude local disks or
 249 LUNs for the array controller.
 250 .LP
 251 The following keywords are recognized:
 252 .TP 17
 253 .B wwid
 254 The \fIWorld Wide Identification\fR of a device.
 255 .TP
 256 .B devnode
 257 Regular expression of the device nodes to be excluded.
 258 .TP
 259 .B device
 260 Subsection for the device description. This subsection recognizes the
 261 .I vendor
 262 and
 263 .I product
 264 keywords. For a full description of these keywords please see the
 265 .I devices
 266 section description.
 267 .SH "blacklist_exceptions section"
 268 The
 269 .I blacklist_exceptions
 270 section is used to revert the actions of the
 271 .I blacklist
 272 section, ie to include specific device in the
 273 multipath topology. This allows to selectively include devices which
 274 would normally be excluded via the
 275 .I blacklist
 276 section.
 277 .LP
 278 The following keywords are recognized:
 279 .TP 17
 280 .B wwid
 281 The \fIWorld Wide Identification\fR of a device.
 282 .TP
 283 .B devnode
 284 Regular expression of the device nodes to be excluded.
 285 .TP
 286 .B device
 287 Subsection for the device description. This subsection recognizes the
 288 .I vendor
 289 and
 290 .I product
 291 keywords. For a full description of these keywords please see the
 292 .I devices
 293 section description.
 294 .SH "multipaths section"
 295 The only recognized attribute for the
 296 .B multipaths
 297 section is the
 298 .I multipath
 299 subsection.
 300 .LP
 301 The
 302 .B multipath
 303 subsection recognizes the following attributes:
 304 .TP 17
 305 .B wwid
 306 Index of the container. Mandatory for this subsection.
 307 .TP
 308 .B alias
 309 (Optional) symbolic name for the multipath map.
 310 .LP
 311 The following attributes are optional; if not set the default values
 312 are taken from the
 313 .I defaults
 314 section:
 315 .sp 1
 316 .PD .1v
 317 .RS
 318 .TP 18
 319 .B path_grouping_policy
 320 .TP
 321 .B path_selector
 322 .TP
 323 .B failback
 324 .TP
 325 .B no_path_retry
 326 .TP
 327 .B rr_min_io
 328 .RE
 329 .PD
 330 .LP
 331 .SH "devices section"
 332 The only recognized attribute for the
 333 .B devices
 334 section is the
 335 .I device
 336 subsection.
 337 .LP
 338 The
 339 .I device
 340 subsection recognizes the following attributes:
 341 .TP 17
 342 .B vendor
 343 (Mandatory) Vendor identifier
 344 .TP
 345 .B product
 346 (Mandatory) Product identifier
 347 .TP
 348 .B product_blacklist
 349 Product strings to blacklist for this vendor
 350 .TP
 351 .B hardware_handler
 352 (Optional) The hardware handler to use for this device type.
 353 The following hardware handler are implemented:
 354 .RS
 355 .TP 12
 356 .B 1 emc
 357 Hardware handler for EMC storage arrays.
 358 .RE
 359 .LP
 360 The following attributes are optional; if not set the default values
 361 are taken from the
 362 .I defaults
 363 section:
 364 .sp 1
 365 .PD .1v
 366 .RS
 367 .TP 18
 368 .B path_grouping_policy
 369 .TP
 370 .B getuid_callout
 371 .TP
 372 .B path_selector
 373 .TP
 374 .B path_checker
 375 .TP
 376 .B features
 377 .TP
 378 .B prio_callout
 379 .TP
 380 .B failback
 381 .TP
 382 .B rr_weight
 383 .TP
 384 .B no_path_retry
 385 .TP
 386 .B rr_min_io
 387 .RE
 388 .PD
 389 .LP
 390 .SH "KNOWN ISSUES"
 391 The usage of
 392 .B queue_if_no_path
 393 option can lead to
 394 .B D state
 395 processes being hung and not killable in situations where all the paths to the LUN go offline.
 396 It is advisable to use the
 397 .B no_path_retry
 398 option instead.
 399 .SH "SEE ALSO"
 400 .BR udev (8),
 401 .BR dmsetup (8)
 402 .BR multipath (8)
 403 .BR multipathd (8)
 404 .SH AUTHORS
 405 .B multipath
 406 was developed by Christophe Varoqui, <christophe.varoqui@free.fr> and others.