11
11
This utility allows Persistent reservations and registrations to be
12
12
queried and changed. Persistent reservations and registrations are
13
queried by sub-commands ("service actions" in SPC-3) of the Persistent
14
Reservation In (PRIN) SCSI command. Persistent reservations and
15
registrations are changed by sub-commands of the Persistent Reservation
13
queried by sub-commands (called "service actions" in SPC-4) of the Persistent
14
Reserve In (PRIN) SCSI command. Persistent reservations and
15
registrations are changed by sub-commands of the Persistent Reserve
16
16
Out (PROUT) SCSI command.
18
There is a two stage process to obtain a persistent reservation. First an
19
application (an I_T nexus in standard's jargon) must register a reservation
20
key. If that is accepted (and it should be unless some other I_T nexus has
21
registered that key) then the application can try and reserve
22
the device. The reserve operation must specify the reservation
23
key and a "type" (see the '--prout-type=' option).
18
25
It is relatively safe to query the state of Persistent reservations and
19
26
registrations. With no options this utility defaults to the READ KEYS
20
27
sub-command of the PRIN command. Other PRIN sub-commands are
23
30
Before trying to change Persistent reservations and registrations users
24
31
should be aware of what they are doing! The relevant sections of the
25
SCSI Primary Commands document (SPC-3 most recent draft revision 20
26
dated 31st July 2004) are sections 5.6 (general information), 6.11 (for
27
PRIN) and 6.12 (for PROUT). To safeguard against accidental use
28
the '--out' option together with a PROUT sub-command (e.g. '--register')
32
SCSI Primary Commands document (SPC-4 most recent draft revision 5a
33
dated 14th June 2006) are sections 5.6 (general information), 6.11 (for
34
PRIN) and 6.12 (for PROUT). To safeguard against accidental use,
35
the '--out' option must be given when a PROUT sub-command (e.g. '--register')
31
38
The older SCSI Reserve and Release commands (both 6 and 10 byte variants)
32
39
are not supported by this utility. In SPC-3, Reserve and Release are
33
deprecated, replaced by Persistent Reservations. See a utility
40
deprecated, replaced by Persistent Reservations. Reserve and Release
41
have been removed from SPC-4 and Annex B is provided showing how to
42
convert to persistent reservation commands. See a utility
34
43
called 'scsires' for support of the SCSI Reserve and Release commands.
36
45
The <scsi_device> is required by all variants of this utility apart
38
47
argument (typically but not necessarily the last one) or via
39
48
the '--device=<scsi_device>' (or '-d <scsi_device') option.
41
SPC-3 does not use the term "sub-command". It uses the term "service action"
50
SPC-4 does not use the term "sub-command". It uses the term "service action"
42
51
for this and for part of a field's name in the parameter block associated
43
52
with the PROUT command (i.e. "service action reservation key"). To lessen
44
the potential ambiguity the term "sub-command" has been introduced.
53
the potential confusion the term "sub-command" has been introduced.
48
57
Clear is a sub-command of the PROUT command. It releases the
49
58
persistent reservation (if any) and clears all registrations from the
59
device. It is required to supply a reservation key that is registered
60
for this I_T_L nexus (identified by --param-rk).
52
62
--device=<scsi_device> | -d <scsi_device>
53
63
This utility needs to have a scsi_device to be specified. This can either
61
71
the response to a valid PRIN sub-command will be output in hexadecimal.
62
72
Normally if the PRIN sub-command is recognised then the response
63
will be decoded as per SPC-3.
73
will be decoded as per SPC-4.
66
specify that a Persistent Reservation In SCSI command is required. This
76
specify that a Persistent Reserve In SCSI command is required. This
70
specify that a Persistent Reservation Out SCSI command is required.
80
specify that a Persistent Reserve Out SCSI command is required.
73
83
the default action is to do a standard INQUIRY SCSI command and output
88
98
--param-rk=<h> | -K <h>
89
99
specify the reservation key found in the parameter block of the PROUT
90
100
command. Argument is assumed to be hex (up to 8 bytes long). Default value
101
is 0. This option is needed by most PROUT sub-commands.
93
103
--param-sark=<h> | -S <h>
94
104
specify the service action reservation key found in the parameter block
95
105
of the PROUT command. Argument is assumed to be hex (up to 8 bytes long).
106
Default value is 0. This option is needed by some PROUT sub-commands.
99
109
Preempt is a sub-command of the PROUT command. Preempts
100
110
the existing persistent reservation (identified by '--param-sark') with
101
the current I_T_L nexus (identified by '--param-rk').
111
the registration key that is registered for this I_T_L nexus (identified
112
by '--param-rk'). The associated '--prout-type<h>' option needs to match
113
the type of the reservation.
103
115
--preempt-abort | -A
104
116
Preempt and Abort is a sub-command of the PROUT command. Preempts
105
117
the existing persistent reservation (identified by '--param-sark') with
106
the current I_T_L nexus (identified by '--param-rk'). ACA and other
107
pending tasks are aborted.
118
the registration key that is registered for this I_T_L nexus (identified
119
by '--param-rk'). The associated '--prout-type<h>' option needs to match
120
the type of the reservation. ACA and other pending tasks are aborted.
109
122
--prout-type=<h> | -T <h>
110
specify the PROUT command's 'type' argument. Required by the 'reserve'
111
and 'release' sub-commands. Valid arguments: 1-> write exclusive, 3->
123
specify the PROUT command's 'type' argument. Required by
124
the 'register-move', 'reserve', 'release' and 'preempt (and abort)'
125
sub-commands. Valid arguments: 1-> write exclusive, 3->
112
126
exclusive access, 5-> write exclusive - registrants only, 6->
113
127
exclusive access - registrants only, 7-> write exclusive - all registrants,
114
128
8-> exclusive access - all registrants. Default value is 0 (which is
129
an invalid type). Each "persistent reservation type" is explained in more
130
detail in a subsection of that name in the read reservation section of
131
the PRIN command (section 6.11.3.4 of SPC-4 revision 5a).
117
133
--read-full-status | -s
118
134
Read Full Status is a sub-command of the PRIN command. For each registration
119
135
with the given SCSI device, it lists the reservation key and associated
120
information. TransportIDs, if supplied in the reponse, are decoded.
136
information. TransportIDs, if supplied in the response, are decoded.
123
139
Read Keys is a sub-command of the PRIN command. Lists all the reservation
137
153
Register is a sub-command of the PROUT command. It has 3 different
138
actions depending on associated parameters. 1) add a new registration
139
with '--param-rk=0' and '--param-sark=<new_rk>'. 2) Change an existing
140
registration with '--param-rk=<old_rk>' and '--param-sark=<new_rk>'.
141
3) Delete an existing registration with '--param-rk=<old_rk>'
142
and '--param-sark=0'.
154
actions depending on associated parameters. a) add a new registration
155
with '--param-rk=0' and '--param-sark=<new_rk>'; b) Change an existing
156
registration with '--param-rk=<old_rk>'
157
and '--param-sark=<new_rk>'; or c) Delete an existing registration
158
with '--param-rk=<old_rk>' and '--param-sark=0'.
144
160
--register-ignore | -I
145
161
Register and Ignore Existing Key is a sub-command of the PROUT command.
146
162
Similar to '--register' except that when changing a reservation key the
147
old key is not specified.
163
old key is not specified. The '--prout-sark=<new_rk>' option should also
149
166
--register-move | -M
150
167
register (another initiator) and move (the reservation held by the current
151
168
initiator to that other initiator) is a sub-command of the PROUT command.
152
It requires the transportID of the other initiator.
169
It requires the transportID of the other initiator. [The standard uses the
170
term I_T nexus but the point to stress is that there are two initiators
171
(the one sending this command and another one) but only one target.]
172
The '--param-type=<h>' and '--param-rk=<h>' options need to match that of
173
the existing reservation while '--param-sark=<h>' option specifies the
174
reservation key of the new (i.e. destination) registration.
154
176
--relative-target-port=<h> | -Q <h>
155
177
relative target port number that reservation is to be moved to by
160
182
Release is a sub-command of the PROUT command. It releases the
161
current persistent reservation. The '--prout-type' must also be specified.
183
current persistent reservation. The '--prout-type=<h>'
184
and '--prout-rk=<h>' options, matching the reservation, must also be
163
187
--report-capabilities | -c
164
188
Report Capabilities is a sub-command of the PRIN command. It lists
169
193
Reserve is a sub-command of the PROUT command. It creates a new
170
persistent reservation (if permitted). The '--prout-type' must also be
194
persistent reservation (if permitted). The '--prout-type=<h>'
195
and '--prout-rk=<h>' options must also be specified.
173
197
--transport-id=<h>,<h>... | -X <h>,<h>...
174
198
a transportID is required for the PROUT 'register and move' sub-command
186
210
and is optional for the PROUT 'register' and 'register and ignore
187
211
existing key' sub-commands. The latter two sub-commands can take multiple
188
212
transportIDs in a list. The argument is '-' which indicates
189
stdin should be read for the transportID(s). Empty lines and those starting
190
with '#' are ignored. Leading spaces and tabs are ignored. All numbers
213
stdin should be read for the transportID(s). Empty lines are ignored.
214
Everything from and including a "#" on a line is ignored.
215
Leading spaces and tabs are ignored. All numbers
191
216
are assumed to be hexadecimal and can be separated by space, comma or
192
217
tab. There can be one transportID per line. TranportIDs will be padded
193
218
out with zeroes to 24 bytes which is the minimum length of a
220
245
will work in the 2.6 series kernels.
222
247
The only scope for PROUT commands supported in the current draft of
223
SPC-3 is "LU_SCOPE". Hence there seems to be no point in offering an
248
SPC-4 is "LU_SCOPE". Hence there seems to be no point in offering an
224
249
option to set scope to another value.
251
Most errors with the PROUT sub-commands (e.g. missing or
252
mismatched '--prout-type=<h>' option) will result in a RESERVATION
253
CONFLICT status. This can be a bit confusing when you know there is
254
only one (active) initiator: the "conflict" is with the SPC standard, not
227
258
Due to defaults the simplest example executes the 'read keys' sub-command
239
270
sg_persist -r /dev/sda
241
To register the new reservation key 0x123abc the following could be used:
243
sg_persist --out --register --param-rk=0
245
--param-sark=123abc /dev/sda
247
Given the above registration succeeds, a reservation (of type 'write
248
exclusive') may be obtained with:
274
the new reservation key 0x123abc the following could be used:
276
sg_persist --out --register --param-sark=123abc /dev/sda
278
Given the above registration succeeds, to
280
the given device (with type 'write exclusive') the following
250
283
sg_persist --out --reserve --param-rk=123abc
252
285
--prout-type=1 /dev/sda
289
the reservation the following can be given (note that
290
the --param-rk and --prout-type arguments must match those of the
293
sg_persist --out --release --param-rk=123abc
295
--prout-type=1 /dev/sda
299
a reservation key (and not effect other
300
registrations which is what '--clear' would do) the command
301
is a little surprising:
303
sg_persist --out --register --param-rk=123abc /dev/sda
305
Now have a close look at the difference between the register and
306
unregister examples above.
254
308
An example file that is suitably formatted to pass transportIDs via
255
309
the '-transport-id=-' option can be found in the examples sub-directory
256
310
of the sg3_utils package. That file is called 'transport_ids.txt'.
312
The exit status of sg_persist is 0 when it is successful. Otherwise see
313
the sg3_utils(8) man page.
258
315
Written by Doug Gilbert
259
316
.SH "REPORTING BUGS"
260
317
Report bugs to <dgilbert at interlog dot com>.
262
Copyright \(co 2004 Douglas Gilbert
319
Copyright \(co 2004-2006 Douglas Gilbert
264
321
This software is distributed under the GPL version 2. There is NO
265
322
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
324
.B scsires(internet), examples/sg_persist_tst.sh(sg3_utils tarball)
added
removed
sg_persist.8
