From 7b165064d3d22cf8e699935bccef0e728857c4eb Mon Sep 17 00:00:00 2001 From: Douglas Gilbert Date: Mon, 10 Sep 2007 00:54:57 +0000 Subject: rearrange files into include, src, lib and doc directories git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@100 6180dd3e-e324-4e3e-922d-17de1ae2f315 --- doc/sg_persist.8 | 332 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 332 insertions(+) create mode 100644 doc/sg_persist.8 (limited to 'doc/sg_persist.8') diff --git a/doc/sg_persist.8 b/doc/sg_persist.8 new file mode 100644 index 00000000..6447cbdb --- /dev/null +++ b/doc/sg_persist.8 @@ -0,0 +1,332 @@ +.TH SG_PERSIST "8" "March 2007" "sg3_utils\-1.24" SG3_UTILS +.SH NAME +sg_persist \- sends a SCSI PERSISTENT RESERVE (IN or OUT) command +to manipulate registrations and reservations +.SH SYNOPSIS +.B sg_persist +[\fIOPTIONS\fR] [\fIDEVICE\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\-4 whose most recent draft is +revision 9 dated 17th February 2007) are sections 5.6 (titled "Reservation"), +6.13 (for the PRIN command) and 6.14 (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. +.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. +.TP +\fB\-H\fR, \fB\-\-hex\fR +the response to a valid PRIN sub\-command will be output in hexadecimal. +Normally if the PRIN sub\-command is recognised then the response +will be decoded as per SPC\-4. +.TP +\fB\-i\fR, \fB\-\-in\fR +specify that a SCSI PERSISTENT RESERVE IN command is required. This +is the default. +.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 PR In or Out 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). The associated \fI\-\-prout\-type=TYPE\fR option +needs to match the type of the 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). The associated \fI\-\-prout\-type=TYPE\fR option +needs to match the type of the 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.13.3.4 of SPC\-4 revision 9). +.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\-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='; b) Change an existing +registration with '\-\-param\-rk=' +and '\-\-param\-sark='; or c) Delete an existing registration +with '\-\-param\-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 '\-\-prout-sark=' 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\-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=\fIH,H...\fR +a transportID is required for the PROUT 'register and move' sub\-command +and is optional for the PROUT 'register' and 'register and ignore +existing key' sub\-commands. The latter two sub\-commands can take multiple +transportIDs in a list but only one is supported with this option +variant (use the following option variant that reads stdin if multiple +transportIDs are required). \fIH,H...\fR is a comma separated list of hex +bytes which represent the transportID. The list of hex numbers will be +padded out with zeros to 24 bytes which is the minimum length of a +transportID. A transportID longer than 24 bytes (e.g. for iSCSI) is +padded with zeros so its length is a multiple of 4. +.TP +\fB\-X\fR, \fB\-\-transport\-id=\-\fR +a transportID is required for the PROUT 'register and move' sub\-command +and is optional for the PROUT 'register' and 'register and ignore +existing key' sub\-commands. The latter two sub\-commands can take multiple +transportIDs in a list. The argument is '\-' which indicates +stdin should be read for the transportID(s). Empty lines are ignored. +Everything from and including a "#" on a line is ignored. +Leading spaces and tabs are ignored. All numbers +are assumed to be hexadecimal and can be separated by space, comma or +tab. There can be one transportID per line. TranportIDs will be padded +out with zeros to 24 bytes which is the minimum length of a +transportID. A transportID longer than 24 bytes (e.g. for iSCSI) is +padded with zeros so its length is a multiple of 4. +.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 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/sda" +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 +TransportIDs are defined in SPC\-4 and their structures vary depending +on the underlying transport. +.SH EXAMPLES +.PP +Due to defaults the simplest example executes the 'read keys' sub\-command +of the PRIN command: +.PP + sg_persist /dev/sda +.PP +This is the same as the following (long\-winded) command: +.PP + sg_persist \-\-in \-\-read\-keys \-\-device=/dev/sda +.PP +To read the current reservation either the '\-\-read\-reservation' form or +the shorter '\-r' can be used: +.PP + sg_persist \-r /dev/sda +.PP +To +.B register +the new reservation key 0x123abc the following could be used: +.PP + sg_persist \-\-out \-\-register \-\-param\-sark=123abc /dev/sda +.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/sda +.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/sda +.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/sda +.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 +the '\-\-transport\-id=\-' option can be found in the examples sub\-directory +of the sg3_utils package. That file is called 'transport_ids.txt'. +.SH EXIT STATUS +The exit status of sg_persist is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. +.SH AUTHOR +Written by Doug Gilbert +.SH "REPORTING BUGS" +Report bugs to . +.SH COPYRIGHT +Copyright \(co 2004\-2007 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 scsires(internet), examples/sg_persist_tst.sh(sg3_utils tarball) -- cgit v1.2.3