File: sg_persist.8

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