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
13 This utility allows Persistent reservations and registrations to be
14 queried and changed. Persistent reservations and registrations are
15 queried by sub-commands (called "service actions" in SPC-4) of the SCSI
16 PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and reg‐
17 istrations are changed by sub-commands of the SCSI PERSISTENT RESERVE
18 OUT (PROUT) command.
19 There is a two stage process to obtain a persistent reservation. First
21 an application (an I_T nexus in standard's jargon) must register a
22 reservation key. If that is accepted (and it should be unless some
23 other I_T nexus has registered that key) then the application can try
24 and reserve the device. The reserve operation must specify the reser‐
25 vation key and a "type" (see the --prout-type=TYPE option).
26 It is relatively safe to query the state of Persistent reservations and
28 registrations. With no options this utility defaults to the READ KEYS
29 sub-command of the PRIN command. Other PRIN sub-commands are READ
30 RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.
31 Before trying to change Persistent reservations and registrations users
33 should be aware of what they are doing! The relevant sections of the
34 SCSI Primary Commands document (SPC-4 most recent draft revision 5a
35 dated 14th June 2006) are sections 5.6 (general information), 6.11 (for
36 PRIN) and 6.12 (for PROUT). To safeguard against accidental use, the
37 --out option must be given when a PROUT sub-command (e.g. --register)
38 is used.
39 The older SCSI RESERVE and RELEASE commands (both 6 and 10 byte vari‐
41 ants) are not supported by this utility. In SPC-3, RESERVE and RELEASE
42 are deprecated, replaced by Persistent Reservations. RESERVE and
43 RELEASE have been removed from SPC-4 and Annex B is provided showing
44 how to convert to persistent reservation commands. See a utility called
45 'scsires' for support of the SCSI RESERVE and RELEASE commands.
46 The DEVICE is required by all variants of this utility apart from
48 --help. The DEVICE can be given either as an argument (typically but
49 not necessarily the last one) or via the --device=DEVICE option.
50 SPC-4 does not use the term "sub-command". It uses the term "service
52 action" for this and for part of a field's name in the parameter block
53 associated with the PROUT command (i.e. "service action reservation
54 key"). To lessen the potential confusion the term "sub-command" has
55 been introduced.
56
58 Arguments to long options are mandatory for short options as well.
59 -C, --clear
61 Clear is a sub-command of the PROUT command. It releases the
62 persistent reservation (if any) and clears all registrations
63 from the device. It is required to supply a reservation key that
64 is registered for this I_T_L nexus (identified by
65 --param-rk=RK).
66 -d, --device=DEVICE
68 DEVICE to send SCSI commands to. The DEVICE can either be pro‐
69 vided via this option or via a freestanding argument. For exam‐
70 ple, these two: 'sg_persist --device=/dev/sg2' and 'sg_persist
71 /dev/sg2' are equivalent.
72 -h, --help
74 output a usage message.
75 -H, --hex
77 the response to a valid PRIN sub-command will be output in hexa‐
78 decimal. Normally if the PRIN sub-command is recognised then
79 the response will be decoded as per SPC-4.
80 -i, --in
82 specify that a SCSI PERSISTENT RESERVE IN command is required.
83 This is the default.
84 -n, --no-inquiry
86 the default action is to do a standard SCSI INQUIRY command and
87 output make, product and revision strings plus the peripheral
88 device type prior to executing a PR In or Out command. With this
89 option the INQUIRY command is skipped.
90 -o, --out
92 specify that a SCSI PERSISTENT RESERVE OUT command is required.
93 -Y, --param-alltgpt
95 set the 'all target ports' (ALL_TG_PT) flag in the parameter
96 block of the PROUT command. Only relevant for 'register' and
97 'register and ignore existing key' sub-commands.
98 -Z, --param-aptpl
100 set the 'activate persist through power loss' (APTPL) flag in
101 the parameter block of the PROUT command. Relevant for 'regis‐
102 ter', 'register and ignore existing key' and 'register and move'
103 sub-commands.
104 -K, --param-rk=RK
106 specify the reservation key found in the parameter block of the
107 PROUT command. RK is assumed to be hex (up to 8 bytes long).
108 Default value is 0. This option is needed by most PROUT sub-com‐
109 mands.
110 -S, --param-sark=SARK
112 specify the service action reservation key found in the parame‐
113 ter block of the PROUT command. SARK is assumed to be hex (up to
114 8 bytes long). Default value is 0. This option is needed by
115 some PROUT sub-commands.
116 -P, --preempt
118 Preempt is a sub-command of the PROUT command. Preempts the
119 existing persistent reservation (identified by
120 --param-sark=SARK) with the registration key that is registered
121 for this I_T_L nexus (identified by --param-rk=RK). The associ‐
122 ated --prout-type=TYPE option needs to match the type of the
123 reservation.
124 -A, --preempt-abort
126 Preempt and Abort is a sub-command of the PROUT command. Pre‐
127 empts the existing persistent reservation (identified by
128 --param-sark=SARK) with the registration key that is registered
129 for this I_T_L nexus (identified by --param-rk=RK). The associ‐
130 ated --prout-type=TYPE option needs to match the type of the
131 reservation. ACA and other pending tasks are aborted.
132 -T, --prout-type=TYPE
134 specify the PROUT command's 'type' argument. Required by the
135 'register-move', 'reserve', 'release' and 'preempt (and abort)'
136 sub-commands. Valid TYPE values: 1-> write exclusive, 3-> exclu‐
137 sive access, 5-> write exclusive - registrants only, 6-> exclu‐
138 sive access - registrants only, 7-> write exclusive - all regis‐
139 trants, 8-> exclusive access - all registrants. Default value is
140 0 (which is an invalid type). Each "persistent reservation type"
141 is explained in more detail in a subsection of that name in the
142 read reservation section of the PRIN command (section 6.11.3.4
143 of SPC-4 revision 5a).
144 -s, --read-full-status
146 Read Full Status is a sub-command of the PRIN command. For each
147 registration with the given SCSI device, it lists the reserva‐
148 tion key and associated information. TransportIDs, if supplied
149 in the response, are decoded.
150 -k, --read-keys
152 Read Keys is a sub-command of the PRIN command. Lists all the
153 reservation keys registered (i.e. registrations) with the given
154 SCSI device. This is the default sub-command for the SCSI PRIN
155 command.
156 -r, --read-reservation
158 Read Reservation is a sub-command of the PRIN command. List
159 information about the current holder of the reservation on the
160 DEVICE. If there is no current reservation this will be noted.
161 Information about the current holder of the reservation includes
162 its reservation key, scope and type.
163 -s, --read-status
165 same as --read-full-status.
166 -G, --register
168 Register is a sub-command of the PROUT command. It has 3 differ‐
169 ent actions depending on associated parameters. a) add a new
170 registration with '--param-rk=0' and '--param-sark=<new_rk>'; b)
171 Change an existing registration with '--param-rk=<old_rk>' and
172 '--param-sark=<new_rk>'; or c) Delete an existing registration
173 with '--param-rk=<old_rk>' and '--param-sark=0'.
174 -I, --register-ignore
176 Register and Ignore Existing Key is a sub-command of the PROUT
177 command. Similar to --register except that when changing a
178 reservation key the old key is not specified. The '--prout-
179 sark=<new_rk>' option should also be given.
180 -M, --register-move
182 register (another initiator) and move (the reservation held by
183 the current initiator to that other initiator) is a sub-command
184 of the PROUT command. It requires the transportID of the other
185 initiator. [The standard uses the term I_T nexus but the point
186 to stress is that there are two initiators (the one sending this
187 command and another one) but only one logical unit.] The
188 --prout-type=TYPE and --param-rk=RK options need to match that
189 of the existing reservation while --param-sark=SARK option spec‐
190 ifies the reservation key of the new (i.e. destination) regis‐
191 tration.
192 -Q, --relative-target-port=RTPI
194 relative target port identifier that reservation is to be moved
195 to by PROUT 'register and move' sub-command. RTPI is assumed to
196 be hex in the range 0 to ffff inclusive. Defaults to 0 .
197 -L, --release
199 Release is a sub-command of the PROUT command. It releases the
200 current persistent reservation. The --prout-type=TYPE and
201 --param-rk=RK options, matching the reservation, must also be
202 specified.
203 -c, --report/-capabilities
205 Report Capabilities is a sub-command of the PRIN command. It
206 lists information about the aspects of persistent reservations
207 that the DEVICE supports.
208 -R, --reserve
210 Reserve is a sub-command of the PROUT command. It creates a new
211 persistent reservation (if permitted). The --prout-type=TYPE and
212 --param-rk=RK options must also be specified.
213 -X, --transport-id=H,H...
215 a transportID is required for the PROUT 'register and move'
216 sub-command and is optional for the PROUT 'register' and 'regis‐
217 ter and ignore existing key' sub-commands. The latter two
218 sub-commands can take multiple transportIDs in a list but only
219 one is supported on the command line. H,H... is a comma sepa‐
220 rated list of hex numbers representing the bytes of the trans‐
221 portID. The list of hex numbers will be padded out with zeros to
222 24 bytes which is the minimum length of a transportID. A trans‐
223 portID longer than 24 bytes (e.g. for iSCSI) is padded with
224 zeros so its length is a multiple of 4.
225 -X, --transport-id=-
227 a transportID is required for the PROUT 'register and move'
228 sub-command and is optional for the PROUT 'register' and 'regis‐
229 ter and ignore existing key' sub-commands. The latter two
230 sub-commands can take multiple transportIDs in a list. The argu‐
231 ment is '-' which indicates stdin should be read for the trans‐
232 portID(s). Empty lines are ignored. Everything from and includ‐
233 ing a "#" on a line is ignored. Leading spaces and tabs are
234 ignored. All numbers are assumed to be hexadecimal and can be
235 separated by space, comma or tab. There can be one transportID
236 per line. TranportIDs will be padded out with zeros to 24 bytes
237 which is the minimum length of a transportID. A transportID
238 longer than 24 bytes (e.g. for iSCSI) is padded with zeros so
239 its length is a multiple of 4.
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 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
262 (sg) device. In the 2.6 series any SCSI device name (e.g. /dev/sdc,
263 /dev/st1m or /dev/sg3) can be specified. For example "sg_persist
264 --read-keys /dev/sda" will work in the 2.6 series kernels.
265 The only scope for PROUT commands supported in the current draft of
267 SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an
268 option to set scope to another value.
269 Most errors with the PROUT sub-commands (e.g. missing or mismatched
271 --prout-type=TYPE) will result in a RESERVATION CONFLICT status. This
272 can be a bit confusing when you know there is only one (active) initia‐
273 tor: the "conflict" is with the SPC standard, not another initiator.
274
276 Due to defaults the simplest example executes the 'read keys' sub-com‐
277 mand of the PRIN command:
278 sg_persist /dev/sda
280 This is the same as the following (long-winded) command:
282 sg_persist --in --read-keys --device=/dev/sda
284 To read the current reservation either the '--read-reservation' form or
286 the shorter '-r' can be used:
287 sg_persist -r /dev/sda
289 To register the new reservation key 0x123abc the following could be
291 used:
292 sg_persist --out --register --param-sark=123abc /dev/sda
294 Given the above registration succeeds, to reserve the DEVICE (with type
296 'write exclusive') the following could be used:
297 sg_persist --out --reserve --param-rk=123abc
299 --prout-type=1 /dev/sda
300 To release the reservation the following can be given (note that the
302 --param-rk and --prout-type arguments must match those of the reserva‐
303 tion):
304 sg_persist --out --release --param-rk=123abc
306 --prout-type=1 /dev/sda
307 Finally to unregister a reservation key (and not effect other registra‐
309 tions which is what '--clear' would do) the command is a little sur‐
310 prising:
311 sg_persist --out --register --param-rk=123abc /dev/sda
313 Now have a close look at the difference between the register and unreg‐
315 ister examples above.
316 An example file that is suitably formatted to pass transportIDs via the
318 '--transport-id=-' option can be found in the examples sub-directory of
319 the sg3_utils package. That file is called 'transport_ids.txt'.
320
322 The exit status of sg_persist is 0 when it is successful. Otherwise see
323 the sg3_utils(8) man page.
324
326 Written by Doug Gilbert
327
329 Report bugs to <dgilbert at interlog dot com>.
330
332 Copyright © 2004-2007 Douglas Gilbert
333 This software is distributed under the GPL version 2. There is NO war‐
334 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
335 POSE.
336
338 scsires(internet), examples/sg_persist_tst.sh(sg3_utils tarball)
339sg3_utils-1.23 January 2007 SG_PERSIST(8)