1MPATHPERSIST(8) System Manager's Manual MPATHPERSIST(8)
2
6 mpathpersist - Manages SCSI persistent reservations on dm multipath de‐
7 vices.
8
10 mpathpersist [OPTIONS] device
11
13 This utility is used to manage SCSI persistent reservations on Device
14 Mapper Multipath devices. To be able to use this functionality, the
15 reservation_key attribute must be defined in the /etc/multipath.conf
16 file. Otherwise the multipathd daemon will not check for persistent
17 reservation for newly discovered paths or reinstated paths.
18 mpathpersist supports the same command-line options as the sg_persist
20 utility. Consult the sg_persist (8) manual page for an in-depth dis‐
21 cussion of the various options.
22
24 -verbose|-v level
25 Verbosity:
26 0 Critical messages.
28 1 Error messages.
30 2 Warning messages.
32 3 Informational messages.
34 4 Informational messages with trace enabled.
36 --device=DEVICE|-d DEVICE
38 Query or change DEVICE.
39 --batch-file=DEVICE|-f FILE
41 Read commands from FILE. See section "BATCH FILES" below. This
42 option can be given at most once.
43 --help|-h
45 Output this usage message.
46 --hex|-H
48 Output response in hex.
49 --in|-i
51 Request PR In command.
52 --out|-o
54 Request PR Out command.
55 --param-alltgpt|-Y
57 PR Out parameter 'ALL_TG_PT'.
58 --param-aptpl|-Z
60 PR Out parameter 'APTPL'.
61 --read-keys|-k
63 PR In: Read Keys.
64 --param-rk=RK|-K RK
66 PR Out parameter reservation key (RK is in hex, up to 8 bytes).
67 --param-sark=SARK|-S SARK
69 PR Out parameter service action reservation key (SARK is in
70 hex).
71 --preempt|-P
73 PR Out: Preempt.
74 --clear|-C
76 PR Out: Clear registrations.
77 --preempt-abort|-A
79 PR Out: Preempt and Abort.
80 --prout-type=TYPE|-T TYPE
82 PR Out command type.
83 --read-full-status|-s
85 PR In: Read Full Status.
86 --read-keys|-k
88 PR In: Read Keys.
89 --read-reservation|-r
91 PR In: Read Reservation.
92 --register|-G
94 PR Out: Register.
95 --register-ignore|-I
97 PR Out: Register and Ignore.
98 --release|-L
100 PR Out: Release.
101 --report-capabilities|-c
103 PR In: Report Capabilities.
104 --reserve|-R
106 PR Out: Reserve.
107 --transport-id=TIDS|-X TIDS
109 TransportIDs can be mentioned in several forms.
110 --alloc-length=LEN|-l LEN
112 PR In: maximum allocation length. LEN is a decimal number be‐
113 tween 0 and 8192.
114
116 Register the key "123abc" for the /dev/mapper/mpath9 device:
117 mpathpersist --out --register --param-sark=123abc /dev/map‐
118 per/mpath9
119 Read registered reservation keys for the /dev/mapper/mpath9 device:
121 mpathpersist -i -k /dev/mapper/mpath9
122 Create a reservation for the /dev/mapper/mpath9 device with the given
124 reservation key:
125 mpathpersist --out --reserve --param-rk=123abc --prout-type=8 -d
126 /dev/mapper/mpath9
127 Read the reservation status of the /dev/mapper/mpath9 device:
129 mpathpersist -i -s -d /dev/mapper/mpath9
130 Release the previously created reservation (note that the prout-type
132 needs to be the same as above):
133 mpathpersist --out --release --param-rk=123abc --prout-type=8 -d
134 /dev/mapper/mpath9
135 Remove the current key registered for this host (i.e. reset it to 0):
137 mpathpersist --out --register-ignore -K 123abc -S 0 /dev/map‐
138 per/mpath9
139 Remove current reservation, and unregister all registered keys from all
141 I_T nexuses:
142 mpathpersist -oCK 123abc /dev/mapper/mpath9
143
145 The option --batch-file (-f) sets an input file to be processed by
146 mpathpersist. Grouping commands in batch files can provide a speed im‐
147 provement in particular on large installments, because mpathpersist
148 needs to scan existing paths and maps only once during startup.
149 The input file is a text file that is parsed line by line. Every line
151 of the file is interpreted as a command line (i.e. list of options and
152 parameters) for mpathpersist. Options and parameters are separated by
153 one or more whitespace characters (space or TAB). Lines can, but do
154 not have to, begin with the word "mpathpersist". The "#" character,
155 either at the beginning of the line or following some whitespace, de‐
156 notes the start of a comment that lasts until the end of the line.
157 Empty lines are allowed. Continuation of mpathpersist commands over
158 multiple lines is not supported.
159 All options listed in this man page, except -f and -v, are allowed in
161 batch files. Both short and long option formats may be used. Using the
162 -f option inside the batch file is an error. The -v option is ignored
163 in batch files.
164 The multipath map on which to act must be specified on every input
166 line, e.g. using the -d option. Commands acting on different multipath
167 maps may be combined in a batch file, and multiple commands may act on
168 the same multipath map. Commands are executed one by one, so that com‐
169 mands further down in the file see status changes caused by previous
170 commands. If mpathpersist encounters an error while processing a line
171 in the batch file, batch file processing is not aborted; subsequent
172 commands are executed nonetheless. The exit status of mpathpersist is
173 the status of the first failed command, or 0 if all commands succeeded.
174 If other options and parameters are used along with -f on the mpathper‐
176 sist command line, the command line will be executed first, followed by
177 the commands from the batch file.
178 Below is an example of a valid batch input file.
180 # This is an mpathpersist input file.
182 # Short and long forms of the same command
183 -i -k /dev/dm-1 # short form, this comment is ignored
184 mpathpersist --in --read-keys --device=/dev/dm-1
185 # Mixing of long and short options, variable white space
187 --out --register -S abcde /dev/dm-1
188 # Mixing of commands for different maps
190 -ir /dev/dm-0
191 -ir /dev/dm-1
192 mpathpersist --out --param-rk abcde --reserve --prout-type 5 /dev/dm-1
194 # This should now show a reservation
195 -ir /dev/dm-1
196 -oCK abcde /dev/dm-1
197 --in --read-reservation /dev/dm-1
198
200 multipath(8), multipathd(8), sg_persist(8).
201
203 multipath-tools was developed by Christophe Varoqui <christophe.varo‐
204 qui@opensvc.com> and others.
205Linux 2021-11-12 MPATHPERSIST(8)