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-4 whose most recent draft is
39 revision 37 dated 17 May 2014) are sections 5.12 (titled "Reserva‐
40 tions"), 6.15 (for the PRIN command) and 6.16 (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 -n, --no-inquiry
103 the default action is to do a standard SCSI INQUIRY command and
104 output make, product and revision strings plus the peripheral
105 device type prior to executing a PRIN or PROUT command. With
106 this option the INQUIRY command is skipped.
107 -o, --out
109 specify that a SCSI PERSISTENT RESERVE OUT command is required.
110 -Y, --param-alltgpt
112 set the 'all target ports' (ALL_TG_PT) flag in the parameter
113 block of the PROUT command. Only relevant for 'register' and
114 'register and ignore existing key' sub-commands.
115 -Z, --param-aptpl
117 set the 'activate persist through power loss' (APTPL) flag in
118 the parameter block of the PROUT command. Relevant for 'regis‐
119 ter', 'register and ignore existing key' and 'register and move'
120 sub-commands.
121 -K, --param-rk=RK
123 specify the reservation key found in the parameter block of the
124 PROUT command. RK is assumed to be hex (up to 8 bytes long).
125 Default value is 0. This option is needed by most PROUT sub-com‐
126 mands.
127 -S, --param-sark=SARK
129 specify the service action reservation key found in the parame‐
130 ter block of the PROUT command. SARK is assumed to be hex (up to
131 8 bytes long). Default value is 0. This option is needed by
132 some PROUT sub-commands.
133 -P, --preempt
135 Preempt is a sub-command of the PROUT command. Preempts the
136 existing persistent reservation (identified by
137 --param-sark=SARK) with the registration key that is registered
138 for this I_T_L nexus (identified by --param-rk=RK). If a new
139 reservation is established as a result of the preemption then
140 the supplied --prout-type=TYPE is used as the type for this new
141 reservation.
142 -A, --preempt-abort
144 Preempt and Abort is a sub-command of the PROUT command. Pre‐
145 empts the existing persistent reservation (identified by
146 --param-sark=SARK) with the registration key that is registered
147 for this I_T_L nexus (identified by --param-rk=RK). If a new
148 reservation is established as a result of the preemption then
149 the supplied --prout-type=TYPE is used as the type for this new
150 reservation. ACA and other pending tasks are aborted.
151 -T, --prout-type=TYPE
153 specify the PROUT command's 'type' argument. Required by the
154 'register-move', 'reserve', 'release' and 'preempt (and abort)'
155 sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclu‐
156 sive access, 5-> write exclusive - registrants only, 6-> exclu‐
157 sive access - registrants only, 7-> write exclusive - all regis‐
158 trants, 8-> exclusive access - all registrants. Default value is
159 0 (which is an invalid type). Each "persistent reservation type"
160 is explained in more detail in a subsection of that name in the
161 read reservation section of the PRIN command (section 6.15.3.3
162 of SPC-4 revision 37).
163 -s, --read-full-status
165 Read Full Status is a sub-command of the PRIN command. For each
166 registration with the given SCSI device, it lists the reserva‐
167 tion key and associated information. TransportIDs, if supplied
168 in the response, are decoded.
169 -k, --read-keys
171 Read Keys is a sub-command of the PRIN command. Lists all the
172 reservation keys registered (i.e. registrations) with the given
173 SCSI device. This is the default sub-command for the SCSI PRIN
174 command.
175 -y, --readonly
177 Open DEVICE read-only. May be useful with PRIN commands if there
178 are unwanted side effects with the default read-write open. When
179 given twice is interpreted as forcing a read-write open thus
180 overriding the SG_PERSIST_IN_RDONLY environment variable if
181 present.
182 -r, --read-reservation
184 Read Reservation is a sub-command of the PRIN command. List
185 information about the current holder of the reservation on the
186 DEVICE. If there is no current reservation this will be noted.
187 Information about the current holder of the reservation includes
188 its reservation key, scope and type.
189 -s, --read-status
191 same as --read-full-status.
192 -G, --register
194 Register is a sub-command of the PROUT command. It has 3 differ‐
195 ent actions depending on associated parameters. a) add a new
196 registration with '--param-rk=0' and '--param-sark=<new_rk>'; b)
197 Change an existing registration with '--param-rk=<old_rk>' and
198 '--param-sark=<new_rk>'; or c) Delete an existing registration
199 with '--param-rk=<old_rk>' and '--param-sark=0'.
200 -I, --register-ignore
202 Register and Ignore Existing Key is a sub-command of the PROUT
203 command. Similar to --register except that when changing a
204 reservation key the old key is not specified. The
205 '--param-sark=<new_rk>' option should also be given.
206 -M, --register-move
208 register (another initiator) and move (the reservation held by
209 the current initiator to that other initiator) is a sub-command
210 of the PROUT command. It requires the transportID of the other
211 initiator. [The standard uses the term I_T nexus but the point
212 to stress is that there are two initiators (the one sending this
213 command and another one) but only one logical unit.] The
214 --prout-type=TYPE and --param-rk=RK options need to match that
215 of the existing reservation while --param-sark=SARK option spec‐
216 ifies the reservation key of the new (i.e. destination) regis‐
217 tration.
218 -Q, --relative-target-port=RTPI
220 relative target port identifier that reservation is to be moved
221 to by PROUT 'register and move' sub-command. RTPI is assumed to
222 be hex in the range 0 to ffff inclusive. Defaults to 0 .
223 -L, --release
225 Release is a sub-command of the PROUT command. It releases the
226 current persistent reservation. The --prout-type=TYPE and
227 --param-rk=RK options, matching the reservation, must also be
228 specified.
229 -z, --replace-lost
231 Replace Lost Reservation is a sub-command of the PROUT command.
232 It "begins a recovery process for the lost persistent reserva‐
233 tion that is managed by application clients". It also stops the
234 device server terminating commands due to a lost persistent
235 reservation. Options should be be '--param-rk=0' (or not given),
236 '--param-sark=<new_rk>' and --prout-type=TYPE.
237 -c, --report-capabilities
239 Report Capabilities is a sub-command of the PRIN command. It
240 lists information about the aspects of persistent reservations
241 that the DEVICE supports.
242 -R, --reserve
244 Reserve is a sub-command of the PROUT command. It creates a new
245 persistent reservation (if permitted). The --prout-type=TYPE and
246 --param-rk=RK options must also be specified.
247 -X, --transport-id=TIDS
249 The TIDS argument can take one of several forms. It can be a
250 comma (or single space) separated list of ASCII hex bytes repre‐
251 senting a single TransportID as defined in SPC-4. They are usu‐
252 ally 24 bytes long apart from in iSCSI. The TIDS argument may be
253 a transport specific form (e.g. "sas,5000c50005b32001" is
254 clearer than and equivalent to the hex byte form:
255 "6,0,0,0,5,0,c5,0,5,b3,20,1"). The TIDS argument may be "-" in
256 which case one or more TransportIDs can be read from stdin. The
257 TIDS argument may be of the form "file=<name>" in which case one
258 or more TransportIDs can be read from a file called <name>. See
259 the "TRANSPORT IDs" section below for more information.
260 -U, --unreg
262 optional when the PROUT register and move sub-command is
263 invoked. If given it will unregister the current initiator (I_T
264 nexus) after the other initiator has been registered and the
265 reservation moved to it. When not given the initiator (I_T
266 nexus) that sent the PROUT command remains registered.
267 -v, --verbose
269 print out cdb of issued commands prior to execution. If used
270 twice prints out the parameter block associated with the PROUT
271 command prior to its execution as well. If used thrice decodes
272 given transportID(s) as well. To see the response to a PRIN com‐
273 mand in low level form use the --hex option.
274 -V, --version
276 print out version string. Ignore all other parameters.
277 -? output usage message. Ignore all other parameters.
279
281 TransportIDs are used in persistent reservations to identify initia‐
282 tors. The format of a TransportID differs depending on the type of
283 transport being used. Their format is described in SPC-4 (in draft
284 revision 37 see section 7.6.4).
285 A TransportID is required for the PROUT 'register and move' sub-command
287 and the PROUT 'register' sub-command can have zero, one or more Trans‐
288 portIDs.
289 When the --transport-id=TIDS option is given then the TIDS argument may
291 be a comma (or single space) separated list of ASCII hex bytes that
292 represent a single TransportID as defined in SPC-4. Alternatively the
293 TIDS argument may be a transport specific string starting with either
294 "fcp,", "spi,", "sbp,", "srp,", "iqn", "sas," or "sop,". The "iqn" form
295 is an iSCSI qualified name. Apart from "iqn" the other transport spe‐
296 cific leadin string may be given in upper case (e.g. "FCP,").
297 The "fcp," form should be followed by 16 ASCII hex digits that repre‐
299 sent an initiator's N_PORT_NAME (e.g. "fcp,10000000C9F3A571"). The
300 "spi," form should be followed by "<scsi_address>,<relative_tar‐
301 get_port_identifier>" (both decimal numbers). The "sbp," form should be
302 followed by 16 ASCII hex digits that represent an initiator's EUI-64
303 name. The "srp," form should be followed by 32 ASCII hex digits that
304 represent an initiator port identifier. The "sas," form should be fol‐
305 lowed by 16 ASCII hex digits that represent an initiator's port SAS
306 address (e.g. "sas,5000c50005b32001"). The "sop," form takes a hex num‐
307 ber that represents a routing id.
308 There are two iSCSI qualified name forms. The shorter form contains the
310 iSCSI name of the initiator port (e.g. "iqn.5886.com.acme.diskar‐
311 rays-sn-a8675309"). The longer form adds the initiator session id (ISID
312 in hex) separated by ",i,0x". For example "iqn.5886.com.acme.diskar‐
313 rays-sn-a8675309,i,0x1234567890ab". On the command line to stop punc‐
314 tuation in an iSCSI name being (mis)-interpreted by the shell, putting
315 the option argument containing the iSCSI name in double quotes is
316 advised. iSCSI names are encoded in UTF-8 so if non (7 bit) ASCII char‐
317 acters appear in the iSCSI name on the command line, there will be dif‐
318 ficulties if they are not encoded in UTF-8. The locale can be changed
319 temporarily by prefixing the command line invocation of sg_persist with
320 "LANG=en_US.utf-8" for example.
321 Alternatively the TIDS argument may specify a file (or pipe) from which
323 one or more TransportIDs may be read. If the TIDS argument is "-" then
324 stdin (standard input) is read. If the TIDS argument is of the form
325 "file=<name>" than a file called <name> is read. A valid SPC-4 Trans‐
326 portID is built from the transport specific string outlined in the pre‐
327 vious paragraphs. The parsing of the data read is relatively simple.
328 Empty lines are ignored. Everything from and including a "#" on a line
329 is ignored. Leading spaces and tabs are ignored. There can be one
330 transportID per line. The transportID can either be a comma, space or
331 tab separated list of ASCII hex bytes that represent a TransportID as
332 defined in SPC-4. Padding with zero bytes to a minimum length of 24
333 bytes is performed if necessary. The transportID may also be transport
334 specific string type discussed above.
335 In SPC-3 the SPEC_I_PT bit set to one and TransportIDs were allowed for
337 the PROUT register and ignore existing key sub-command. In SPC-4 that
338 is disallowed yielding a CHECK CONDITION status with and ILLEGAL
339 REQUEST sense key and an additional sense code set to INVALID FIELD IN
340 PARAMETER LIST.
341
343 Currently there is one recognised environment variable: SG_PER‐
344 SIST_IN_RDONLY. If present and only if a PRIN command has been
345 selected then the given DEVICE is opened read-only (e.g. in Unix that
346 is with the O_RDONLY flag). See the --readonly option.
347
349 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
350 (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc,
351 /dev/st1m or /dev/sg3) can be specified. For example "sg_persist
352 --read-keys /dev/sdb" will work in the 2.6 series kernels.
353 The only scope for PROUT commands supported in the current draft of
355 SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an
356 option to set scope to another value.
357 Most errors with the PROUT sub-commands (e.g. missing or mismatched
359 --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This
360 can be a bit confusing when you know there is only one (active) initia‐
361 tor: the "conflict" is with the SPC standard, not another initiator.
362 Some recent disks accept some PRIN and PROUT sub-commands when the
364 media is stopped. One exception was setting the APTPL flag (with the
365 --param-aptpl option) during a key register operation, it complained if
366 the disk one stopped. The error indicated it wanted the disk spun up
367 and when that happened, the registration was successful.
368
370 These examples use Linux device names. For suitable device names in
371 other supported Operating Systems see the sg3_utils(8) man page.
372 Due to the various option defaults the simplest example executes the
374 'read keys' sub-command of the PRIN command:
375 sg_persist /dev/sdb
377 This is the same as the following (long-winded) command:
379 sg_persist --in --read-keys --device=/dev/sdb
381 To read the current reservation either the '--read-reservation' form or
383 the shorter '-r' can be used:
384 sg_persist -r /dev/sdb
386 To register the new reservation key 0x123abc the following could be
388 used:
389 sg_persist --out --register --param-sark=123abc /dev/sdb
391 Given the above registration succeeds, to reserve the DEVICE (with type
393 'write exclusive') the following could be used:
394 sg_persist --out --reserve --param-rk=123abc
396 --prout-type=1 /dev/sdb
397 To release the reservation the following can be given (note that the
399 --param-rk and --prout-type arguments must match those of the reserva‐
400 tion):
401 sg_persist --out --release --param-rk=123abc
403 --prout-type=1 /dev/sdb
404 Finally to unregister a reservation key (and not effect other registra‐
406 tions which is what '--clear' would do) the command is a little sur‐
407 prising:
408 sg_persist --out --register --param-rk=123abc /dev/sdb
410 Now have a close look at the difference between the register and unreg‐
412 ister examples above.
413 An example file that is suitably formatted to pass transportIDs via a
415 '--transport-id=file=transport_ids.txt' option can be found in the
416 examples sub-directory of the sg3_utils package. There is also a simple
417 test script called sg_persist_tst.sh in the same directory.
418 The above sequence of commands was tested successfully on a Seagate
420 Savvio 10K.3 disk and a 1200 SSD both of which have SAS interfaces.
421
423 The exit status of sg_persist is 0 when it is successful. Otherwise see
424 the sg3_utils(8) man page.
425
427 Written by Douglas Gilbert
428
430 Report bugs to <dgilbert at interlog dot com>.
431
433 Copyright © 2004-2014 Douglas Gilbert
434 This software is distributed under the GPL version 2. There is NO war‐
435 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
436 POSE.
437
439 sg3_utils(sg3_utils), scsires(internet)
440sg3_utils-1.40 October 2014 SG_PERSIST(8)