1MULTIPATH(8)                System Manager's Manual               MULTIPATH(8)
2
3
4

NAME

6       multipath - Device mapper target autoconfig.
7

SYNOPSIS

9       multipath [-v level] [-B|-d|-i|-q|-r] [-b file] [-p policy] [device]
10
11       multipath [-v level] [-R retries] -f device
12
13       multipath [-v level] [-R retries] -F
14
15       multipath [-v level] [-l|-ll] [device]
16
17       multipath [-v level] [-a|-w] device
18
19       multipath [-v level] [-A|-W]
20
21       multipath [-v level] [-i] [-c|-C] device
22
23       multipath [-v level] [-i] [-u|-U]
24
25       multipath [-h|-t|-T]
26

DESCRIPTION

28       multipath is used to detect and coalesce multiple paths to devices, for
29       fail-over or performance reasons.
30

ARGUMENTS

32       The device argument restricts multipath's operation to devices matching
33       the  given expression. The argument may refer either to a multipath map
34       or to its components ("paths"). The expression may be  in  one  of  the
35       following formats:
36
37       device node   file  name of a device node, e.g. /dev/dm-10 or /dev/sda.
38                     If the node refers to an existing  device  mapper  device
39                     representing a multipath map, this selects the map or its
40                     paths, depending on the operation mode. Otherwise, it se‐
41                     lects a path device.
42
43       device ID     kernel  device  number  specified by major:minor numbers,
44                     e.g. 65:16. This format can only be  used  for  path  de‐
45                     vices.
46
47       WWID          a  World  Wide Identifier matching a multipath map or its
48                     paths. To list WWIDs of devices present  in  the  system,
49                     use e.g. the command "multipath -d -v3 2>/dev/null".
50

OPERATION MODES

52       The  default operation mode is to detect and set up multipath maps from
53       the devices found in the system.  Other operation modes are  chosen  by
54       using one of the following command line switches:
55
56       -f     Flush (remove) a multipath device map specified as parameter, if
57              unused. This operation is delegated to the multipathd daemon  if
58              it's running.
59
60       -F     Flush  (remove) all unused multipath device maps. This operation
61              is delegated to the multipathd daemon if it's running.
62
63       -l     Show ("list") the current multipath  topology  from  information
64              fetched in sysfs and the device mapper.
65
66       -ll    Show  ("list") the current multipath topology from all available
67              information (sysfs, the device mapper, path checkers ...).
68
69       -a     Add the WWID for the specified device to the WWIDs file.
70
71       -A     Add the WWIDs from any kernel command line mpath.wwid parameters
72              to the WWIDs file.
73
74       -w     Remove the WWID for the specified device from the WWIDs file.
75
76       -W     Reset  the  WWIDs file to only include the current multipath de‐
77              vices.
78
79       -c     Check if a block device should be a path in a multipath device.
80
81       -C     Check if a multipath device has usable paths. This can  be  used
82              to  test whether or not I/O on this device is likely to succeed.
83              The command itself doesn't attempt to do I/O on the device.
84
85       -u     Check if the device specified in the program environment  should
86              be a path in a multipath device.
87
88       -U     Check  if  the  device specified in the program environment is a
89              multipath device with usable paths. See -C.
90
91       -h     Print usage text.
92
93       -t     Display the currently used multipathd configuration.
94
95       -T     Display the currently used  multipathd  configuration,  limiting
96              the output to those devices actually present in the system. This
97              can be used a template for creating multipath.conf.
98

OPTIONS

100       -v level
101              Verbosity of information printed to stdout in default and "list"
102              operation modes. The default level is -v 2.
103
104                   0           Nothing is printed.
105
106                   1           In default mode, Names/WWIDs of created or mod‐
107                               ified multipath maps are printed. In list mode,
108                               WWIDs of all multipath maps are printed.
109
110                   2           In  default  mode, Topology of created or modi‐
111                               fied multipath maps is printed.  In list  mode,
112                               topology of all multipath maps is printed.
113
114                   3           All detected paths and the topology of all mul‐
115                               tipath maps are printed.
116
117                   The verbosity level also controls the level of log and  de‐
118                   bug  messages  printed  to stderr. The default level corre‐
119                   sponds to LOG_NOTICE (important messages that shouldn't  be
120                   missed in normal operation).
121
122       -d     Dry run, do not create or update devmaps.
123
124       -e     Enable  all foreign libraries. This overrides the enable_foreign
125              option from multipath.conf(5).
126
127       -i     Ignore WWIDs file when processing  devices.  If  find_multipaths
128              strict or find_multipaths no is set in multipath.conf, multipath
129              only considers devices that are listed in the WWIDs  file.  This
130              option  overrides that behavior. For other values of find_multi‐
131              paths, this  option  has  no  effect.  See  the  description  of
132              find_multipaths  in  multipath.conf(5).  This option should only
133              be used in rare circumstances.
134
135       -B     Treat the bindings file as read only.
136
137       -b file
138              Set user_friendly_names bindings file location.  The default  is
139              /etc/multipath/bindings.
140
141       -q     Don't  unset the device mapper feature queue_if_no_path for mul‐
142              tipath maps. Normally, multipath would do so  if  multipathd  is
143              not  running, because only a running multipath daemon guarantees
144              that unusable paths  are  reinstated  when  they  become  usable
145              again.
146
147       -p policy
148              Force  new maps to use the specified policy, overriding the con‐
149              figuration in multipath.conf(5). The possible values for  policy
150              are  the  same  as the values for path_grouping_policy in multi‐
151              path.conf(5). Existing maps are not modified.
152
153       -r     Force a reload of all existing multipath maps. This  command  is
154              delegated  to  the  multipathd  daemon  if it's running. In this
155              case, other command line switches of the multipath command  have
156              no effect.
157
158       -R retries
159              Number  of times to retry flushing multipath devices that are in
160              use. The default is 0.
161

SEE ALSO

163       multipathd(8), multipath.conf(5), kpartx(8), udev(8), dmsetup(8),  hot‐
164       plug(8).
165

AUTHORS

167       multipath-tools  was  developed by Christophe Varoqui <christophe.varo‐
168       qui@opensvc.com> and others.
169
170
171
172Linux                             2018-10-10                      MULTIPATH(8)
Impressum