sg_persist
(1m)
Name
sg_persist - sends a SCSI PERSISTENT RESERVE (IN or OUT)
command to manipulate registrations and reservations
Synopsis
sg_persist [OPTIONS] DEVICE
sg_persist [OPTIONS] --device=DEVICE
sg_persist --help | --version
Description
SG3_UTILS SG_PERSIST(8)
NAME
sg_persist - sends a SCSI PERSISTENT RESERVE (IN or OUT)
command to manipulate registrations and reservations
SYNOPSIS
sg_persist [OPTIONS] DEVICE
sg_persist [OPTIONS] --device=DEVICE
sg_persist --help | --version
DESCRIPTION
This utility allows Persistent reservations and registra-
tions 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.
There is a two stage process to obtain a persistent reserva-
tion. First an application (an I_T nexus in standard's jar-
gon) 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 --prout-type=TYPE option).
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 CAPA-
BILITIES and READ FULL STATUS.
Before trying to change Persistent reservations and regis-
trations users should be aware of what they are doing. The
relevant sections of the SCSI Primary Commands document
(i.e. SPC-4 whose most recent draft is revision 20 dated 22
May 2009) are sections 5.7 (titled "Reservations"), 6.13
(for the PRIN command) and 6.14 (for the PROUT command). To
safeguard against accidental use, the --out option must be
given when a PROUT sub-command (e.g. --register) is used.
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 per-
sistent reservation commands. See a utility called 'scsires'
for support of the SCSI RESERVE and RELEASE commands.
sg3_utils-1.30 Last change: September 2010 1
SG3_UTILS SG_PERSIST(8)
The DEVICE is required by all variants of this utility apart
from --help. The DEVICE can be given either as an argument
(typically but not necessarily the last one) or via the
--device=DEVICE option.
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.
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.
-l, --alloc-length=LEN
specify the allocation length of the PRIN command. LEN
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 LEN values are 0-8192.
-C, --clear
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 --param-rk=RK).
-d, --device=DEVICE
DEVICE to send SCSI commands to. The DEVICE can either
be provided via this option or via a freestanding argu-
ment. For example, these two: 'sg_persist
--device=/dev/sg2' and 'sg_persist /dev/sg2' are equiv-
alent.
-h, --help
output a usage message.
-H, --hex
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.
-i, --in
specify that a SCSI PERSISTENT RESERVE IN command is
required. This is the default.
-n, --no-inquiry
sg3_utils-1.30 Last change: September 2010 2
SG3_UTILS SG_PERSIST(8)
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.
-o, --out
specify that a SCSI PERSISTENT RESERVE OUT command is
required.
-Y, --param-alltgpt
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.
-Z, --param-aptpl
set the 'activate persist through power loss' (APTPL)
flag in the parameter block of the PROUT command. Rele-
vant for 'register', 'register and ignore existing key'
and 'register and move' sub-commands.
-K, --param-rk=RK
specify the reservation key found in the parameter
block of the PROUT command. RK is assumed to be hex (up
to 8 bytes long). Default value is 0. This option is
needed by most PROUT sub-commands.
-S, --param-sark=SARK
specify the service action reservation key found in the
parameter block of the PROUT command. SARK is assumed
to be hex (up to 8 bytes long). Default value is 0.
This option is needed by some PROUT sub-commands.
-P, --preempt
Preempt is a sub-command of the PROUT command. Preempts
the existing persistent reservation (identified by
--param-sark=SARK) with the registration key that is
registered for this I_T_L nexus (identified by
--param-rk=RK). The associated --prout-type=TYPE option
needs to match the type of the reservation.
-A, --preempt-abort
Preempt and Abort is a sub-command of the PROUT com-
mand. Preempts the existing persistent reservation
(identified by --param-sark=SARK) with the registration
key that is registered for this I_T_L nexus (identified
by --param-rk=RK). The associated --prout-type=TYPE
option needs to match the type of the reservation. ACA
and other pending tasks are aborted.
-T, --prout-type=TYPE
sg3_utils-1.30 Last change: September 2010 3
SG3_UTILS SG_PERSIST(8)
specify the PROUT command's 'type' argument. Required
by the 'register-move', 'reserve', 'release' and 'pre-
empt (and abort)' sub-commands. Valid TYPE values: 1->
write exclusive, 3-> exclusive access, 5-> write exclu-
sive - registrants only, 6-> exclusive access - regis-
trants only, 7-> write exclusive - all registrants, 8->
exclusive access - all registrants. Default value is 0
(which is an invalid type). Each "persistent reserva-
tion type" is explained in more detail in a subsection
of that name in the read reservation section of the
PRIN command (section 6.13.3.4 of SPC-4 revision 9).
-s, --read-full-status
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.
-k, --read-keys
Read Keys is a sub-command of the PRIN command. Lists
all the reservation keys registered (i.e. registra-
tions) with the given SCSI device. This is the default
sub-command for the SCSI PRIN command.
-r, --read-reservation
Read Reservation is a sub-command of the PRIN command.
List information about the current holder of the reser-
vation on the DEVICE. If there is no current reserva-
tion this will be noted. Information about the current
holder of the reservation includes its reservation key,
scope and type.
-s, --read-status
same as --read-full-status.
-G, --register
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 regis-
tration with '--param-rk=<old_rk>' and
'--param-sark=<new_rk>'; or c) Delete an existing reg-
istration with '--param-rk=<old_rk>' and
'--param-sark=0'.
-I, --register-ignore
Register and Ignore Existing Key is a sub-command of
the PROUT command. Similar to --register except that
when changing a reservation key the old key is not
specified. The '--param-sark=<new_rk>' option should
also be given.
sg3_utils-1.30 Last change: September 2010 4
SG3_UTILS SG_PERSIST(8)
-M, --register-move
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
--prout-type=TYPE and --param-rk=RK options need to
match that of the existing reservation while
--param-sark=SARK option specifies the reservation key
of the new (i.e. destination) registration.
-Q, --relative-target-port=RTPI
relative target port identifier that reservation is to
be moved to by PROUT 'register and move' sub-command.
RTPI is assumed to be hex in the range 0 to ffff inclu-
sive. Defaults to 0 .
-L, --release
Release is a sub-command of the PROUT command. It
releases the current persistent reservation. The
--prout-type=TYPE and --param-rk=RK options, matching
the reservation, must also be specified.
-c, --report-capabilities
Report Capabilities is a sub-command of the PRIN com-
mand. It lists information about the aspects of persis-
tent reservations that the DEVICE supports.
-R, --reserve
Reserve is a sub-command of the PROUT command. It cre-
ates a new persistent reservation (if permitted). The
--prout-type=TYPE and --param-rk=RK options must also
be specified.
-X, --transport-id=TIDS
The TIDS 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 TIDS argument may be a transport specific
form (e.g. "sas,5000c50005b32001"). The TIDS argument
may be "-" in which case one or more TransportIDs can
be read from stdin. The TIDS argument may be of the
form "file=<name>" in which case one or more Trans-
portIDs can be read from a file called <name>. See the
"TRANSPORT IDs" section below for more information.
-U, --unreg
optional when the PROUT register and move sub-command
is invoked. If given it will unregister the current
sg3_utils-1.30 Last change: September 2010 5
SG3_UTILS SG_PERSIST(8)
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.
-v, --verbose
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 --hex option.
-V, --version
print out version string. Ignore all other parameters.
-? output usage message. Ignore all other parameters.
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 20 see section 7.5.4).
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.
When the --transport-id=TIDS option is given then the TIDS
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 TIDS argument may be a
transport specific string starting with either "fcp,",
"spi,", "sbp,", "srp,", "iqn", or "sas,". The "iqn" form is
an iSCSI qualified name. Apart from "iqn" the other trans-
port specific leadin string may be given in upper case (e.g.
"FCP,").
The "fcp," form should be followed by 16 ASCII hex digits
that represent an initiator's N_PORT_NAME. The "spi," form
should be followed by "<scsi_address>,<relative_tar-
get_port_identifier>" (both decimal numbers). The "sbp,"
form should be followed by 16 ASCII hex digits that repre-
sent 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.
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
sg3_utils-1.30 Last change: September 2010 6
SG3_UTILS SG_PERSIST(8)
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 tempo-
rarily by prefixing the command line invocation of sg_per-
sist with "LANG=en_US.utf-8" for example.
Alternatively the TIDS argument may specify a file (or pipe)
from which one or more TransportIDs may be read. If the TIDS
argument is "-" then stdin (standard input) is read. If the
TIDS argument is of the form "file=<name>" than 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 realtively sim-
ple. 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 trans-
portID 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.
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.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Uncommitted |
+---------------+--------------------------+
NOTES
In the 2.4 series of Linux kernels the DEVICE 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
sg3_utils-1.30 Last change: September 2010 7
SG3_UTILS SG_PERSIST(8)
the 2.6 series kernels.
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.
Most errors with the PROUT sub-commands (e.g. missing or
mismatched --prout-type=TYPE) 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.
Some recent disks accept some PRIN and PROUT sub-commands
when the media is stopped. One exception was setting the
APTPL flag (with the --param-aptpl option) during a key reg-
ister 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.
EXAMPLES
These examples use Linux device names. For suitable device
names in other supported Operating Systems see the
sg3_utils(8) man page.
Due to the various option defaults the simplest example exe-
cutes the 'read keys' sub-command of the PRIN command:
sg_persist /dev/sdb
This is the same as the following (long-winded) command:
sg_persist --in --read-keys --device=/dev/sdb
To read the current reservation either the '--read-reserva-
tion' form or the shorter '-r' can be used:
sg_persist -r /dev/sdb
To register the new reservation key 0x123abc the following
could be used:
sg_persist --out --register --param-sark=123abc /dev/sdb
Given the above registration succeeds, to reserve the DEVICE
(with type 'write exclusive') the following could be used:
sg_persist --out --reserve --param-rk=123abc
--prout-type=1 /dev/sdb
To release the reservation the following can be given (note
that the --param-rk and --prout-type arguments must match
those of the reservation):
sg3_utils-1.30 Last change: September 2010 8
SG3_UTILS SG_PERSIST(8)
sg_persist --out --release --param-rk=123abc
--prout-type=1 /dev/sdb
Finally to unregister a reservation key (and not effect
other registrations which is what '--clear' would do) the
command is a little surprising:
sg_persist --out --register --param-rk=123abc /dev/sdb
Now have a close look at the difference between the register
and unregister examples above.
An example file that is suitably formatted to pass trans-
portIDs 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_per-
sist_tst.sh in the same directory.
The above sequence of commands was tested successfully on a
Seagate Savvio 10K.3 disk which has a SAS interface.
EXIT STATUS
The exit status of sg_persist is 0 when it is successful.
Otherwise see the sg3_utils(8) man page.
AUTHOR
Written by Doug Gilbert
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2004-2010 Douglas Gilbert
This software is distributed under the GPL version 2. There
is NO warranty; not even for MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE.
SEE ALSO
sg3_utils(sg3_utils), scsires(internet)
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://sg.danny.cz/sg/p/sg3_utils-1.33.tgz
Further information about this software can be found on the
open source community website at
http://sg.danny.cz/sg/sg3_utils.html.
sg3_utils-1.30 Last change: September 2010 9