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 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.
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 --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 CAPABILITIES and READ FULL STATUS.
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-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 persistent reservation commands. See a
utility called ’scsires’ for support of the SCSI RESERVE and RELEASE
commands.
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 argument. For
example, these two: ’sg_persist --device=/dev/sg2’ and
’sg_persist /dev/sg2’ are equivalent.
-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
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. Relevant 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 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. ACA and other pending tasks are aborted.
-T, --prout-type=TYPE
specify the PROUT command’s ’type’ argument. Required by the
’register-move’, ’reserve’, ’release’ and ’preempt (and abort)’
sub-commands. Valid TYPE 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.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. registrations) 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 reservation on the
DEVICE. 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.
-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 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’.
-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.
-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 inclusive. 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 command. It
lists information about the aspects of persistent reservations
that the DEVICE supports.
-R, --reserve
Reserve is a sub-command of the PROUT command. It creates 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 TransportIDs 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 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 transport 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_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.
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.
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 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.
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.
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 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 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.
EXAMPLES
Due to the various option defaults the simplest example executes 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-reservation’ 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):
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 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.
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 © 2004-2009 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
scsires(internet)