cd602e40c77a747bb9075bc18085e8956eef4c9b
[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 2016-10-30 "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 .B \--help|\-h
75 Output this usage message.
76 .
77 .TP
78 .B \--hex|\-H
79 Output response in hex.
80 .
81 .TP
82 .B \--in|\-i
83 Request PR In command.
84 .
85 .TP
86 .B \--out|\-o
87 Request PR Out command.
88 .
89 .TP
90 .B \--param-alltgpt|\-Y
91 PR Out parameter 'ALL_TG_PT'.
92 .
93 .TP
94 .B \--param-aptpl|\-Z
95 PR Out parameter 'APTPL'.
96 .
97 .TP
98 .B \--read-keys|\-k
99 PR In: Read Keys.
100 .
101 .TP
102 .BI \--param-rk=\fIRK\fB|\-K " RK"
103 PR Out parameter reservation key (RK is in hex, up to 8 bytes).
104 .
105 .TP
106 .BI \--param-sark=\fISARK\fB|\-S " SARK"
107 PR Out parameter service action reservation key (SARK is in hex).
108 .
109 .TP
110 .B \--preempt|\-P
111 PR Out: Preempt.
112 .
113 .TP
114 .B \--clear|\-C
115 PR Out: Clear registrations.
116 .
117 .TP
118 .B \--preempt-abort|\-A
119 PR Out: Preempt and Abort.
120 .
121 .TP
122 .BI \--prout-type=\fITYPE\fB|\-T " TYPE"
123 PR Out command type.
124 .
125 .TP
126 .B \--read-full-status|\-s
127 PR In: Read Full Status.
128 .
129 .TP
130 .B \--read-keys|\-k
131 PR In: Read Keys.
132 .
133 .TP
134 .B \--read-reservation|\-r
135 PR In: Read Reservation.
136 .
137 .TP
138 .B \--register|\-G
139 PR Out: Register.
140 .
141 .TP
142 .B \--register-ignore|\-I
143 PR Out: Register and Ignore.
144 .
145 .TP
146 .B \--release|\-L
147 PR Out: Release.
148 .
149 .TP
150 .B \--report-capabilities|\-c
151 PR In: Report Capabilities.
152 .
153 .TP
154 .B \--reserve|\-R
155 PR Out: Reserve.
156 .
157 .TP
158 .BI \--transport-id=\fITIDS\fB|\-X " TIDS"
159 TransportIDs can be mentioned in several forms.
160 .
161 .TP
162 .BI \--alloc-length=\fILEN\fB|\-l " LEN"
163 PR In: maximum allocation length. LEN is a decimal number between 0 and 8192.
164 .
165 .
166 .\" ----------------------------------------------------------------------------
167 .SH EXAMPLE
168 .\" ----------------------------------------------------------------------------
169 .
170 .PP
171 Register the key \(dq123abc\(dq for the /dev/mapper/mpath9 device:
172 .RS
173 \fBmpathpersist --out --register --param-sark=\fI123abc /dev/mapper/mpath9\fR
174 .RE
175 .PP
176 Read registered reservation keys for the /dev/mapper/mpath9 device:
177 .RS
178 \fBmpathpersist -i -k \fI/dev/mapper/mpath9\fR
179 .RE
180 .PP
181 Create a reservation for the /dev/mapper/mpath9 device with the given
182 reservation key:
183 .RS
184 \fBmpathpersist --out --reserve --param-rk=\fI123abc \fB--prout-type=\fI8 \fB-d \fI/dev/mapper/mpath9\fR
185 .RE
186 .PP
187 Read the reservation status of the /dev/mapper/mpath9 device:
188 .RS
189 \fBmpathpersist -i -s -d \fI/dev/mapper/mpath9\fR
190 .RE
191 .PP
192 Release the previously created reservation (note that the prout-type needs to
193 be the same as above):
194 .RS
195 \fBmpathpersist --out --release --param-rk=\fI123abc \fB--prout-type=\fI8 \fB-d \fI/dev/mapper/mpath9\fR
196 .RE
197 .PP
198 Remove the current key registered for this host (i.e. reset it to 0):
199 .RS
200 \fBmpathpersist --out --register-ignore -K \fI123abc\fB -S \fI0\fB \fI/dev/mapper/mpath9\fR
201 .RE
202 .PP
203 Remove current reservation, and unregister all registered keys from all I_T nexuses:
204 .RS
205 \fBmpathpersist -oCK \fI123abc \fI/dev/mapper/mpath9\fR
206 .RE
207 .
208 .
209 .\" ----------------------------------------------------------------------------
210 .SH "SEE ALSO"
211 .\" ----------------------------------------------------------------------------
212 .
213 .BR multipath (8),
214 .BR multipathd (8),
215 .BR sg_persist (8).
216 .
217 .
218 .\" ----------------------------------------------------------------------------
219 .SH AUTHORS
220 .\" ----------------------------------------------------------------------------
221 .
222 \fImultipath-tools\fR was developed by Christophe Varoqui <christophe.varoqui@opensvc.com>
223 and others.
224 .\" EOF