.\" ----------------------------------------------------------------------------
.\" Make sure there are no errors with:
.\" groff -z -wall -b -e -t multipath/multipath.8
.\" man --warnings -E UTF-8 -l -Tutf8 -Z multipath/multipath.8 > /dev/null
.\"
.\" Update the date below if you make any significant change.
.\" ----------------------------------------------------------------------------
.
.TH MULTIPATH 8 2023-09-08 Linux
.
.
.\" ----------------------------------------------------------------------------
.SH NAME
.\" ----------------------------------------------------------------------------
.
multipath \- Device mapper target autoconfig.
.
.
.\" ----------------------------------------------------------------------------
.SH SYNOPSIS
.\" ----------------------------------------------------------------------------
.
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-B | \-d | \-i | \-q | \-r \|]
.RB [\| \-b\ \c
.IR file \|]
.RB [\| \-p\ \c
.IR policy \|]
.RB [\| device \|]
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-R\ \c
.IR retries \|]
.B \-f device
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-R\ \c
.IR retries \|]
.B \-F
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-l | \-ll \|]
.RB [\| device \|]
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-a | \-w \|]
.B device
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.B -W
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-i \|]
.RB [\| \-c | \-C \|]
.B device
.
.LP
.B multipath
.RB [\| \-v\ \c
.IR level \|]
.RB [\| \-i \|]
.RB [\| \-u | \-U \|]
.
.LP
.B multipath
.RB [\| \-h | \-t | \-T \|]
.
.\" ----------------------------------------------------------------------------
.SH DESCRIPTION
.\" ----------------------------------------------------------------------------
.
.B multipath
is used to detect and coalesce multiple paths to devices, for fail-over or performance reasons.
.
.\" ----------------------------------------------------------------------------
.SH ARGUMENTS
.\" ----------------------------------------------------------------------------
.
The \fBdevice\fR argument restricts \fBmultipath\fR's operation to devices matching the given
expression. The argument may refer either to a multipath map or to
its components ("paths"). The expression may be in one of the following formats:
.
.TP 1.4i
.B device node
file name of a device node, e.g. \fI/dev/dm-10\fR or \fI/dev/sda\fR. If the node refers
to an existing device mapper device representing a multipath map, this selects
the map or its paths, depending on the operation mode. Otherwise, it selects a path device.
.
.TP
.B device ID
kernel device number specified by major:minor numbers, e.g. \fI65:16\fR. This
format can only be used for path devices.
.
.TP
.B WWID
a World Wide Identifier matching a multipath map or its paths. To list WWIDs of devices
present in the system, use e.g. the command "\fImultipath -d -v3 2>/dev/null\fR".
.
.\" ----------------------------------------------------------------------------
.SH OPERATION MODES
.\" ----------------------------------------------------------------------------
.
The default operation mode is to detect and set up multipath maps from the devices found in
the system.
.
Other operation modes are chosen by using one of the following command line switches:
.TP
.B \-f
Flush (remove) a multipath device map specified as parameter, if unused. This operation is delegated to the multipathd daemon if it's running.
.
.TP
.B \-F
Flush (remove) all unused multipath device maps. This operation is delegated to the multipathd daemon if it's running.
.
.TP
.B \-l
Show ("list") the current multipath topology from information fetched in sysfs and the device mapper.
.
.TP
.B \-ll
Show ("list") the current multipath topology from all available information (sysfs, the
device mapper, path checkers ...).
.
.TP
.B \-a
Add the WWID for the specified device to the WWIDs file.
.
.TP
.B \-w
Remove the WWID for the specified device from the WWIDs file.
.
.TP
.B \-W
Reset the WWIDs file to only include the current multipath devices.
.
.TP
.B \-c
Check if a block device should be a path in a multipath device.
.
.TP
.B \-C
Check if a multipath device has usable paths. This can be used to
test whether or not I/O on this device is likely to succeed. The command
itself doesn't attempt to do I/O on the device.
.
.TP
.B \-u
Check if the device specified in the program environment should be
a path in a multipath device.
.
.TP
.B \-U
Check if the device specified in the program environment is a multipath device
with usable paths. See \fB-C\fB.
.
.TP
.B \-h
Print usage text.
.
.TP
.B \-t
Display the currently used multipathd configuration.
.
.TP
.B \-T
Display the currently used multipathd configuration, limiting the output to
those devices actually present in the system. This can be used a template for
creating \fI@CONFIGFILE@\fR.
.
.\" ----------------------------------------------------------------------------
.SH OPTIONS
.\" ----------------------------------------------------------------------------
.
.TP
.BI \-v " level"
Verbosity of information printed to stdout in default and "list" operation
modes. The default level is \fI-v 2\fR.
.RS 1.2i
.TP 1.2i
.I 0
Nothing is printed.
.TP
.I 1
In default mode, Names/WWIDs of created or modified multipath maps are
printed. In list mode, WWIDs of all multipath maps are printed.
.TP
.I 2
In default mode,
Topology of created or modified multipath maps is printed.
In list mode, topology of all multipath maps is printed.
.TP
.I 3
All detected paths and the topology of all multipath maps are printed.
.
.LP
.
The verbosity level also controls the level of log and debug messages printed to
\fIstderr\fR. The default level corresponds to \fILOG_NOTICE\fR
(important messages that shouldn't be missed in normal operation).
.
.RE
.TP
.B \-d
Dry run, do not create or update devmaps.
.
.TP
.B \-e
Enable all foreign libraries. This overrides the
.I enable_foreign
option from \fBmultipath.conf(5)\fR.
.
.TP
.B \-i
Ignore WWIDs file when processing devices. If
\fIfind_multipaths strict\fR or \fIfind_multipaths no\fR is set in
\fI@CONFIGFILE@\fR, multipath only considers devices that are
listed in the WWIDs file. This option overrides that behavior. For other values
of \fIfind_multipaths\fR, this option has no effect. See the description of
\fIfind_multipaths\fR in
.BR @CONFIGFILE@ (5).
This option should only be used in rare circumstances.
.
.TP
.B \-B
Treat the bindings file as read only.
.
.TP
.BI \-b " file"
(\fBdeprecated, do not use\fR) Set \fIuser_friendly_names\fR bindings file location. The default is
\fI@STATE_DIR@/bindings\fR.
.
.TP
.B \-q
Don't unset the device mapper feature \fIqueue_if_no_path\fR for multipath
maps. Normally, \fBmultipath\fR would do so if \fBmultipathd\fR is not
running, because only a running multipath daemon guarantees that unusable
paths are reinstated when they become usable again.
.
.TP
.BI \-p " policy"
Force new maps to use the specified policy, overriding the configuration in
\fBmultipath.conf(5)\fR. The possible values for
\fIpolicy\fR are the same as the values for \fIpath_grouping_policy\fR in
\fBmultipath.conf(5)\fR. Existing maps are not modified.
.
.TP
.B \-r
Force a reload of all existing multipath maps. This command is delegated to
the multipathd daemon if it's running. In this case, other command line
switches of the \fImultipath\fR command have no effect.
.
.TP
.BI \-R " retries"
Number of times to retry flushing multipath devices that are in use. The default
is \fI0\fR.
.
.\" ----------------------------------------------------------------------------
.SH "SEE ALSO"
.\" ----------------------------------------------------------------------------
.
.BR multipathd (8),
.BR multipath.conf (5),
.BR kpartx (8),
.BR udev (8),
.BR dmsetup (8),
.BR hotplug (8).
.
.
.\" ----------------------------------------------------------------------------
.SH AUTHORS
.\" ----------------------------------------------------------------------------
.
\fImultipath-tools\fR was developed by Christophe Varoqui <christophe.varoqui@opensvc.com>
and others.
.\" EOF