path: root/multipath/multipath.conf.5

.TH MULTIPATH.CONF 5 "30 November 2006"
.SH NAME
multipath.conf \- multipath daemon configuration file
.SH DESCRIPTION
.B "multipath.conf"
is the configuration file for the multipath daemon. It is used to
overwrite the built-in configuration table of \fBmultipathd\fP.
Any line whose first non-white-space character is a '#' is considered
a comment line. Empty lines are ignored.
.SH SYNTAX
The configuration file contains entries of the form:
.RS
.nf
.ft B
.sp
<section> {
.RS
.ft B
<attribute> <value>
.I "..."
.ft B
<subsection> {
.RS
.ft B
<attribute> <value>
.I "..."
.RE
}
.RE
}
.ft R
.fi
.RE
.LP
Each \fIsection\fP contains one or more attributes or subsections. The
recognized keywords for attributes or subsections depend on the
section in which they occor.
.LP
The following \fIsection\fP keywords are recognized:
.TP 17
.B defaults
This section defines default values for attributes which are used
whenever no specific setting is given.
.TP
.B blacklist
This section defines which devices should be excluded from the
multipath topology discovery.
.TP
.B blacklist_exceptions
This section defines which devices should be included in the
multipath topology discovery, despite being listed in the
.I blacklist
section.
.TP
.B multipaths
This section defines the multipath topologies. They are indexed by a
\fIWorld Wide Identifier\fR(wwid), which is the result of the
\fIgetuid_callout\fR program.
.TP
.B devices
This section defines the device-specific settings.
.RE
.LP
.SH "defaults section"
The
.B defaults
section recognizes the following keywords:
.TP 17
.B polling_interval
interval between two path checks in seconds For properly functioning paths,
the interval between checks will gradually increase to (4 * polling_interval);
default is
.I 5
.TP
.B udev_dir
directory where udev creates its device nodes; default is
.I /dev
.TP
.B verbosity
default verbosity. Higher values increase the verbosity level. Valid
levels are between 0 and 6; default is
.I 2
.TP
.B selector
The default path selector algorithm to use; they are offered by the
kernel multipath target. The only currently implemented is
.I "round-robin 0"
.TP
.B path_grouping_policy
The default path grouping policy to apply to unspecified
multipaths. Possible values are
.RS
.TP 12
.B failover
1 path per priority group
.TP
.B multibus
all paths in 1 priority group
.TP
.B group_by_serial
1 priority group per serial number
.TP
.B group_by_prio
1 priority group per priority value. Priorities are determined by
callout programs specified as a global, per-controller or
per-multipath option in the configuration file.
.TP
.B group_by_node_name
1 priority group per target node name. Target node names are fetched
in /sys/class/fc_transport/target*/node_name.
.TP
Default value is \fImultibus\fR.
.RE
.TP
.B getuid_callout
The default program and args to callout to obtain a unique path
identifier. Should be specified with an absolute path. Default value
is
.I /lib/udev/scsi_id --whitelisted --device=/dev/%n
.TP
.B prio_callout
The default program and args to callout to obtain a path priority
value. The specified program will be executed and should return a
numeric value specifying the relative priority of this path. Higher
number have a higher priority. A '%n' in the command line will be expanded
to the device name, a '%b' will be expanded to the device number in
.I major:minor
format.
.I "none"
is a valid value. Currently the following path priority programs are
implemented:
.RS
.TP 12
.B mpath_prio_emc /dev/%n
Generate the path priority for EMC arrays
.TP
.B mpath_prio_alua /dev/%n
Generate the path priority based on the SCSI-3 ALUA settings.
.TP
.B mpath_prio_netapp /dev/%n
Generate the path priority for NetApp arrays.
.TP
.B mpath_prio_rdac /dev/%n
Generate the path priority for LSI/Engenio RDAC controller.
.TP
.B mpath_prio_hp_sw /dev/%n
Generate the path priority for Compaq/HP controller in
active/standby mode.
.TP
.B mpath_prio_hds_modular %b
Generate the path priority for Hitachi HDS Modular storage arrays.
.TP
Default value is \fBnone\fR.
.RE
.TP
.B features
Specify any device-mapper features to be used. The most common of
these features is
.I "1 queue_if_no_path" 
Note that this can also be set via the
.I no_path_retry
keyword.
.TP
.B path_checker
The default method used to determine the paths' state. Possible values
are
.RS
.TP 12
.B readsector0
Read the first sector of the device
.TP
.B tur
Issue a
.I TEST UNIT READY
command to the device.
.TP
.B emc_clariion
Query the EMC Clariion specific EVPD page 0xC0 to determine the path
state.
.TP
.B hp_sw
Check the path state for HP storage arrays with Active/Standby firmware.
.TP
.B rdac
Check the path state for LSI/Engenio RDAC storage controller.
.TP
.B directio
Read the first sector with direct I/O.
.TP
Default value is \fIreadsector0\fR.
.RE
.TP
.B failback
Tell the daemon to manage path group failback, or not to. 0 or
.I immediate
means immediate failback, values >0 means deferred failback (in
seconds).
.I manual
means no failback. Default value is
.I manual
.TP
.B  rr_min_io
The number of IO to route to a path before switching to the next in
the same path group. Default is
.I 1000
.TP
.B rr_weight
If set to \fIpriorities\fR the multipath configurator will assign
path weights as "path prio * rr_min_io". Possible values are
.I priorities
or
.IR uniform .
Default is
.IR uniform .
.TP
.B no_path_retry
Specify the number of retries until disable queueing, or
.I fail
for immediate failure (no queueing),
.I queue
for never stop queueing. Default is 0.
.TP
.B user_friendly_names
If set to 
.I yes
, using the bindings file
.I /etc/multipath/bindings
to assign a persistent and unique alias to the multipath, in the form of mpath<n>.
If set to 
.I no
use the WWID as the alias. In either case this be will
be overriden by any specific aliases in the \fImultipaths\fR section.
Default is
.I no
.TP
.B max_fds
Specify the maximum number of file descriptors that can be opened by multipath
and multipathd.  This is equivalent to ulimit -n. A value of \fImax\fR will set
this to the system limit from /proc/sys/fs/nr_open. If this is not set, the
maximum number of open fds is taken from the calling process. It is usually
1024. To be safe, this should be set to the maximum number of paths plus 32,
if that number is greated than 1024.
.TP
.B fast_io_fail_tmo
Specify the number of seconds the scsi layer will wait after a problem has been
detected on a FC remote port before failing IO to devices on that remote port.
This should be smaller than dev_loss_tmo. Setting this to
.I off
will disable the timeout.
.TP
.B dev_loss_tmo
Specify the number of seconds the scsi layer will wait after a problem has
been detected on a FC remote port before removing it from the system.
.TP
.B queue_without_daemon
If set to
.I no
, when multipathd stops, queueing will be turned off for all devices.
This is useful for devices that set no_path_retry.  If a machine is
shut down while all paths to a device are down, it is possible to hang waiting
for IO to return from the device after multipathd has been stopped. Without
multipathd running, access to the paths cannot be restored, and the kernel
cannot be told to stop queueing IO. Setting queue_without_daemon to
.I no
, avoids this problem. Default is
.I yes
.
.SH "blacklist section"
The
.I blacklist
section is used to exclude specific device from inclusion in the
multipath topology. It is most commonly used to exclude local disks or
LUNs for the array controller.
.LP
The following keywords are recognized:
.TP 17
.B wwid
The \fIWorld Wide Identification\fR of a device.
.TP
.B devnode
Regular expression of the device nodes to be excluded.
.TP
.B device
Subsection for the device description. This subsection recognizes the
.I vendor
and
.I product
keywords. For a full description of these keywords please see the
.I devices
section description.
.SH "blacklist_exceptions section"
The
.I blacklist_exceptions
section is used to revert the actions of the
.I blacklist
section, ie to include specific device in the
multipath topology. This allows to selectively include devices which
would normally be excluded via the
.I blacklist
section.
.LP
The following keywords are recognized:
.TP 17
.B wwid
The \fIWorld Wide Identification\fR of a device.
.TP
.B devnode
Regular expression of the device nodes to be excluded.
.TP
.B device
Subsection for the device description. This subsection recognizes the
.I vendor
and
.I product
keywords. For a full description of these keywords please see the
.I devices
section description.
.SH "multipaths section"
The only recognized attribute for the
.B multipaths
section is the
.I multipath
subsection.
.LP
The
.B multipath
subsection recognizes the following attributes:
.TP 17
.B wwid
Index of the container. Mandatory for this subsection.
.TP
.B alias
(Optional) symbolic name for the multipath map.
.LP
The following attributes are optional; if not set the default values
are taken from the
.I defaults
section:
.sp 1
.PD .1v
.RS
.TP 18
.B path_grouping_policy
.TP
.B path_selector
.TP
.B failback
.TP
.B no_path_retry
.TP
.B rr_min_io
.RE
.PD
.LP
.SH "devices section"
The only recognized attribute for the
.B devices
section is the
.I device
subsection.
.LP
The
.I device
subsection recognizes the following attributes:
.TP 17
.B vendor
(Mandatory) Vendor identifier
.TP
.B product
(Mandatory) Product identifier
.TP
.B product_blacklist
Product strings to blacklist for this vendor
.TP
.B hardware_handler
(Optional) The hardware handler to use for this device type.
The following hardware handler are implemented:
.RS
.TP 12
.B 1 emc
Hardware handler for EMC storage arrays.
.RE
.LP
The following attributes are optional; if not set the default values
are taken from the
.I defaults
section:
.sp 1
.PD .1v
.RS
.TP 18
.B path_grouping_policy
.TP
.B getuid_callout
.TP
.B path_selector
.TP
.B path_checker
.TP
.B features
.TP
.B prio_callout
.TP
.B failback
.TP
.B rr_weight
.TP
.B no_path_retry
.TP
.B rr_min_io
.TP
.B fast_io_fail_tmo
.TP
.B dev_loss_tmo
.RE
.PD
.LP
.SH "KNOWN ISSUES"
The usage of
.B queue_if_no_path
option can lead to
.B D state
processes being hung and not killable in situations where all the paths to the LUN go offline.
It is advisable to use the
.B no_path_retry
option instead.
.SH "SEE ALSO"
.BR udev (8),
.BR dmsetup (8)
.BR multipath (8)
.BR multipathd (8)
.SH AUTHORS
.B multipath
was developed by Christophe Varoqui, <christophe.varoqui@opensvc.com> and others.