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