diff options
Diffstat (limited to 'doc/sg_persist.8')
| -rw-r--r-- | doc/sg_persist.8 | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/doc/sg_persist.8 b/doc/sg_persist.8 new file mode 100644 index 00000000..23a0c97a --- /dev/null +++ b/doc/sg_persist.8 @@ -0,0 +1,435 @@ +.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 ANSI INCITS 502\-2020) are sections +8.14 (titled "Reservations"), 9.16 (for the PRIN command) and 9.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\-5. 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) |