1 .TH MULTIPATH.CONF 5 "30 November 2006"
3 multipath.conf \- multipath daemon configuration file
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.
11 The configuration file contains entries of the form:
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.
39 The following \fIsection\fP keywords are recognized:
42 This section defines default values for attributes which are used
43 whenever no values are given in the appropriate device or multipath
47 This section defines which devices should be excluded from the
48 multipath topology discovery.
50 .B blacklist_exceptions
51 This section defines which devices should be included in the
52 multipath topology discovery, despite being listed in the
57 This section defines the multipath topologies. They are indexed by a
58 \fIWorld Wide Identifier\fR(wwid), which is the result of the
59 \fIgetuid_callout\fR program.
62 This section defines the device-specific settings.
65 .SH "defaults section"
68 section recognizes the following keywords:
71 interval between two path checks in seconds. For properly functioning paths,
72 the interval between checks will gradually increase to
73 .B max_polling_interval;
77 .B max_polling_interval
78 maximal interval between two path checks in seconds; default is
79 .I 4 * polling_interval
82 directory where udev creates its device nodes; default is
86 default verbosity. Higher values increase the verbosity level. Valid
87 levels are between 0 and 6; default is
91 enable reassigning of device-mapper maps. With this option multipathd
92 will remap existing device-mapper maps to always point to multipath
93 device, not the underlying block devices. Possible values are
94 \fIyes\fR and \fIno\fR. Default is
98 The default path selector algorithm to use; they are offered by the
99 kernel multipath target. There are three selector algorithms.
103 Loop through every path in the path group, sending the same amount of IO to
107 Send the next bunch of IO down the path with the least amount of outstanding IO.
110 Choose the path for the next bunch of IO based on the amount of outstanding IO
111 to the path and its relative throughput.
114 .B path_grouping_policy
115 The default path grouping policy to apply to unspecified
116 multipaths. Possible values are
120 1 path per priority group
123 all paths in 1 priority group
126 1 priority group per serial number
129 1 priority group per priority value. Priorities are determined by
130 callout programs specified as a global, per-controller or
131 per-multipath option in the configuration file.
133 .B group_by_node_name
134 1 priority group per target node name. Target node names are fetched
135 in /sys/class/fc_transport/target*/node_name.
137 Default value is \fImultibus\fR.
141 The default program and args to callout to obtain a unique path
142 identifier. Should be specified with an absolute path. Default value
144 .I /lib/udev/scsi_id --whitelisted --device=/dev/%n
147 The default program and args to callout to obtain a path priority
148 value. The specified program will be executed and should return a
149 numeric value specifying the relative priority of this path. Higher
150 number have a higher priority. A '%n' in the command line will be expanded
151 to the device name, a '%b' will be expanded to the device number in
155 is a valid value. Currently the following path priority programs are
159 .B mpath_prio_emc /dev/%n
160 Generate the path priority for EMC arrays
162 .B mpath_prio_alua /dev/%n
163 Generate the path priority based on the SCSI-3 ALUA settings.
165 .B mpath_prio_ontap /dev/%n
166 Generate the path priority for NetApp arrays.
168 .B mpath_prio_rdac /dev/%n
169 Generate the path priority for LSI/Engenio RDAC controller.
171 .B mpath_prio_hp_sw /dev/%n
172 Generate the path priority for Compaq/HP controller in
175 .B mpath_prio_hds_modular %b
176 Generate the path priority for Hitachi HDS Modular storage arrays.
178 Default value is \fBnone\fR.
182 Specify any device-mapper features to be used. Syntax is
186 is the number of features in
188 Possible values for the feature list are
192 Queue IO if no path is active; identical to the
197 Disable automatic partitions generation via kpartx.
201 The default method used to determine the paths' state. Possible values
206 Read the first sector of the device
211 command to the device.
214 Query the EMC Clariion specific EVPD page 0xC0 to determine the path
218 Check the path state for HP storage arrays with Active/Standby firmware.
221 Check the path state for LSI/Engenio RDAC storage controller.
224 Read the first sector with direct I/O.
226 Default value is \fIreadsector0\fR.
230 Tell the daemon to manage path group failback, or not to. 0 or
232 means immediate failback, values >0 means deferred failback (in
235 means no failback. Default value is
239 The number of IO to route to a path before switching to the next in
240 the same path group. Default is
244 If set to \fIpriorities\fR the multipath configurator will assign
245 path weights as "path prio * rr_min_io". Possible values are
253 Specify the number of retries until disable queueing, or
255 for immediate failure (no queueing),
257 for never stop queueing. Default is 0.
259 .B user_friendly_names
262 , using the bindings file
263 .I /etc/multipath/bindings
264 to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
267 use the WWID as the alias. In either case this be will
268 be overriden by any specific aliases in the \fImultipaths\fR section.
273 Specify the maximum number of file descriptors that can be opened by multipath
274 and multipathd. This is equivalent to ulimit -n. A value of \fImax\fR will set
275 this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
276 maximum number of open fds is taken from the calling process. It is usually
277 1024. To be safe, this should be set to the maximum number of paths plus 32,
278 if that number is greated than 1024.
281 Specify the timeout to user for path checkers that issue scsi commands with an
282 explict timeout, in seconds; default taken from
283 .I /sys/block/sd<x>/device/timeout
286 Specify the number of seconds the scsi layer will wait after a problem has been
287 detected on a FC remote port before failing IO to devices on that remote port.
288 This should be smaller than dev_loss_tmo. Setting this to
290 will disable the timeout.
293 Specify the number of seconds the scsi layer will wait after a problem has
294 been detected on a FC remote port before removing it from the system.
296 .B queue_without_daemon
299 , when multipathd stops, queueing will be turned off for all devices.
300 This is useful for devices that set no_path_retry. If a machine is
301 shut down while all paths to a device are down, it is possible to hang waiting
302 for IO to return from the device after multipathd has been stopped. Without
303 multipathd running, access to the paths cannot be restored, and the kernel
304 cannot be told to stop queueing IO. Setting queue_without_daemon to
306 , avoids this problem. Default is
310 The full pathname of the binding file to be used when the user_friendly_names option is set. Defaults to
311 .I /var/lib/multipath/bindings
313 .SH "blacklist section"
316 section is used to exclude specific device from inclusion in the
317 multipath topology. It is most commonly used to exclude local disks or
318 LUNs for the array controller.
320 The following keywords are recognized:
323 The \fIWorld Wide Identification\fR of a device.
326 Regular expression of the device nodes to be excluded.
329 Subsection for the device description. This subsection recognizes the
333 keywords. For a full description of these keywords please see the
336 .SH "blacklist_exceptions section"
338 .I blacklist_exceptions
339 section is used to revert the actions of the
341 section, ie to include specific device in the
342 multipath topology. This allows to selectively include devices which
343 would normally be excluded via the
347 The following keywords are recognized:
350 The \fIWorld Wide Identification\fR of a device.
353 Regular expression of the device nodes to be excluded.
356 Subsection for the device description. This subsection recognizes the
360 keywords. For a full description of these keywords please see the
363 .SH "multipaths section"
364 The only recognized attribute for the
372 subsection recognizes the following attributes:
375 Index of the container. Mandatory for this subsection.
378 (Optional) symbolic name for the multipath map.
380 The following attributes are optional; if not set the default values
390 .B path_grouping_policy
404 .SH "devices section"
405 The only recognized attribute for the
413 subsection recognizes the following attributes:
416 (Mandatory) Vendor identifier
419 (Mandatory) Product identifier
422 (Optional) Revision identfier
425 (Optional) Product strings to blacklist for this vendor
428 (Optional) The hardware handler to use for this device type.
429 The following hardware handler are implemented:
433 Hardware handler for EMC storage arrays.
436 The following attributes are optional; if not set the default values
444 .B path_grouping_policy
475 processes being hung and not killable in situations where all the paths to the LUN go offline.
476 It is advisable to use the
486 was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.