1SG_PERSIST(8) SG3_UTILS SG_PERSIST(8)
2
6 sg_persist - use SCSI PERSISTENT RESERVE command to access registra‐
7 tions and reservations
8
10 sg_persist [OPTIONS] DEVICE
11 sg_persist [OPTIONS] --device=DEVICE
13 sg_persist --help | --version
15
17 This utility allows Persistent reservations and registrations to be
18 queried and changed. Persistent reservations and registrations are
19 queried by sub-commands (called "service actions" in SPC-4) of the SCSI
20 PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and reg‐
21 istrations are changed by sub-commands of the SCSI PERSISTENT RESERVE
22 OUT (PROUT) command.
23 There is a two stage process to obtain a persistent reservation. First
25 an application (an I_T nexus in standard's jargon) must register a
26 reservation key. If that is accepted (and it should be unless some
27 other I_T nexus has registered that key) then the application can try
28 and reserve the device. The reserve operation must specify the reser‐
29 vation key and a "type" (see the --prout-type=TYPE option).
30 It is relatively safe to query the state of Persistent reservations and
32 registrations. With no options this utility defaults to the READ KEYS
33 sub-command of the PRIN command. Other PRIN sub-commands are READ
34 RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.
35 Before trying to change Persistent reservations and registrations users
37 should be aware of what they are doing. The relevant sections of the
38 SCSI Primary Commands document (i.e. SPC-5 whose most recent draft is
39 revision 18 dated 4 January 2018) are sections 5.14 (titled "Reserva‐
40 tions"), 6.16 (for the PRIN command) and 6.17 (for the PROUT command).
41 To safeguard against accidental use, the --out option must be given
42 when a PROUT sub-command (e.g. --register) is used.
43 The older SCSI RESERVE and RELEASE commands (both 6 and 10 byte vari‐
45 ants) are not supported by this utility. In SPC-3, RESERVE and RELEASE
46 are deprecated, replaced by Persistent Reservations. RESERVE and
47 RELEASE have been removed from SPC-4 and Annex B is provided showing
48 how to convert to persistent reservation commands. See a utility called
49 'scsires' for support of the SCSI RESERVE and RELEASE commands.
50 The DEVICE is required by all variants of this utility apart from
52 --help. The DEVICE can be given either as an argument (typically but
53 not necessarily the last one) or via the --device=DEVICE option.
54 SPC-4 does not use the term "sub-command". It uses the term "service
56 action" for this and for part of a field's name in the parameter block
57 associated with the PROUT command (i.e. "service action reservation
58 key"). To lessen the potential confusion the term "sub-command" has
59 been introduced.
60
62 Arguments to long options are mandatory for short options as well. The
63 following options are sorted in alphabetical order, based on their long
64 option name.
65 -l, --alloc-length=LEN
67 specify the allocation length of the PRIN command. LEN is a hex
68 value. By default this value is set to the size of the data-in
69 buffer (8192). This parameter is of use for verification that
70 response to PRIN commands with various allocation lengths is per
71 section 4.3.5.6 of SPC-4 revision 18. Valid LEN values are
72 0-8192.
73 -C, --clear
75 Clear is a sub-command of the PROUT command. It releases the
76 persistent reservation (if any) and clears all registrations
77 from the device. It is required to supply a reservation key that
78 is registered for this I_T_L nexus (identified by
79 --param-rk=RK).
80 -d, --device=DEVICE
82 DEVICE to send SCSI commands to. The DEVICE can either be pro‐
83 vided via this option or via a freestanding argument. For exam‐
84 ple, these two: 'sg_persist --device=/dev/sg2' and 'sg_persist
85 /dev/sg2' are equivalent.
86 -h, --help
88 output a usage message showing main options. Use twice (e.g.
89 '-hh') for the other option and more help.
90 -H, --hex
92 the response to a valid PRIN sub-command will be output in hexa‐
93 decimal. By default (i.e. without this option) if the PRIN
94 sub-command is recognised then the response will be decoded as
95 per SPC-4. May be used more than once for more hex and less
96 text.
97 -i, --in
99 specify that a SCSI PERSISTENT RESERVE IN command is required.
100 This is the default.
101 -m, --maxlen=LEN
103 LEN is used as the ALLOCATION LENGTH field of the PRIN command.
104 LEN is by default a decimal value. To give a hex value use a
105 '0x' or '0X' prefix, or use a 'h' (or 'H') suffix. Can also take
106 multipliers, see --maxlen=LEN option in the sg3_utils manual
107 page.
108 This option is the same as --alloc-length=LEN option apart from
109 the representation of LEN. The option defaults to decimal while
110 --alloc-length=LEN only takes hex.
111 -n, --no-inquiry
113 the default action is to do a standard SCSI INQUIRY command and
114 output make, product and revision strings plus the peripheral
115 device type prior to executing a PRIN or PROUT command. With
116 this option the INQUIRY command is skipped.
117 -o, --out
119 specify that a SCSI PERSISTENT RESERVE OUT command is required.
120 -Y, --param-alltgpt
122 set the 'all target ports' (ALL_TG_PT) flag in the parameter
123 block of the PROUT command. Only relevant for 'register' and
124 'register and ignore existing key' sub-commands.
125 -Z, --param-aptpl
127 set the 'activate persist through power loss' (APTPL) flag in
128 the parameter block of the PROUT command. Relevant for 'regis‐
129 ter', 'register and ignore existing key' and 'register and move'
130 sub-commands.
131 -K, --param-rk=RK
133 specify the reservation key found in the parameter block of the
134 PROUT command. RK is assumed to be hex (up to 8 bytes long).
135 Default value is 0. This option is needed by most PROUT sub-com‐
136 mands.
137 -S, --param-sark=SARK
139 specify the service action reservation key found in the parame‐
140 ter block of the PROUT command. SARK is assumed to be hex (up to
141 8 bytes long). Default value is 0. This option is needed by
142 some PROUT sub-commands.
143 -P, --preempt
145 Preempt is a sub-command of the PROUT command. Preempts the
146 existing persistent reservation (identified by
147 --param-sark=SARK) with the registration key that is registered
148 for this I_T_L nexus (identified by --param-rk=RK). If a new
149 reservation is established as a result of the preemption then
150 the supplied --prout-type=TYPE is used as the type for this new
151 reservation.
152 -A, --preempt-abort
154 Preempt and Abort is a sub-command of the PROUT command. Pre‐
155 empts the existing persistent reservation (identified by
156 --param-sark=SARK) with the registration key that is registered
157 for this I_T_L nexus (identified by --param-rk=RK). If a new
158 reservation is established as a result of the preemption then
159 the supplied --prout-type=TYPE is used as the type for this new
160 reservation. ACA and other pending tasks are aborted.
161 -T, --prout-type=TYPE
163 specify the PROUT command's 'type' argument. Required by the
164 'register-move', 'reserve', 'release' and 'preempt (and abort)'
165 sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclu‐
166 sive access, 5-> write exclusive - registrants only, 6-> exclu‐
167 sive access - registrants only, 7-> write exclusive - all regis‐
168 trants, 8-> exclusive access - all registrants. Default value is
169 0 (which is an invalid type). Each "persistent reservation type"
170 is explained in more detail in a subsection of that name in the
171 read reservation section of the PRIN command (section 6.15.3.3
172 of SPC-4 revision 37).
173 -s, --read-full-status
175 Read Full Status is a sub-command of the PRIN command. For each
176 registration with the given SCSI device, it lists the reserva‐
177 tion key and associated information. TransportIDs, if supplied
178 in the response, are decoded.
179 -k, --read-keys
181 Read Keys is a sub-command of the PRIN command. Lists all the
182 reservation keys registered (i.e. registrations) with the given
183 SCSI device. This is the default sub-command for the SCSI PRIN
184 command.
185 -y, --readonly
187 Open DEVICE read-only. May be useful with PRIN commands if there
188 are unwanted side effects with the default read-write open. When
189 given twice is interpreted as forcing a read-write open thus
190 overriding the SG_PERSIST_IN_RDONLY environment variable if
191 present. See the ENVIRONMENT VARIABLES section for more.
192 -r, --read-reservation
194 Read Reservation is a sub-command of the PRIN command. List
195 information about the current holder of the reservation on the
196 DEVICE. If there is no current reservation this will be noted.
197 Information about the current holder of the reservation includes
198 its reservation key, scope and type.
199 -s, --read-status
201 same as --read-full-status.
202 -G, --register
204 Register is a sub-command of the PROUT command. It has 3 differ‐
205 ent actions depending on associated parameters. a) add a new
206 registration with '--param-rk=0' and '--param-sark=<new_rk>'; b)
207 Change an existing registration with '--param-rk=<old_rk>' and
208 '--param-sark=<new_rk>'; or c) Delete an existing registration
209 with '--param-rk=<old_rk>' and '--param-sark=0'.
210 -I, --register-ignore
212 Register and Ignore Existing Key is a sub-command of the PROUT
213 command. Similar to --register except that when changing a
214 reservation key the old key is not specified. The
215 '--param-sark=<new_rk>' option should also be given.
216 -M, --register-move
218 register (another initiator) and move (the reservation held by
219 the current initiator to that other initiator) is a sub-command
220 of the PROUT command. It requires the transportID of the other
221 initiator. [The standard uses the term I_T nexus but the point
222 to stress is that there are two initiators (the one sending this
223 command and another one) but only one logical unit.] The
224 --prout-type=TYPE and --param-rk=RK options need to match that
225 of the existing reservation while --param-sark=SARK option spec‐
226 ifies the reservation key of the new (i.e. destination) regis‐
227 tration.
228 -Q, --relative-target-port=RTPI
230 relative target port identifier that reservation is to be moved
231 to by PROUT 'register and move' sub-command. RTPI is assumed to
232 be hex in the range 0 to ffff inclusive. Defaults to 0 .
233 -L, --release
235 Release is a sub-command of the PROUT command. It releases the
236 current persistent reservation. The --prout-type=TYPE and
237 --param-rk=RK options, matching the reservation, must also be
238 specified.
239 -z, --replace-lost
241 Replace Lost Reservation is a sub-command of the PROUT command.
242 It "begins a recovery process for the lost persistent reserva‐
243 tion that is managed by application clients". It also stops the
244 device server terminating commands due to a lost persistent
245 reservation. Options should be be '--param-rk=0' (or not given),
246 '--param-sark=<new_rk>' and --prout-type=TYPE.
247 -c, --report-capabilities
249 Report Capabilities is a sub-command of the PRIN command. It
250 lists information about the aspects of persistent reservations
251 that the DEVICE supports.
252 -R, --reserve
254 Reserve is a sub-command of the PROUT command. It creates a new
255 persistent reservation (if permitted). The --prout-type=TYPE and
256 --param-rk=RK options must also be specified.
257 -X, --transport-id=TIDS
259 The TIDS argument can take one of several forms. It can be a
260 comma (or single space) separated list of ASCII hex bytes repre‐
261 senting a single TransportID as defined in SPC-4. They are usu‐
262 ally 24 bytes long apart from in iSCSI. The TIDS argument may be
263 a transport specific form (e.g. "sas,5000c50005b32001" is
264 clearer than an equivalent to the hex byte form:
265 "6,0,0,0,5,0,c5,0,5,b3,20,1"). The TIDS argument may be "-" in
266 which case one or more TransportIDs can be read from stdin. The
267 TIDS argument may be of the form "file=<name>" in which case one
268 or more TransportIDs can be read from a file called <name>. See
269 the "TRANSPORT IDs" section below for more information.
270 -U, --unreg
272 optional when the PROUT register and move sub-command is
273 invoked. If given it will unregister the current initiator (I_T
274 nexus) after the other initiator has been registered and the
275 reservation moved to it. When not given the initiator (I_T
276 nexus) that sent the PROUT command remains registered.
277 -v, --verbose
279 print out cdb of issued commands prior to execution. If used
280 twice prints out the parameter block associated with the PROUT
281 command prior to its execution as well. If used thrice decodes
282 given transportID(s) as well. To see the response to a PRIN com‐
283 mand in low level form use the --hex option.
284 -V, --version
286 print out version string. Ignore all other parameters.
287 -? output usage message. Ignore all other parameters.
289
291 TransportIDs are used in persistent reservations to identify initia‐
292 tors. The format of a TransportID differs depending on the type of
293 transport being used. Their format is described in SPC-4 (in draft
294 revision 37 see section 7.6.4).
295 A TransportID is required for the PROUT 'register and move' sub-command
297 and the PROUT 'register' sub-command can have zero, one or more Trans‐
298 portIDs.
299 When the --transport-id=TIDS option is given then the TIDS argument may
301 be a comma (or single space) separated list of ASCII hex bytes that
302 represent a single TransportID as defined in SPC-4. Alternatively the
303 TIDS argument may be a transport specific string starting with either
304 "fcp,", "spi,", "sbp,", "srp,", "iqn", "sas," or "sop,". The "iqn" form
305 is an iSCSI qualified name. Apart from "iqn" the other transport spe‐
306 cific leadin string may be given in upper case (e.g. "FCP,").
307 The "fcp," form should be followed by 16 ASCII hex digits that repre‐
309 sent an initiator's N_PORT_NAME (e.g. "fcp,10000000C9F3A571"). The
310 "spi," form should be followed by "<scsi_address>,<relative_tar‐
311 get_port_identifier>" (both decimal numbers). The "sbp," form should be
312 followed by 16 ASCII hex digits that represent an initiator's EUI-64
313 name. The "srp," form should be followed by 32 ASCII hex digits that
314 represent an initiator port identifier. The "sas," form should be fol‐
315 lowed by 16 ASCII hex digits that represent an initiator's port SAS
316 address (e.g. "sas,5000c50005b32001"). The "sop," form takes a hex num‐
317 ber that represents a routing id.
318 There are two iSCSI qualified name forms. The shorter form contains the
320 iSCSI name of the initiator port (e.g. "iqn.5886.com.acme.diskar‐
321 rays-sn-a8675309"). The longer form adds the initiator session id (ISID
322 in hex) separated by ",i,0x". For example "iqn.5886.com.acme.diskar‐
323 rays-sn-a8675309,i,0x1234567890ab". On the command line to stop punc‐
324 tuation in an iSCSI name being (mis)-interpreted by the shell, putting
325 the option argument containing the iSCSI name in double quotes is
326 advised. iSCSI names are encoded in UTF-8 so if non (7 bit) ASCII char‐
327 acters appear in the iSCSI name on the command line, there will be dif‐
328 ficulties if they are not encoded in UTF-8. The locale can be changed
329 temporarily by prefixing the command line invocation of sg_persist with
330 "LANG=en_US.utf-8" for example.
331 Alternatively the TIDS argument may specify a file (or pipe) from which
333 one or more TransportIDs may be read. If the TIDS argument is "-" then
334 stdin (standard input) is read. If the TIDS argument is of the form
335 "file=<name>" then a file called <name> is read. A valid SPC-4 Trans‐
336 portID is built from the transport specific string outlined in the pre‐
337 vious paragraphs. The parsing of the data read is relatively simple.
338 Empty lines are ignored. Everything from and including a "#" on a line
339 is ignored. Leading spaces and tabs are ignored. There can be one
340 transportID per line. The transportID can either be a comma, space or
341 tab separated list of ASCII hex bytes that represent a TransportID as
342 defined in SPC-4. Padding with zero bytes to a minimum length of 24
343 bytes is performed if necessary. The transportID may also be transport
344 specific string type discussed above.
345 In SPC-3 the SPEC_I_PT bit set to one and TransportIDs were allowed for
347 the PROUT register and ignore existing key sub-command. In SPC-4 that
348 is disallowed yielding a CHECK CONDITION status with and ILLEGAL
349 REQUEST sense key and an additional sense code set to INVALID FIELD IN
350 PARAMETER LIST.
351
353 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
354 (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc,
355 /dev/st1m or /dev/sg3) can be specified. For example "sg_persist
356 --read-keys /dev/sdb" will work in the 2.6 series kernels.
357 The only scope for PROUT commands supported in the current draft of
359 SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an
360 option to set scope to another value.
361 Most errors with the PROUT sub-commands (e.g. missing or mismatched
363 --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This
364 can be a bit confusing when you know there is only one (active) initia‐
365 tor: the "conflict" is with the SPC standard, not another initiator.
366 Some recent disks accept some PRIN and PROUT sub-commands when the
368 media is stopped. One exception was setting the APTPL flag (with the
369 --param-aptpl option) during a key register operation, it complained if
370 the disk one stopped. The error indicated it wanted the disk spun up
371 and when that happened, the registration was successful.
372
374 These examples use Linux device names. For suitable device names in
375 other supported Operating Systems see the sg3_utils(8) man page.
376 Due to the various option defaults the simplest example executes the
378 'read keys' sub-command of the PRIN command:
379 sg_persist /dev/sdb
381 This is the same as the following (long-winded) command:
383 sg_persist --in --read-keys --device=/dev/sdb
385 To read the current reservation either the '--read-reservation' form or
387 the shorter '-r' can be used:
388 sg_persist -r /dev/sdb
390 To register the new reservation key 0x123abc the following could be
392 used:
393 sg_persist --out --register --param-sark=123abc /dev/sdb
395 Given the above registration succeeds, to reserve the DEVICE (with type
397 'write exclusive') the following could be used:
398 sg_persist --out --reserve --param-rk=123abc
400 --prout-type=1 /dev/sdb
401 To release the reservation the following can be given (note that the
403 --param-rk and --prout-type arguments must match those of the reserva‐
404 tion):
405 sg_persist --out --release --param-rk=123abc
407 --prout-type=1 /dev/sdb
408 Finally to unregister a reservation key (and not effect other registra‐
410 tions which is what '--clear' would do) the command is a little sur‐
411 prising:
412 sg_persist --out --register --param-rk=123abc /dev/sdb
414 Now have a close look at the difference between the register and unreg‐
416 ister examples above.
417 An example file that is suitably formatted to pass transportIDs via a
419 '--transport-id=file=transport_ids.txt' option can be found in the
420 examples sub-directory of the sg3_utils package. There is also a simple
421 test script called sg_persist_tst.sh in the same directory.
422 The above sequence of commands was tested successfully on a Seagate
424 Savvio 10K.3 disk and a 1200 SSD both of which have SAS interfaces.
425
427 The exit status of sg_persist is 0 when it is successful. Otherwise see
428 the sg3_utils(8) man page.
429
431 Currently there is one recognised environment variable: SG_PER‐
432 SIST_IN_RDONLY. If present and only if a PRIN command has been
433 selected then the given DEVICE is opened read-only (e.g. in Unix that
434 is with the O_RDONLY flag). See the --readonly option.
435
437 Written by Douglas Gilbert
438
440 Report bugs to <dgilbert at interlog dot com>.
441
443 Copyright © 2004-2018 Douglas Gilbert
444 This software is distributed under the GPL version 2. There is NO war‐
445 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
446 POSE.
447
449 sg3_utils(sg3_utils), scsires(internet)
450sg3_utils-1.43 June 2018 SG_PERSIST(8)