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