mpathpersist.8: add documentation for --batch-file (-f)
[multipath-tools/.git] / mpathpersist / mpathpersist.8
1 .\" ----------------------------------------------------------------------------
2 .\" Update the date below if you make any significant change.
3 .\" Make sure there are no errors with:
4 .\" groff -z -wall -b -e -t mpathpersist/mpathpersist.8
5 .\"
6 .\" ----------------------------------------------------------------------------
7 .
8 .TH MPATHPERSIST 8 2019-05-27 "Linux"
9 .
10 .
11 .\" ----------------------------------------------------------------------------
12 .SH NAME
13 .\" ----------------------------------------------------------------------------
14 .
15 mpathpersist \- Manages SCSI persistent reservations on dm multipath devices.
16 .
17 .
18 .\" ----------------------------------------------------------------------------
19 .SH SYNOPSIS
20 .\" ----------------------------------------------------------------------------
21 .
22 .B mpathpersist
23 .RB [\| OPTIONS \|]
24 .I device
25 .
26 .
27 .\" ----------------------------------------------------------------------------
28 .SH DESCRIPTION
29 .\" ----------------------------------------------------------------------------
30 .
31 This utility is used to manage SCSI persistent reservations on Device Mapper
32 Multipath devices. To be able to use this functionality, the \fIreservation_key\fR
33 attribute must be defined in the \fI/etc/multipath.conf\fR file. Otherwise the
34 \fBmultipathd\fR daemon will not check for persistent reservation for newly
35 discovered paths or reinstated paths.
36 .
37 .LP
38 \fBmpathpersist\fR supports the same command-line options as the
39 \fBsg_persist\fR utility.
40 .
41 Consult the \fBsg_persist (8)\fR manual page for an in-depth discussion of the
42 various options.
43 .
44 .\" ----------------------------------------------------------------------------
45 .SH OPTIONS
46 .\" ----------------------------------------------------------------------------
47 .
48 .TP
49 .BI \-verbose|\-v " level"
50 Verbosity:
51 .RS
52 .TP 5
53 .I 0
54 Critical messages.
55 .TP
56 .I 1
57 Error messages.
58 .TP
59 .I 2
60 Warning messages.
61 .TP
62 .I 3
63 Informational messages.
64 .TP
65 .I 4
66 Informational messages with trace enabled.
67 .RE
68 .
69 .TP
70 .BI \--device=\fIDEVICE\fB|\-d " DEVICE"
71 Query or change DEVICE.
72 .
73 .TP
74 .BI \--batch-file=\fIDEVICE\fB|\-f " FILE"
75 Read commands from \fIFILE\fR. See section \(dqBATCH FILES\(dq below. This
76 option can be given at most once.
77 .
78 .TP
79 .B \--help|\-h
80 Output this usage message.
81 .
82 .TP
83 .B \--hex|\-H
84 Output response in hex.
85 .
86 .TP
87 .B \--in|\-i
88 Request PR In command.
89 .
90 .TP
91 .B \--out|\-o
92 Request PR Out command.
93 .
94 .TP
95 .B \--param-alltgpt|\-Y
96 PR Out parameter 'ALL_TG_PT'.
97 .
98 .TP
99 .B \--param-aptpl|\-Z
100 PR Out parameter 'APTPL'.
101 .
102 .TP
103 .B \--read-keys|\-k
104 PR In: Read Keys.
105 .
106 .TP
107 .BI \--param-rk=\fIRK\fB|\-K " RK"
108 PR Out parameter reservation key (RK is in hex, up to 8 bytes).
109 .
110 .TP
111 .BI \--param-sark=\fISARK\fB|\-S " SARK"
112 PR Out parameter service action reservation key (SARK is in hex).
113 .
114 .TP
115 .B \--preempt|\-P
116 PR Out: Preempt.
117 .
118 .TP
119 .B \--clear|\-C
120 PR Out: Clear registrations.
121 .
122 .TP
123 .B \--preempt-abort|\-A
124 PR Out: Preempt and Abort.
125 .
126 .TP
127 .BI \--prout-type=\fITYPE\fB|\-T " TYPE"
128 PR Out command type.
129 .
130 .TP
131 .B \--read-full-status|\-s
132 PR In: Read Full Status.
133 .
134 .TP
135 .B \--read-keys|\-k
136 PR In: Read Keys.
137 .
138 .TP
139 .B \--read-reservation|\-r
140 PR In: Read Reservation.
141 .
142 .TP
143 .B \--register|\-G
144 PR Out: Register.
145 .
146 .TP
147 .B \--register-ignore|\-I
148 PR Out: Register and Ignore.
149 .
150 .TP
151 .B \--release|\-L
152 PR Out: Release.
153 .
154 .TP
155 .B \--report-capabilities|\-c
156 PR In: Report Capabilities.
157 .
158 .TP
159 .B \--reserve|\-R
160 PR Out: Reserve.
161 .
162 .TP
163 .BI \--transport-id=\fITIDS\fB|\-X " TIDS"
164 TransportIDs can be mentioned in several forms.
165 .
166 .TP
167 .BI \--alloc-length=\fILEN\fB|\-l " LEN"
168 PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.
169 .
170 .
171 .\" ----------------------------------------------------------------------------
172 .SH EXAMPLE
173 .\" ----------------------------------------------------------------------------
174 .
175 .PP
176 Register the key \(dq123abc\(dq for the /dev/mapper/mpath9 device:
177 .RS
178 \fBmpathpersist --out --register --param-sark=\fI123abc /dev/mapper/mpath9\fR
179 .RE
180 .PP
181 Read registered reservation keys for the /dev/mapper/mpath9 device:
182 .RS
183 \fBmpathpersist -i -k \fI/dev/mapper/mpath9\fR
184 .RE
185 .PP
186 Create a reservation for the /dev/mapper/mpath9 device with the given
187 reservation key:
188 .RS
189 \fBmpathpersist --out --reserve --param-rk=\fI123abc \fB--prout-type=\fI8 \fB-d \fI/dev/mapper/mpath9\fR
190 .RE
191 .PP
192 Read the reservation status of the /dev/mapper/mpath9 device:
193 .RS
194 \fBmpathpersist -i -s -d \fI/dev/mapper/mpath9\fR
195 .RE
196 .PP
197 Release the previously created reservation (note that the prout-type needs to
198 be the same as above):
199 .RS
200 \fBmpathpersist --out --release --param-rk=\fI123abc \fB--prout-type=\fI8 \fB-d \fI/dev/mapper/mpath9\fR
201 .RE
202 .PP
203 Remove the current key registered for this host (i.e. reset it to 0):
204 .RS
205 \fBmpathpersist --out --register-ignore -K \fI123abc\fB -S \fI0\fB \fI/dev/mapper/mpath9\fR
206 .RE
207 .PP
208 Remove current reservation, and unregister all registered keys from all I_T nexuses:
209 .RS
210 \fBmpathpersist -oCK \fI123abc \fI/dev/mapper/mpath9\fR
211 .RE
212 .
213 .
214 .\" ----------------------------------------------------------------------------
215 .SH BATCH FILES
216 .\" ----------------------------------------------------------------------------
217 .
218 .PP
219 The option \fI--batch-file\fR (\fI-f\fR) sets an input file to be processed
220 by \fBmpathpersist\fR. Grouping commands in batch files can provide a speed
221 improvement in particular on large installments, because \fBmpathpersist\fR
222 needs to scan existing paths and maps only once during startup.
223 .
224 .PP
225 The input file is a text file that is parsed
226 line by line. Every line of the file is interpreted as a command line
227 (i.e. list of options and parameters) for \fBmpathpersist\fR. Options
228 and parameters are separated by one or more whitespace characters (space or TAB).
229 Lines can, but do not have to, begin with the word \(dqmpathpersist\(dq.
230 The \(dq#\(dq character, either at the beginning of the line or following
231 some whitespace, denotes the start of a comment that lasts until the end of the
232 line. Empty lines are allowed. Continuation of mpathpersist commands over
233 multiple lines is not supported.
234 .
235 .PP
236 All options listed in this man page, except \fI-f\fR and
237 \fI-v\fR, are allowed in batch files. Both short and long option formats may be used.
238 Using the  \fI-f\fR option inside the batch file is an error. The \fI-v\fR
239 option is ignored in batch files.
240 .
241 .PP
242 The multipath map on which to act must be specified on every input line, e.g. using the \fI-d\fR option.
243 Commands acting on different multipath maps may be combined in a
244 batch file, and multiple commands may act on the same multipath
245 map. Commands are executed one by one, so
246 that commands further down in the file see status changes caused by previous
247 commands.
248 If \fBmpathpersist\fR encounters an error while processing a line in the
249 batch file, batch file processing is \fBnot\fR aborted; subsequent commands
250 are executed nonetheless. The exit status of \fBmpathpersist\fR is the status
251 of the first failed command, or 0 if all commands succeeded.
252 .
253 .PP
254 If other options and parameters are used along with
255 \fI-f\fR on the \fBmpathpersist\fR command line, the command line will be executed first, followed
256 by the commands from the the batch file.
257 .
258 .PP
259 Below is an example of a valid batch input file.
260 .
261 .PP
262 .RS
263 .EX
264 # This is an mpathpersist input file.
265 # Short and long forms of the same command
266 -i -k /dev/dm-1 # short form, this comment is ignored
267 mpathpersist --in --read-keys --device=/dev/dm-1
268
269 # Mixing of long and short options, variable white space
270   --out  --register    -S  abcde     /dev/dm-1
271
272 # Mixing of commands for different maps
273 -ir /dev/dm-0
274 -ir /dev/dm-1
275
276 mpathpersist --out --param-rk abcde --reserve --prout-type 5 /dev/dm-1
277 # This should now show a reservation
278 -ir /dev/dm-1
279 -oCK abcde /dev/dm-1
280 --in --read-reservation /dev/dm-1
281 .EE
282 .RE
283 .
284 .
285 .\" ----------------------------------------------------------------------------
286 .SH "SEE ALSO"
287 .\" ----------------------------------------------------------------------------
288 .
289 .BR multipath (8),
290 .BR multipathd (8),
291 .BR sg_persist (8).
292 .
293 .
294 .\" ----------------------------------------------------------------------------
295 .SH AUTHORS
296 .\" ----------------------------------------------------------------------------
297 .
298 \fImultipath-tools\fR was developed by Christophe Varoqui <christophe.varoqui@opensvc.com>
299 and others.
300 .\" EOF