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