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

NAME

6       mpathpersist - Manages SCSI persistent reservations on dm multipath de‐
7       vices.
8

SYNOPSIS

10       mpathpersist [OPTIONS] device
11

DESCRIPTION

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
19       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

OPTIONS

24       -verbose|-v level
25              Verbosity:
26
27              0    Critical messages.
28
29              1    Error messages.
30
31              2    Warning messages.
32
33              3    Informational messages.
34
35              4    Informational messages with trace enabled.
36
37       --device=DEVICE|-d DEVICE
38              Query or change DEVICE.
39
40       --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
44       --help|-h
45              Output this usage message.
46
47       --hex|-H
48              Output response in hex.
49
50       --in|-i
51              Request PR In command.
52
53       --out|-o
54              Request PR Out command.
55
56       --param-alltgpt|-Y
57              PR Out parameter 'ALL_TG_PT'.
58
59       --param-aptpl|-Z
60              PR Out parameter 'APTPL'.
61
62       --read-keys|-k
63              PR In: Read Keys.
64
65       --param-rk=RK|-K RK
66              PR Out parameter reservation key (RK is in hex, up to 8 bytes).
67
68       --param-sark=SARK|-S SARK
69              PR  Out  parameter  service  action  reservation key (SARK is in
70              hex).
71
72       --preempt|-P
73              PR Out: Preempt.
74
75       --clear|-C
76              PR Out: Clear registrations.
77
78       --preempt-abort|-A
79              PR Out: Preempt and Abort.
80
81       --prout-type=TYPE|-T TYPE
82              PR Out command type.
83
84       --read-full-status|-s
85              PR In: Read Full Status.
86
87       --read-keys|-k
88              PR In: Read Keys.
89
90       --read-reservation|-r
91              PR In: Read Reservation.
92
93       --register|-G
94              PR Out: Register.
95
96       --register-ignore|-I
97              PR Out: Register and Ignore.
98
99       --release|-L
100              PR Out: Release.
101
102       --report-capabilities|-c
103              PR In: Report Capabilities.
104
105       --reserve|-R
106              PR Out: Reserve.
107
108       --transport-id=TIDS|-X TIDS
109              TransportIDs can be mentioned in several forms.
110
111       --alloc-length=LEN|-l LEN
112              PR In: maximum allocation length. LEN is a  decimal  number  be‐
113              tween 0 and 8192.
114

EXAMPLE

116       Register the key "123abc" for the /dev/mapper/mpath9 device:
117              mpathpersist   --out  --register  --param-sark=123abc  /dev/map‐
118              per/mpath9
119
120       Read registered reservation keys for the /dev/mapper/mpath9 device:
121              mpathpersist -i -k /dev/mapper/mpath9
122
123       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
128       Read the reservation status of the /dev/mapper/mpath9 device:
129              mpathpersist -i -s -d /dev/mapper/mpath9
130
131       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
136       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
140       Remove current reservation, and unregister all registered keys from all
141       I_T nexuses:
142              mpathpersist -oCK 123abc /dev/mapper/mpath9
143

BATCH FILES

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
150       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
160       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
165       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
175       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
179       Below is an example of a valid batch input file.
180
181              # 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
186              # Mixing of long and short options, variable white space
187                --out  --register    -S  abcde     /dev/dm-1
188
189              # Mixing of commands for different maps
190              -ir /dev/dm-0
191              -ir /dev/dm-1
192
193              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

SEE ALSO

200       multipath(8), multipathd(8), sg_persist(8).
201

AUTHORS

203       multipath-tools was developed by Christophe  Varoqui  <christophe.varo‐
204       qui@opensvc.com> and others.
205
206
207
208Linux                             2021-11-12                   MPATHPERSIST(8)
Impressum