1SG_PERSIST(8) SG3_UTILS SG_PERSIST(8)
2
6 sg_persist - sends a SCSI PERSISTENT RESERVE (IN or OUT) command to
7 manipulate registrations 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 20 dated 22 May 2009) are sections 5.7 (titled "Reserva‐
40 tions"), 6.13 (for the PRIN command) and 6.14 (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.
89 -H, --hex
91 the response to a valid PRIN sub-command will be output in hexa‐
92 decimal. By default (i.e. without this option) if the PRIN
93 sub-command is recognised then the response will be decoded as
94 per SPC-4.
95 -i, --in
97 specify that a SCSI PERSISTENT RESERVE IN command is required.
98 This is the default.
99 -n, --no-inquiry
101 the default action is to do a standard SCSI INQUIRY command and
102 output make, product and revision strings plus the peripheral
103 device type prior to executing a PRIN or PROUT command. With
104 this option the INQUIRY command is skipped.
105 -o, --out
107 specify that a SCSI PERSISTENT RESERVE OUT command is required.
108 -Y, --param-alltgpt
110 set the 'all target ports' (ALL_TG_PT) flag in the parameter
111 block of the PROUT command. Only relevant for 'register' and
112 'register and ignore existing key' sub-commands.
113 -Z, --param-aptpl
115 set the 'activate persist through power loss' (APTPL) flag in
116 the parameter block of the PROUT command. Relevant for 'regis‐
117 ter', 'register and ignore existing key' and 'register and move'
118 sub-commands.
119 -K, --param-rk=RK
121 specify the reservation key found in the parameter block of the
122 PROUT command. RK is assumed to be hex (up to 8 bytes long).
123 Default value is 0. This option is needed by most PROUT sub-com‐
124 mands.
125 -S, --param-sark=SARK
127 specify the service action reservation key found in the parame‐
128 ter block of the PROUT command. SARK is assumed to be hex (up to
129 8 bytes long). Default value is 0. This option is needed by
130 some PROUT sub-commands.
131 -P, --preempt
133 Preempt is a sub-command of the PROUT command. Preempts the
134 existing persistent reservation (identified by
135 --param-sark=SARK) with the registration key that is registered
136 for this I_T_L nexus (identified by --param-rk=RK). The associ‐
137 ated --prout-type=TYPE option needs to match the type of the
138 reservation.
139 -A, --preempt-abort
141 Preempt and Abort is a sub-command of the PROUT command. Pre‐
142 empts the existing persistent reservation (identified by
143 --param-sark=SARK) with the registration key that is registered
144 for this I_T_L nexus (identified by --param-rk=RK). The associ‐
145 ated --prout-type=TYPE option needs to match the type of the
146 reservation. ACA and other pending tasks are aborted.
147 -T, --prout-type=TYPE
149 specify the PROUT command's 'type' argument. Required by the
150 'register-move', 'reserve', 'release' and 'preempt (and abort)'
151 sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclu‐
152 sive access, 5-> write exclusive - registrants only, 6-> exclu‐
153 sive access - registrants only, 7-> write exclusive - all regis‐
154 trants, 8-> exclusive access - all registrants. Default value is
155 0 (which is an invalid type). Each "persistent reservation type"
156 is explained in more detail in a subsection of that name in the
157 read reservation section of the PRIN command (section 6.13.3.4
158 of SPC-4 revision 9).
159 -s, --read-full-status
161 Read Full Status is a sub-command of the PRIN command. For each
162 registration with the given SCSI device, it lists the reserva‐
163 tion key and associated information. TransportIDs, if supplied
164 in the response, are decoded.
165 -k, --read-keys
167 Read Keys is a sub-command of the PRIN command. Lists all the
168 reservation keys registered (i.e. registrations) with the given
169 SCSI device. This is the default sub-command for the SCSI PRIN
170 command.
171 -r, --read-reservation
173 Read Reservation is a sub-command of the PRIN command. List
174 information about the current holder of the reservation on the
175 DEVICE. If there is no current reservation this will be noted.
176 Information about the current holder of the reservation includes
177 its reservation key, scope and type.
178 -s, --read-status
180 same as --read-full-status.
181 -G, --register
183 Register is a sub-command of the PROUT command. It has 3 differ‐
184 ent actions depending on associated parameters. a) add a new
185 registration with '--param-rk=0' and '--param-sark=<new_rk>'; b)
186 Change an existing registration with '--param-rk=<old_rk>' and
187 '--param-sark=<new_rk>'; or c) Delete an existing registration
188 with '--param-rk=<old_rk>' and '--param-sark=0'.
189 -I, --register-ignore
191 Register and Ignore Existing Key is a sub-command of the PROUT
192 command. Similar to --register except that when changing a
193 reservation key the old key is not specified. The
194 '--param-sark=<new_rk>' option should also be given.
195 -M, --register-move
197 register (another initiator) and move (the reservation held by
198 the current initiator to that other initiator) is a sub-command
199 of the PROUT command. It requires the transportID of the other
200 initiator. [The standard uses the term I_T nexus but the point
201 to stress is that there are two initiators (the one sending this
202 command and another one) but only one logical unit.] The
203 --prout-type=TYPE and --param-rk=RK options need to match that
204 of the existing reservation while --param-sark=SARK option spec‐
205 ifies the reservation key of the new (i.e. destination) regis‐
206 tration.
207 -Q, --relative-target-port=RTPI
209 relative target port identifier that reservation is to be moved
210 to by PROUT 'register and move' sub-command. RTPI is assumed to
211 be hex in the range 0 to ffff inclusive. Defaults to 0 .
212 -L, --release
214 Release is a sub-command of the PROUT command. It releases the
215 current persistent reservation. The --prout-type=TYPE and
216 --param-rk=RK options, matching the reservation, must also be
217 specified.
218 -c, --report-capabilities
220 Report Capabilities is a sub-command of the PRIN command. It
221 lists information about the aspects of persistent reservations
222 that the DEVICE supports.
223 -R, --reserve
225 Reserve is a sub-command of the PROUT command. It creates a new
226 persistent reservation (if permitted). The --prout-type=TYPE and
227 --param-rk=RK options must also be specified.
228 -X, --transport-id=TIDS
230 The TIDS argument can take one of several forms. It can be a
231 comma (or single space) separated list of ASCII hex bytes repre‐
232 senting a single TransportID as defined in SPC-4. They are usu‐
233 ally 24 bytes long apart from in iSCSI. The TIDS argument may be
234 a transport specific form (e.g. "sas,5000c50005b32001"). The
235 TIDS argument may be "-" in which case one or more TransportIDs
236 can be read from stdin. The TIDS argument may be of the form
237 "file=<name>" in which case one or more TransportIDs can be read
238 from a file called <name>. See the "TRANSPORT IDs" section below
239 for more information.
240 -U, --unreg
242 optional when the PROUT register and move sub-command is
243 invoked. If given it will unregister the current initiator (I_T
244 nexus) after the other initiator has been registered and the
245 reservation moved to it. When not given the initiator (I_T
246 nexus) that sent the PROUT command remains registered.
247 -v, --verbose
249 print out cdb of issued commands prior to execution. If used
250 twice prints out the parameter block associated with the PROUT
251 command prior to its execution as well. If used thrice decodes
252 given transportID(s) as well. To see the response to a PRIN com‐
253 mand in low level form use the --hex option.
254 -V, --version
256 print out version string. Ignore all other parameters.
257 -? output usage message. Ignore all other parameters.
259
261 TransportIDs are used in persistent reservations to identify initia‐
262 tors. The format of a TransportID differs depending on the type of
263 transport being used. Their format is described in SPC-4 (in draft
264 revision 20 see section 7.5.4).
265 A TransportID is required for the PROUT 'register and move' sub-command
267 and the PROUT 'register' sub-command can have zero, one or more Trans‐
268 portIDs.
269 When the --transport-id=TIDS option is given then the TIDS argument may
271 be a comma (or single space) separated list of ASCII hex bytes that
272 represent a single TransportID as defined in SPC-4. Alternatively the
273 TIDS argument may be a transport specific string starting with either
274 "fcp,", "spi,", "sbp,", "srp,", "iqn", or "sas,". The "iqn" form is an
275 iSCSI qualified name. Apart from "iqn" the other transport specific
276 leadin string may be given in upper case (e.g. "FCP,").
277 The "fcp," form should be followed by 16 ASCII hex digits that repre‐
279 sent an initiator's N_PORT_NAME. The "spi," form should be followed by
280 "<scsi_address>,<relative_target_port_identifier>" (both decimal num‐
281 bers). The "sbp," form should be followed by 16 ASCII hex digits that
282 represent an initiator's EUI-64 name. The "srp," form should be fol‐
283 lowed by 32 ASCII hex digits that represent an initiator port identi‐
284 fier. The "sas," form should be followed by 16 ASCII hex digits that
285 represent an initiator's port SAS address.
286 There are two iSCSI qualified name forms. The shorter form contains the
288 iSCSI name of the initiator port (e.g. "iqn.5886.com.acme.diskarrays-
289 sn-a8675309"). The longer form adds the initiator session id (ISID in
290 hex) separated by ",i,0x". For example "iqn.5886.com.acme.diskarrays-
291 sn-a8675309,i,0x1234567890ab". On the command line to stop punctuation
292 in an iSCSI name being (mis)- interpreted by the shell, putting the
293 option argument containing the iSCSI name in double quotes is advised.
294 iSCSI names are encoded in UTF-8 so if non (7 bit) ASCII characters
295 appear in the iSCSI name on the command line, there will be difficul‐
296 ties if they are not encoded in UTF-8. The locale can be changed tempo‐
297 rarily by prefixing the command line invocation of sg_persist with
298 "LANG=en_US.utf-8" for example.
299 Alternatively the TIDS argument may specify a file (or pipe) from which
301 one or more TransportIDs may be read. If the TIDS argument is "-" then
302 stdin (standard input) is read. If the TIDS argument is of the form
303 "file=<name>" than a file called <name> is read. A valid SPC-4 Trans‐
304 portID is built from the transport specific string outlined in the pre‐
305 vious paragraphs. The parsing of the data read is realtively simple.
306 Empty lines are ignored. Everything from and including a "#" on a line
307 is ignored. Leading spaces and tabs are ignored. There can be one
308 transportID per line. The transportID can either be a comma, space or
309 tab separated list of ASCII hex bytes that represent a TransportID as
310 defined in SPC-4. Padding with zero bytes to a minimum length of 24
311 bytes is performed if necessary. The transportID may also be transport
312 specific string type discussed above.
313 In SPC-3 the SPEC_I_PT bit set to one and TransportIDs were allowed for
315 the PROUT register and ignore existing key sub-command. In SPC-4 that
316 is disallowed yielding a CHECK CONDITION status with and ILLEGAL
317 REQUEST sense key and an additional sense code set to INVALID FIELD IN
318 PARAMETER LIST.
319
321 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
322 (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc,
323 /dev/st1m or /dev/sg3) can be specified. For example "sg_persist
324 --read-keys /dev/sdb" will work in the 2.6 series kernels.
325 The only scope for PROUT commands supported in the current draft of
327 SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an
328 option to set scope to another value.
329 Most errors with the PROUT sub-commands (e.g. missing or mismatched
331 --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This
332 can be a bit confusing when you know there is only one (active) initia‐
333 tor: the "conflict" is with the SPC standard, not another initiator.
334 Some recent disks accept some PRIN and PROUT sub-commands when the
336 media is stopped. One exception was setting the APTPL flag (with the
337 --param-aptpl option) during a key register operation, it complained if
338 the disk one stopped. The error indicated it wanted the disk spun up
339 and when that happened, the registration was successful.
340
342 Due to the various option defaults the simplest example executes the
343 'read keys' sub-command of the PRIN command:
344 sg_persist /dev/sdb
346 This is the same as the following (long-winded) command:
348 sg_persist --in --read-keys --device=/dev/sdb
350 To read the current reservation either the '--read-reservation' form or
352 the shorter '-r' can be used:
353 sg_persist -r /dev/sdb
355 To register the new reservation key 0x123abc the following could be
357 used:
358 sg_persist --out --register --param-sark=123abc /dev/sdb
360 Given the above registration succeeds, to reserve the DEVICE (with type
362 'write exclusive') the following could be used:
363 sg_persist --out --reserve --param-rk=123abc
365 --prout-type=1 /dev/sdb
366 To release the reservation the following can be given (note that the
368 --param-rk and --prout-type arguments must match those of the reserva‐
369 tion):
370 sg_persist --out --release --param-rk=123abc
372 --prout-type=1 /dev/sdb
373 Finally to unregister a reservation key (and not effect other registra‐
375 tions which is what '--clear' would do) the command is a little sur‐
376 prising:
377 sg_persist --out --register --param-rk=123abc /dev/sdb
379 Now have a close look at the difference between the register and unreg‐
381 ister examples above.
382 An example file that is suitably formatted to pass transportIDs via a
384 '--transport-id=file=transport_ids.txt' option can be found in the
385 examples sub-directory of the sg3_utils package. There is also a simple
386 test script called sg_persist_tst.sh in the same directory.
387 The above sequence of commands was tested successfully on a Seagate
389 Savvio 10K.3 disk which has a SAS interface.
390
392 The exit status of sg_persist is 0 when it is successful. Otherwise see
393 the sg3_utils(8) man page.
394
396 Written by Doug Gilbert
397
399 Report bugs to <dgilbert at interlog dot com>.
400
402 Copyright © 2004-2009 Douglas Gilbert
403 This software is distributed under the GPL version 2. There is NO war‐
404 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
405 POSE.
406
408 scsires(internet)
409sg3_utils-1.29 December 2009 SG_PERSIST(8)