{ "content": [ { "type": "text", "text": "# SG_PERSIST(8) (man)\n\n**Summary:** sgpersist - use SCSI PERSISTENT RESERVE command to access registrations and reservations\n\n**Synopsis:** sgpersist [OPTIONS] DEVICE\nsgpersist [OPTIONS] --device=DEVICE\nsgpersist --help | --version\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -l | --alloc-length | — | specify the allocation length of the PRIN command. LEN is a hex value. By default this value is set to the size of the d |\n| -C | --clear | — | Clear is a sub-command of the PROUT command. It releases the persistent reservation (if any) and clears all registration |\n| -d | --device | — | DEVICE to send SCSI commands to. The DEVICE can either be provided via this option or via a freestanding argument. For e |\n| -h | --help | — | output a usage message showing main options. Use twice (e.g. '-hh') for the other op‐ tion and more help. |\n| -H | --hex | — | the response to a valid PRIN sub-command will be output in hexadecimal. By default (i.e. without this option) if the PRI |\n| -i | --in | — | specify that a SCSI PERSISTENT RESERVE IN command is required. This is the default. |\n| -m | --maxlen | — | LEN is used as the ALLOCATION LENGTH field of the PRIN command. LEN is by default a decimal value. To give a hex value u |\n| -n | --no-inquiry | — | the default action is to do a standard SCSI INQUIRY command and output make, product and revision strings plus the perip |\n| -o | --out | — | specify that a SCSI PERSISTENT RESERVE OUT command is required. |\n| -Y | --param-alltgpt | — | set the 'all target ports' (ALLTGPT) flag in the parameter block of the PROUT com‐ mand. Only relevant for 'register' an |\n| -Z | --param-aptpl | — | set the 'activate persist through power loss' (APTPL) flag in the parameter block of the PROUT command. Relevant for 're |\n| -K | --param-rk | — | specify the reservation key found in the parameter block of the PROUT command. RK is assumed to be hex (up to 8 bytes lo |\n| -S | --param-sark | — | specify the service action reservation key found in the parameter block of the PROUT command. SARK is assumed to be hex |\n| -P | --preempt | — | Preempt is a sub-command of the PROUT command. Preempts the existing persistent reser‐ vation (identified by --param-sar |\n| -A | --preempt-abort | — | Preempt and Abort is a sub-command of the PROUT command. Preempts the existing persis‐ tent reservation (identified by - |\n| -T | --prout-type | — | specify the PROUT command's 'type' argument. Required by the 'register-move', 're‐ serve', 'release' and 'preempt (and a |\n| -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 re |\n| -k | --read-keys | — | Read Keys is a sub-command of the PRIN command. Lists all the reservation keys regis‐ tered (i.e. registrations) with th |\n| -y | --readonly | — | Open DEVICE read-only. May be useful with PRIN commands if there are unwanted side ef‐ fects with the default read-write |\n| -r | --read-reservation | — | Read Reservation is a sub-command of the PRIN command. List information about the cur‐ rent holder of the reservation on |\n| -s | --read-status | — | same as --read-full-status. |\n| -G | --register | — | Register is a sub-command of the PROUT command. It has 3 different actions depending on associated parameters. a) add a |\n| -I | --register-ignore | — | Register and Ignore Existing Key is a sub-command of the PROUT command. Similar to --register except that when changing |\n| -M | --register-move | — | register (another initiator) and move (the reservation held by the current initiator to that other initiator) is a sub-c |\n| -Q | --relative-target-port | — | relative target port identifier that reservation is to be moved to by PROUT 'register and move' sub-command. RTPI is ass |\n| -L | --release | — | Release is a sub-command of the PROUT command. It releases the current persistent reservation. The --prout-type=TYPE and |\n| -z | --replace-lost | — | Replace Lost Reservation is a sub-command of the PROUT command. It \"begins a recovery process for the lost persistent re |\n| -c | --report-capabilities | — | Report Capabilities is a sub-command of the PRIN command. It lists information about the aspects of persistent reservati |\n| -R | --reserve | — | Reserve is a sub-command of the PROUT command. It creates a new persistent reservation (if permitted). The --prout-type= |\n| -X | --transport-id | — | The TIDS argument can take one of several forms. It can be a comma (or single space) separated list of ASCII hex bytes r |\n| -U | --unreg | — | optional when the PROUT register and move sub-command is invoked. If given it will un‐ register the current initiator (I |\n| -v | --verbose | — | print out cdb of issued commands prior to execution. If used twice prints out the pa‐ rameter block associated with the |\n| -V | --version | — | print out version string. Ignore all other parameters. -? output usage message. Ignore all other parameters. |\n\n## Examples\n\n- `These examples use Linux device names. For suitable device names in other supported Operating`\n- `Systems see the sg3utils(8) man page.`\n- `Due to the various option defaults the simplest example executes the 'read keys' sub-command`\n- `of the PRIN command:`\n- `sgpersist /dev/sdb`\n- `This is the same as the following (long-winded) command:`\n- `sgpersist --in --read-keys --device=/dev/sdb`\n- `To read the current reservation either the '--read-reservation' form or the shorter '-r' can`\n- `be used:`\n- `sgpersist -r /dev/sdb`\n- `To register the new reservation key 0x123abc the following could be used:`\n- `sgpersist --out --register --param-sark=123abc /dev/sdb`\n- `Given the above registration succeeds, to reserve the DEVICE (with type 'write exclusive')`\n- `the following could be used:`\n- `sgpersist --out --reserve --param-rk=123abc`\n- `--prout-type=1 /dev/sdb`\n- `To release the reservation the following can be given (note that the --param-rk and`\n- `--prout-type arguments must match those of the reservation):`\n- `sgpersist --out --release --param-rk=123abc`\n- `--prout-type=1 /dev/sdb`\n- `Finally to unregister a reservation key (and not effect other registrations which is what`\n- `'--clear' would do) the command is a little surprising:`\n- `sgpersist --out --register --param-rk=123abc /dev/sdb`\n- `Now have a close look at the difference between the register and unregister examples above.`\n- `An example file that is suitably formatted to pass transportIDs via a '--trans‐`\n- `port-id=file=transportids.txt' option can be found in the examples sub-directory of the`\n- `sg3utils package. There is also a simple test script called sgpersisttst.sh in the same`\n- `directory.`\n- `The above sequence of commands was tested successfully on a Seagate Savvio 10K.3 disk and a`\n- `1200 SSD both of which have SAS interfaces.`\n\n## See Also\n\n- sg3utils(sg3utils)\n- scsires(internet)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (6 lines)\n- **DESCRIPTION** (37 lines)\n- **OPTIONS** (3 lines) — 34 subsections\n - -l --alloc-length (5 lines)\n - -C --clear (4 lines)\n - -d --device (4 lines)\n - -h --help (3 lines)\n - -H --hex (4 lines)\n - -i --in (2 lines)\n - -m --maxlen (7 lines)\n - -n --no-inquiry (4 lines)\n - -o --out (2 lines)\n - -Y --param-alltgpt (4 lines)\n - -Z --param-aptpl (4 lines)\n - -K --param-rk (4 lines)\n - -S --param-sark (4 lines)\n - -P --preempt (6 lines)\n - -A --preempt-abort (6 lines)\n - -T --prout-type (8 lines)\n - -s --read-full-status (4 lines)\n - -k --read-keys (4 lines)\n - -y --readonly (5 lines)\n - -r --read-reservation (5 lines)\n - -s --read-status (2 lines)\n - -G --register (6 lines)\n - -I --register-ignore (4 lines)\n - -M --register-move (8 lines)\n - -Q --relative-target-port (4 lines)\n - -L --release (4 lines)\n - -z --replace-lost (6 lines)\n - -c --report-capabilities (3 lines)\n - -R --reserve (4 lines)\n - -X --transport-id (9 lines)\n - -U --unreg (5 lines)\n - -v --verbose (5 lines)\n - -V --version (4 lines)\n - TRANSPORT IDs (49 lines)\n- **NOTES** (16 lines)\n- **EXAMPLES** (48 lines)\n- **EXIT STATUS** (3 lines)\n- **ENVIRONMENT VARIABLES** (4 lines)\n- **AUTHOR** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **COPYRIGHT** (4 lines)\n- **SEE ALSO** (5 lines)\n\n## Full Content\n\n### NAME\n\nsgpersist - use SCSI PERSISTENT RESERVE command to access registrations and reservations\n\n### SYNOPSIS\n\nsgpersist [OPTIONS] DEVICE\n\nsgpersist [OPTIONS] --device=DEVICE\n\nsgpersist --help | --version\n\n### DESCRIPTION\n\nThis utility allows Persistent reservations and registrations to be queried and changed. Per‐\nsistent reservations and registrations are queried by sub-commands (called \"service actions\"\nin SPC-4) of the SCSI PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and reg‐\nistrations are changed by sub-commands of the SCSI PERSISTENT RESERVE OUT (PROUT) command.\n\nThere is a two stage process to obtain a persistent reservation. First an application (an IT\nnexus in standard's jargon) must register a reservation key. If that is accepted (and it\nshould be unless some other IT nexus has registered that key) then the application can try\nand reserve the device. The reserve operation must specify the reservation key and a \"type\"\n(see the --prout-type=TYPE option).\n\nIt is relatively safe to query the state of Persistent reservations and registrations. With\nno options this utility defaults to the READ KEYS sub-command of the PRIN command. Other PRIN\nsub-commands are READ RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.\n\nBefore trying to change Persistent reservations and registrations users should be aware of\nwhat they are doing. The relevant sections of the SCSI Primary Commands document (i.e. SPC-5\nwhose most recent draft is revision 18 dated 4 January 2018) are sections 5.14 (titled\n\"Reservations\"), 6.16 (for the PRIN command) and 6.17 (for the PROUT command). To safeguard\nagainst accidental use, the --out option must be given when a PROUT sub-command (e.g. --reg‐\nister) is used.\n\nThe older SCSI RESERVE and RELEASE commands (both 6 and 10 byte variants) are not supported\nby this utility. In SPC-3, RESERVE and RELEASE are deprecated, replaced by Persistent Reser‐\nvations. RESERVE and RELEASE have been removed from SPC-4 and Annex B is provided showing how\nto convert to persistent reservation commands. See a utility called 'scsires' for support of\nthe SCSI RESERVE and RELEASE commands.\n\nThe DEVICE is required by all variants of this utility apart from --help. The DEVICE can be\ngiven either as an argument (typically but not necessarily the last one) or via the --de‐\nvice=DEVICE option.\n\nSPC-4 does not use the term \"sub-command\". It uses the term \"service action\" for this and for\npart of a field's name in the parameter block associated with the PROUT command (i.e. \"ser‐\nvice action reservation key\"). To lessen the potential confusion the term \"sub-command\" has\nbeen introduced.\n\n### OPTIONS\n\nArguments to long options are mandatory for short options as well. The following options are\nsorted in alphabetical order, based on their long option name.\n\n#### -l --alloc-length\n\nspecify the allocation length of the PRIN command. LEN is a hex value. By default\nthis value is set to the size of the data-in buffer (8192). This parameter is of use\nfor verification that response to PRIN commands with various allocation lengths is per\nsection 4.3.5.6 of SPC-4 revision 18. Valid LEN values are 0-8192.\n\n#### -C --clear\n\nClear is a sub-command of the PROUT command. It releases the persistent reservation\n(if any) and clears all registrations from the device. It is required to supply a\nreservation key that is registered for this ITL nexus (identified by --param-rk=RK).\n\n#### -d --device\n\nDEVICE to send SCSI commands to. The DEVICE can either be provided via this option or\nvia a freestanding argument. For example, these two: 'sgpersist --device=/dev/sg2'\nand 'sgpersist /dev/sg2' are equivalent.\n\n#### -h --help\n\noutput a usage message showing main options. Use twice (e.g. '-hh') for the other op‐\ntion and more help.\n\n#### -H --hex\n\nthe response to a valid PRIN sub-command will be output in hexadecimal. By default\n(i.e. without this option) if the PRIN sub-command is recognised then the response\nwill be decoded as per SPC-4. May be used more than once for more hex and less text.\n\n#### -i --in\n\nspecify that a SCSI PERSISTENT RESERVE IN command is required. This is the default.\n\n#### -m --maxlen\n\nLEN is used as the ALLOCATION LENGTH field of the PRIN command. LEN is by default a\ndecimal value. To give a hex value use a '0x' or '0X' prefix, or use a 'h' (or 'H')\nsuffix. Can also take multipliers, see --maxlen=LEN option in the sg3utils manual\npage.\nThis option is the same as --alloc-length=LEN option apart from the representation of\nLEN. The option defaults to decimal while --alloc-length=LEN only takes hex.\n\n#### -n --no-inquiry\n\nthe default action is to do a standard SCSI INQUIRY command and output make, product\nand revision strings plus the peripheral device type prior to executing a PRIN or\nPROUT command. With this option the INQUIRY command is skipped.\n\n#### -o --out\n\nspecify that a SCSI PERSISTENT RESERVE OUT command is required.\n\n#### -Y --param-alltgpt\n\nset the 'all target ports' (ALLTGPT) flag in the parameter block of the PROUT com‐\nmand. Only relevant for 'register' and 'register and ignore existing key' sub-com‐\nmands.\n\n#### -Z --param-aptpl\n\nset the 'activate persist through power loss' (APTPL) flag in the parameter block of\nthe PROUT command. Relevant for 'register', 'register and ignore existing key' and\n'register and move' sub-commands.\n\n#### -K --param-rk\n\nspecify the reservation key found in the parameter block of the PROUT command. RK is\nassumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by\nmost PROUT sub-commands.\n\n#### -S --param-sark\n\nspecify the service action reservation key found in the parameter block of the PROUT\ncommand. SARK is assumed to be hex (up to 8 bytes long). Default value is 0. This op‐\ntion is needed by some PROUT sub-commands.\n\n#### -P --preempt\n\nPreempt is a sub-command of the PROUT command. Preempts the existing persistent reser‐\nvation (identified by --param-sark=SARK) with the registration key that is registered\nfor this ITL nexus (identified by --param-rk=RK). If a new reservation is estab‐\nlished as a result of the preemption then the supplied --prout-type=TYPE is used as\nthe type for this new reservation.\n\n#### -A --preempt-abort\n\nPreempt and Abort is a sub-command of the PROUT command. Preempts the existing persis‐\ntent reservation (identified by --param-sark=SARK) with the registration key that is\nregistered for this ITL nexus (identified by --param-rk=RK). If a new reservation is\nestablished as a result of the preemption then the supplied --prout-type=TYPE is used\nas the type for this new reservation. ACA and other pending tasks are aborted.\n\n#### -T --prout-type\n\nspecify the PROUT command's 'type' argument. Required by the 'register-move', 're‐\nserve', 'release' and 'preempt (and abort)' sub-commands. Valid TYPE values: 1-> write\nexclusive, 3-> exclusive access, 5-> write exclusive - registrants only, 6-> exclusive\naccess - registrants only, 7-> write exclusive - all registrants, 8-> exclusive access\n- all registrants. Default value is 0 (which is an invalid type). Each \"persistent\nreservation type\" is explained in more detail in a subsection of that name in the read\nreservation section of the PRIN command (section 6.15.3.3 of SPC-4 revision 37).\n\n#### -s --read-full-status\n\nRead Full Status is a sub-command of the PRIN command. For each registration with the\ngiven SCSI device, it lists the reservation key and associated information. Trans‐\nportIDs, if supplied in the response, are decoded.\n\n#### -k --read-keys\n\nRead Keys is a sub-command of the PRIN command. Lists all the reservation keys regis‐\ntered (i.e. registrations) with the given SCSI device. This is the default sub-command\nfor the SCSI PRIN command.\n\n#### -y --readonly\n\nOpen DEVICE read-only. May be useful with PRIN commands if there are unwanted side ef‐\nfects with the default read-write open. When given twice is interpreted as forcing a\nread-write open thus overriding the SGPERSISTINRDONLY environment variable if\npresent. See the ENVIRONMENT VARIABLES section for more.\n\n#### -r --read-reservation\n\nRead Reservation is a sub-command of the PRIN command. List information about the cur‐\nrent holder of the reservation on the DEVICE. If there is no current reservation this\nwill be noted. Information about the current holder of the reservation includes its\nreservation key, scope and type.\n\n#### -s --read-status\n\nsame as --read-full-status.\n\n#### -G --register\n\nRegister is a sub-command of the PROUT command. It has 3 different actions depending\non associated parameters. a) add a new registration with '--param-rk=0' and\n'--param-sark='; b) Change an existing registration with '--param-rk='\nand '--param-sark='; or c) Delete an existing registration with\n'--param-rk=' and '--param-sark=0'.\n\n#### -I --register-ignore\n\nRegister and Ignore Existing Key is a sub-command of the PROUT command. Similar to\n--register except that when changing a reservation key the old key is not specified.\nThe '--param-sark=' option should also be given.\n\n#### -M --register-move\n\nregister (another initiator) and move (the reservation held by the current initiator\nto that other initiator) is a sub-command of the PROUT command. It requires the\ntransportID of the other initiator. [The standard uses the term IT nexus but the\npoint to stress is that there are two initiators (the one sending this command and an‐\nother one) but only one logical unit.] The --prout-type=TYPE and --param-rk=RK op‐\ntions need to match that of the existing reservation while --param-sark=SARK option\nspecifies the reservation key of the new (i.e. destination) registration.\n\n#### -Q --relative-target-port\n\nrelative target port identifier that reservation is to be moved to by PROUT 'register\nand move' sub-command. RTPI is assumed to be hex in the range 0 to ffff inclusive. De‐\nfaults to 0 .\n\n#### -L --release\n\nRelease is a sub-command of the PROUT command. It releases the current persistent\nreservation. The --prout-type=TYPE and --param-rk=RK options, matching the reserva‐\ntion, must also be specified.\n\n#### -z --replace-lost\n\nReplace Lost Reservation is a sub-command of the PROUT command. It \"begins a recovery\nprocess for the lost persistent reservation that is managed by application clients\".\nIt also stops the device server terminating commands due to a lost persistent reserva‐\ntion. Options should be be '--param-rk=0' (or not given), '--param-sark=' and\n--prout-type=TYPE.\n\n#### -c --report-capabilities\n\nReport Capabilities is a sub-command of the PRIN command. It lists information about\nthe aspects of persistent reservations that the DEVICE supports.\n\n#### -R --reserve\n\nReserve is a sub-command of the PROUT command. It creates a new persistent reservation\n(if permitted). The --prout-type=TYPE and --param-rk=RK options must also be speci‐\nfied.\n\n#### -X --transport-id\n\nThe TIDS argument can take one of several forms. It can be a comma (or single space)\nseparated list of ASCII hex bytes representing a single TransportID as defined in\nSPC-4. They are usually 24 bytes long apart from in iSCSI. The TIDS argument may be a\ntransport specific form (e.g. \"sas,5000c50005b32001\" is clearer than an equivalent to\nthe hex byte form: \"6,0,0,0,5,0,c5,0,5,b3,20,1\"). The TIDS argument may be \"-\" in\nwhich case one or more TransportIDs can be read from stdin. The TIDS argument may be\nof the form \"file=\" in which case one or more TransportIDs can be read from a\nfile called . See the \"TRANSPORT IDs\" section below for more information.\n\n#### -U --unreg\n\noptional when the PROUT register and move sub-command is invoked. If given it will un‐\nregister the current initiator (IT nexus) after the other initiator has been regis‐\ntered and the reservation moved to it. When not given the initiator (IT nexus) that\nsent the PROUT command remains registered.\n\n#### -v --verbose\n\nprint out cdb of issued commands prior to execution. If used twice prints out the pa‐\nrameter block associated with the PROUT command prior to its execution as well. If\nused thrice decodes given transportID(s) as well. To see the response to a PRIN com‐\nmand in low level form use the --hex option.\n\n#### -V --version\n\nprint out version string. Ignore all other parameters.\n\n-? output usage message. Ignore all other parameters.\n\n#### TRANSPORT IDs\n\nTransportIDs are used in persistent reservations to identify initiators. The format of a\nTransportID differs depending on the type of transport being used. Their format is described\nin SPC-4 (in draft revision 37 see section 7.6.4).\n\nA TransportID is required for the PROUT 'register and move' sub-command and the PROUT 'regis‐\nter' sub-command can have zero, one or more TransportIDs.\n\nWhen the --transport-id=TIDS option is given then the TIDS argument may be a comma (or single\nspace) separated list of ASCII hex bytes that represent a single TransportID as defined in\nSPC-4. Alternatively the TIDS argument may be a transport specific string starting with ei‐\nther \"fcp,\", \"spi,\", \"sbp,\", \"srp,\", \"iqn\", \"sas,\" or \"sop,\". The \"iqn\" form is an iSCSI\nqualified name. Apart from \"iqn\" the other transport specific leadin string may be given in\nupper case (e.g. \"FCP,\").\n\nThe \"fcp,\" form should be followed by 16 ASCII hex digits that represent an initiator's\nNPORTNAME (e.g. \"fcp,10000000C9F3A571\"). The \"spi,\" form should be followed by \",\" (both decimal numbers). The \"sbp,\" form should be\nfollowed by 16 ASCII hex digits that represent an initiator's EUI-64 name. The \"srp,\" form\nshould be followed by 32 ASCII hex digits that represent an initiator port identifier. The\n\"sas,\" form should be followed by 16 ASCII hex digits that represent an initiator's port SAS\naddress (e.g. \"sas,5000c50005b32001\"). The \"sop,\" form takes a hex number that represents a\nrouting id.\n\nThere are two iSCSI qualified name forms. The shorter form contains the iSCSI name of the\ninitiator port (e.g. \"iqn.5886.com.acme.diskarrays-sn-a8675309\"). The longer form adds the\ninitiator session id (ISID in hex) separated by \",i,0x\". For example\n\"iqn.5886.com.acme.diskarrays-sn-a8675309,i,0x1234567890ab\". On the command line to stop\npunctuation in an iSCSI name being (mis)-interpreted by the shell, putting the option argu‐\nment containing the iSCSI name in double quotes is advised. iSCSI names are encoded in UTF-8\nso if non (7 bit) ASCII characters appear in the iSCSI name on the command line, there will\nbe difficulties if they are not encoded in UTF-8. The locale can be changed temporarily by\nprefixing the command line invocation of sgpersist with \"LANG=enUS.utf-8\" for example.\n\nAlternatively the TIDS argument may specify a file (or pipe) from which one or more Trans‐\nportIDs may be read. If the TIDS argument is \"-\" then stdin (standard input) is read. If the\nTIDS argument is of the form \"file=\" then a file called is read. A valid SPC-4\nTransportID is built from the transport specific string outlined in the previous paragraphs.\nThe parsing of the data read is relatively simple. Empty lines are ignored. Everything from\nand including a \"#\" on a line is ignored. Leading spaces and tabs are ignored. There can be\none transportID per line. The transportID can either be a comma, space or tab separated list\nof ASCII hex bytes that represent a TransportID as defined in SPC-4. Padding with zero bytes\nto a minimum length of 24 bytes is performed if necessary. The transportID may also be trans‐\nport specific string type discussed above.\n\nIn SPC-3 the SPECIPT bit set to one and TransportIDs were allowed for the PROUT register\nand ignore existing key sub-command. In SPC-4 that is disallowed yielding a CHECK CONDITION\nstatus with and ILLEGAL REQUEST sense key and an additional sense code set to INVALID FIELD\nIN PARAMETER LIST.\n\n### NOTES\n\nIn the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6\nseries any SCSI device name (e.g. /dev/sdc, /dev/st1m or /dev/sg3) can be specified. For ex‐\nample \"sgpersist --read-keys /dev/sdb\" will work in the 2.6 series kernels.\n\nThe only scope for PROUT commands supported in the current draft of SPC-4 is \"LUSCOPE\".\nHence there seems to be no point in offering an option to set scope to another value.\n\nMost errors with the PROUT sub-commands (e.g. missing or mismatched --prout-type=TYPE) will\nresult in a RESERVATION CONFLICT status. This can be a bit confusing when you know there is\nonly one (active) initiator: the \"conflict\" is with the SPC standard, not another initiator.\n\nSome recent disks accept some PRIN and PROUT sub-commands when the media is stopped. One ex‐\nception was setting the APTPL flag (with the --param-aptpl option) during a key register op‐\neration, it complained if the disk one stopped. The error indicated it wanted the disk spun\nup and when that happened, the registration was successful.\n\n### EXAMPLES\n\nThese examples use Linux device names. For suitable device names in other supported Operating\nSystems see the sg3utils(8) man page.\n\nDue to the various option defaults the simplest example executes the 'read keys' sub-command\nof the PRIN command:\n\nsgpersist /dev/sdb\n\nThis is the same as the following (long-winded) command:\n\nsgpersist --in --read-keys --device=/dev/sdb\n\nTo read the current reservation either the '--read-reservation' form or the shorter '-r' can\nbe used:\n\nsgpersist -r /dev/sdb\n\nTo register the new reservation key 0x123abc the following could be used:\n\nsgpersist --out --register --param-sark=123abc /dev/sdb\n\nGiven the above registration succeeds, to reserve the DEVICE (with type 'write exclusive')\nthe following could be used:\n\nsgpersist --out --reserve --param-rk=123abc\n--prout-type=1 /dev/sdb\n\nTo release the reservation the following can be given (note that the --param-rk and\n--prout-type arguments must match those of the reservation):\n\nsgpersist --out --release --param-rk=123abc\n--prout-type=1 /dev/sdb\n\nFinally to unregister a reservation key (and not effect other registrations which is what\n'--clear' would do) the command is a little surprising:\n\nsgpersist --out --register --param-rk=123abc /dev/sdb\n\nNow have a close look at the difference between the register and unregister examples above.\n\nAn example file that is suitably formatted to pass transportIDs via a '--trans‐\nport-id=file=transportids.txt' option can be found in the examples sub-directory of the\nsg3utils package. There is also a simple test script called sgpersisttst.sh in the same\ndirectory.\n\nThe above sequence of commands was tested successfully on a Seagate Savvio 10K.3 disk and a\n1200 SSD both of which have SAS interfaces.\n\n### EXIT STATUS\n\nThe exit status of sgpersist is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n\n### ENVIRONMENT VARIABLES\n\nCurrently there is one recognised environment variable: SGPERSISTINRDONLY. If present and\nonly if a PRIN command has been selected then the given DEVICE is opened read-only (e.g. in\nUnix that is with the ORDONLY flag). See the --readonly option.\n\n### AUTHOR\n\nWritten by Douglas Gilbert\n\n### REPORTING BUGS\n\nReport bugs to .\n\n### COPYRIGHT\n\nCopyright © 2004-2018 Douglas Gilbert\nThis software is distributed under the GPL version 2. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n\n### SEE ALSO\n\nsg3utils(sg3utils), scsires(internet)\n\n\n\nsg3utils-1.43 June 2018 SGPERSIST(8)\n\n" } ], "structuredContent": { "command": "SG_PERSIST", "section": "8", "mode": "man", "summary": "sgpersist - use SCSI PERSISTENT RESERVE command to access registrations and reservations", "synopsis": "sgpersist [OPTIONS] DEVICE\nsgpersist [OPTIONS] --device=DEVICE\nsgpersist --help | --version", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-l", "long": "--alloc-length", "arg": null, "description": "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." }, { "flag": "-C", "long": "--clear", "arg": null, "description": "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 ITL nexus (identified by --param-rk=RK)." }, { "flag": "-d", "long": "--device", "arg": null, "description": "DEVICE to send SCSI commands to. The DEVICE can either be provided via this option or via a freestanding argument. For example, these two: 'sgpersist --device=/dev/sg2' and 'sgpersist /dev/sg2' are equivalent." }, { "flag": "-h", "long": "--help", "arg": null, "description": "output a usage message showing main options. Use twice (e.g. '-hh') for the other op‐ tion and more help." }, { "flag": "-H", "long": "--hex", "arg": null, "description": "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." }, { "flag": "-i", "long": "--in", "arg": null, "description": "specify that a SCSI PERSISTENT RESERVE IN command is required. This is the default." }, { "flag": "-m", "long": "--maxlen", "arg": null, "description": "LEN is used as the ALLOCATION LENGTH field of the PRIN command. LEN 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 --maxlen=LEN option in the sg3utils manual page. This option is the same as --alloc-length=LEN option apart from the representation of LEN. The option defaults to decimal while --alloc-length=LEN only takes hex." }, { "flag": "-n", "long": "--no-inquiry", "arg": null, "description": "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." }, { "flag": "-o", "long": "--out", "arg": null, "description": "specify that a SCSI PERSISTENT RESERVE OUT command is required." }, { "flag": "-Y", "long": "--param-alltgpt", "arg": null, "description": "set the 'all target ports' (ALLTGPT) flag in the parameter block of the PROUT com‐ mand. Only relevant for 'register' and 'register and ignore existing key' sub-com‐ mands." }, { "flag": "-Z", "long": "--param-aptpl", "arg": null, "description": "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." }, { "flag": "-K", "long": "--param-rk", "arg": null, "description": "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." }, { "flag": "-S", "long": "--param-sark", "arg": null, "description": "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 op‐ tion is needed by some PROUT sub-commands." }, { "flag": "-P", "long": "--preempt", "arg": null, "description": "Preempt is a sub-command of the PROUT command. Preempts the existing persistent reser‐ vation (identified by --param-sark=SARK) with the registration key that is registered for this ITL nexus (identified by --param-rk=RK). If a new reservation is estab‐ lished as a result of the preemption then the supplied --prout-type=TYPE is used as the type for this new reservation." }, { "flag": "-A", "long": "--preempt-abort", "arg": null, "description": "Preempt and Abort is a sub-command of the PROUT command. Preempts the existing persis‐ tent reservation (identified by --param-sark=SARK) with the registration key that is registered for this ITL nexus (identified by --param-rk=RK). If a new reservation is established as a result of the preemption then the supplied --prout-type=TYPE is used as the type for this new reservation. ACA and other pending tasks are aborted." }, { "flag": "-T", "long": "--prout-type", "arg": null, "description": "specify the PROUT command's 'type' argument. Required by the 'register-move', 're‐ serve', '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.15.3.3 of SPC-4 revision 37)." }, { "flag": "-s", "long": "--read-full-status", "arg": null, "description": "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. Trans‐ portIDs, if supplied in the response, are decoded." }, { "flag": "-k", "long": "--read-keys", "arg": null, "description": "Read Keys is a sub-command of the PRIN command. Lists all the reservation keys regis‐ tered (i.e. registrations) with the given SCSI device. This is the default sub-command for the SCSI PRIN command." }, { "flag": "-y", "long": "--readonly", "arg": null, "description": "Open DEVICE read-only. May be useful with PRIN commands if there are unwanted side ef‐ fects with the default read-write open. When given twice is interpreted as forcing a read-write open thus overriding the SGPERSISTINRDONLY environment variable if present. See the ENVIRONMENT VARIABLES section for more." }, { "flag": "-r", "long": "--read-reservation", "arg": null, "description": "Read Reservation is a sub-command of the PRIN command. List information about the cur‐ rent 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." }, { "flag": "-s", "long": "--read-status", "arg": null, "description": "same as --read-full-status." }, { "flag": "-G", "long": "--register", "arg": null, "description": "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'." }, { "flag": "-I", "long": "--register-ignore", "arg": null, "description": "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=' option should also be given." }, { "flag": "-M", "long": "--register-move", "arg": null, "description": "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 IT nexus but the point to stress is that there are two initiators (the one sending this command and an‐ other one) but only one logical unit.] The --prout-type=TYPE and --param-rk=RK op‐ tions need to match that of the existing reservation while --param-sark=SARK option specifies the reservation key of the new (i.e. destination) registration." }, { "flag": "-Q", "long": "--relative-target-port", "arg": null, "description": "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. De‐ faults to 0 ." }, { "flag": "-L", "long": "--release", "arg": null, "description": "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 reserva‐ tion, must also be specified." }, { "flag": "-z", "long": "--replace-lost", "arg": null, "description": "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 reserva‐ tion. Options should be be '--param-rk=0' (or not given), '--param-sark=' and --prout-type=TYPE." }, { "flag": "-c", "long": "--report-capabilities", "arg": null, "description": "Report Capabilities is a sub-command of the PRIN command. It lists information about the aspects of persistent reservations that the DEVICE supports." }, { "flag": "-R", "long": "--reserve", "arg": null, "description": "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 speci‐ fied." }, { "flag": "-X", "long": "--transport-id", "arg": null, "description": "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\" is clearer than an equivalent to the hex byte form: \"6,0,0,0,5,0,c5,0,5,b3,20,1\"). 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=\" in which case one or more TransportIDs can be read from a file called . See the \"TRANSPORT IDs\" section below for more information." }, { "flag": "-U", "long": "--unreg", "arg": null, "description": "optional when the PROUT register and move sub-command is invoked. If given it will un‐ register the current initiator (IT nexus) after the other initiator has been regis‐ tered and the reservation moved to it. When not given the initiator (IT nexus) that sent the PROUT command remains registered." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "print out cdb of issued commands prior to execution. If used twice prints out the pa‐ rameter 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 com‐ mand in low level form use the --hex option." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print out version string. Ignore all other parameters. -? output usage message. Ignore all other parameters." } ], "examples": [ "These examples use Linux device names. For suitable device names in other supported Operating", "Systems see the sg3utils(8) man page.", "Due to the various option defaults the simplest example executes the 'read keys' sub-command", "of the PRIN command:", "sgpersist /dev/sdb", "This is the same as the following (long-winded) command:", "sgpersist --in --read-keys --device=/dev/sdb", "To read the current reservation either the '--read-reservation' form or the shorter '-r' can", "be used:", "sgpersist -r /dev/sdb", "To register the new reservation key 0x123abc the following could be used:", "sgpersist --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:", "sgpersist --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):", "sgpersist --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:", "sgpersist --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 '--trans‐", "port-id=file=transportids.txt' option can be found in the examples sub-directory of the", "sg3utils package. There is also a simple test script called sgpersisttst.sh in the same", "directory.", "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." ], "see_also": [ { "name": "sg3utils", "section": "sg3utils", "url": "https://www.chedong.com/phpMan.php/man/sg3utils/sg3utils/json" }, { "name": "scsires", "section": "internet", "url": "https://www.chedong.com/phpMan.php/man/scsires/internet/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 37, "subsections": [] }, { "name": "OPTIONS", "lines": 3, "subsections": [ { "name": "-l --alloc-length", "lines": 5, "flag": "-l", "long": "--alloc-length" }, { "name": "-C --clear", "lines": 4, "flag": "-C", "long": "--clear" }, { "name": "-d --device", "lines": 4, "flag": "-d", "long": "--device" }, { "name": "-h --help", "lines": 3, "flag": "-h", "long": "--help" }, { "name": "-H --hex", "lines": 4, "flag": "-H", "long": "--hex" }, { "name": "-i --in", "lines": 2, "flag": "-i", "long": "--in" }, { "name": "-m --maxlen", "lines": 7, "flag": "-m", "long": "--maxlen" }, { "name": "-n --no-inquiry", "lines": 4, "flag": "-n", "long": "--no-inquiry" }, { "name": "-o --out", "lines": 2, "flag": "-o", "long": "--out" }, { "name": "-Y --param-alltgpt", "lines": 4, "flag": "-Y", "long": "--param-alltgpt" }, { "name": "-Z --param-aptpl", "lines": 4, "flag": "-Z", "long": "--param-aptpl" }, { "name": "-K --param-rk", "lines": 4, "flag": "-K", "long": "--param-rk" }, { "name": "-S --param-sark", "lines": 4, "flag": "-S", "long": "--param-sark" }, { "name": "-P --preempt", "lines": 6, "flag": "-P", "long": "--preempt" }, { "name": "-A --preempt-abort", "lines": 6, "flag": "-A", "long": "--preempt-abort" }, { "name": "-T --prout-type", "lines": 8, "flag": "-T", "long": "--prout-type" }, { "name": "-s --read-full-status", "lines": 4, "flag": "-s", "long": "--read-full-status" }, { "name": "-k --read-keys", "lines": 4, "flag": "-k", "long": "--read-keys" }, { "name": "-y --readonly", "lines": 5, "flag": "-y", "long": "--readonly" }, { "name": "-r --read-reservation", "lines": 5, "flag": "-r", "long": "--read-reservation" }, { "name": "-s --read-status", "lines": 2, "flag": "-s", "long": "--read-status" }, { "name": "-G --register", "lines": 6, "flag": "-G", "long": "--register" }, { "name": "-I --register-ignore", "lines": 4, "flag": "-I", "long": "--register-ignore" }, { "name": "-M --register-move", "lines": 8, "flag": "-M", "long": "--register-move" }, { "name": "-Q --relative-target-port", "lines": 4, "flag": "-Q", "long": "--relative-target-port" }, { "name": "-L --release", "lines": 4, "flag": "-L", "long": "--release" }, { "name": "-z --replace-lost", "lines": 6, "flag": "-z", "long": "--replace-lost" }, { "name": "-c --report-capabilities", "lines": 3, "flag": "-c", "long": "--report-capabilities" }, { "name": "-R --reserve", "lines": 4, "flag": "-R", "long": "--reserve" }, { "name": "-X --transport-id", "lines": 9, "flag": "-X", "long": "--transport-id" }, { "name": "-U --unreg", "lines": 5, "flag": "-U", "long": "--unreg" }, { "name": "-v --verbose", "lines": 5, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 4, "flag": "-V", "long": "--version" }, { "name": "TRANSPORT IDs", "lines": 49 } ] }, { "name": "NOTES", "lines": 16, "subsections": [] }, { "name": "EXAMPLES", "lines": 48, "subsections": [] }, { "name": "EXIT STATUS", "lines": 3, "subsections": [] }, { "name": "ENVIRONMENT VARIABLES", "lines": 4, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 4, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "sgpersist - use SCSI PERSISTENT RESERVE command to access registrations and reservations\n", "subsections": [] }, "SYNOPSIS": { "content": "sgpersist [OPTIONS] DEVICE\n\nsgpersist [OPTIONS] --device=DEVICE\n\nsgpersist --help | --version\n", "subsections": [] }, "DESCRIPTION": { "content": "This utility allows Persistent reservations and registrations to be queried and changed. Per‐\nsistent reservations and registrations are queried by sub-commands (called \"service actions\"\nin SPC-4) of the SCSI PERSISTENT RESERVE IN (PRIN) command. Persistent reservations and reg‐\nistrations are changed by sub-commands of the SCSI PERSISTENT RESERVE OUT (PROUT) command.\n\nThere is a two stage process to obtain a persistent reservation. First an application (an IT\nnexus in standard's jargon) must register a reservation key. If that is accepted (and it\nshould be unless some other IT nexus has registered that key) then the application can try\nand reserve the device. The reserve operation must specify the reservation key and a \"type\"\n(see the --prout-type=TYPE option).\n\nIt is relatively safe to query the state of Persistent reservations and registrations. With\nno options this utility defaults to the READ KEYS sub-command of the PRIN command. Other PRIN\nsub-commands are READ RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.\n\nBefore trying to change Persistent reservations and registrations users should be aware of\nwhat they are doing. The relevant sections of the SCSI Primary Commands document (i.e. SPC-5\nwhose most recent draft is revision 18 dated 4 January 2018) are sections 5.14 (titled\n\"Reservations\"), 6.16 (for the PRIN command) and 6.17 (for the PROUT command). To safeguard\nagainst accidental use, the --out option must be given when a PROUT sub-command (e.g. --reg‐\nister) is used.\n\nThe older SCSI RESERVE and RELEASE commands (both 6 and 10 byte variants) are not supported\nby this utility. In SPC-3, RESERVE and RELEASE are deprecated, replaced by Persistent Reser‐\nvations. RESERVE and RELEASE have been removed from SPC-4 and Annex B is provided showing how\nto convert to persistent reservation commands. See a utility called 'scsires' for support of\nthe SCSI RESERVE and RELEASE commands.\n\nThe DEVICE is required by all variants of this utility apart from --help. The DEVICE can be\ngiven either as an argument (typically but not necessarily the last one) or via the --de‐\nvice=DEVICE option.\n\nSPC-4 does not use the term \"sub-command\". It uses the term \"service action\" for this and for\npart of a field's name in the parameter block associated with the PROUT command (i.e. \"ser‐\nvice action reservation key\"). To lessen the potential confusion the term \"sub-command\" has\nbeen introduced.\n", "subsections": [] }, "OPTIONS": { "content": "Arguments to long options are mandatory for short options as well. The following options are\nsorted in alphabetical order, based on their long option name.\n", "subsections": [ { "name": "-l --alloc-length", "content": "specify the allocation length of the PRIN command. LEN is a hex value. By default\nthis value is set to the size of the data-in buffer (8192). This parameter is of use\nfor verification that response to PRIN commands with various allocation lengths is per\nsection 4.3.5.6 of SPC-4 revision 18. Valid LEN values are 0-8192.\n", "flag": "-l", "long": "--alloc-length" }, { "name": "-C --clear", "content": "Clear is a sub-command of the PROUT command. It releases the persistent reservation\n(if any) and clears all registrations from the device. It is required to supply a\nreservation key that is registered for this ITL nexus (identified by --param-rk=RK).\n", "flag": "-C", "long": "--clear" }, { "name": "-d --device", "content": "DEVICE to send SCSI commands to. The DEVICE can either be provided via this option or\nvia a freestanding argument. For example, these two: 'sgpersist --device=/dev/sg2'\nand 'sgpersist /dev/sg2' are equivalent.\n", "flag": "-d", "long": "--device" }, { "name": "-h --help", "content": "output a usage message showing main options. Use twice (e.g. '-hh') for the other op‐\ntion and more help.\n", "flag": "-h", "long": "--help" }, { "name": "-H --hex", "content": "the response to a valid PRIN sub-command will be output in hexadecimal. By default\n(i.e. without this option) if the PRIN sub-command is recognised then the response\nwill be decoded as per SPC-4. May be used more than once for more hex and less text.\n", "flag": "-H", "long": "--hex" }, { "name": "-i --in", "content": "specify that a SCSI PERSISTENT RESERVE IN command is required. This is the default.\n", "flag": "-i", "long": "--in" }, { "name": "-m --maxlen", "content": "LEN is used as the ALLOCATION LENGTH field of the PRIN command. LEN is by default a\ndecimal value. To give a hex value use a '0x' or '0X' prefix, or use a 'h' (or 'H')\nsuffix. Can also take multipliers, see --maxlen=LEN option in the sg3utils manual\npage.\nThis option is the same as --alloc-length=LEN option apart from the representation of\nLEN. The option defaults to decimal while --alloc-length=LEN only takes hex.\n", "flag": "-m", "long": "--maxlen" }, { "name": "-n --no-inquiry", "content": "the default action is to do a standard SCSI INQUIRY command and output make, product\nand revision strings plus the peripheral device type prior to executing a PRIN or\nPROUT command. With this option the INQUIRY command is skipped.\n", "flag": "-n", "long": "--no-inquiry" }, { "name": "-o --out", "content": "specify that a SCSI PERSISTENT RESERVE OUT command is required.\n", "flag": "-o", "long": "--out" }, { "name": "-Y --param-alltgpt", "content": "set the 'all target ports' (ALLTGPT) flag in the parameter block of the PROUT com‐\nmand. Only relevant for 'register' and 'register and ignore existing key' sub-com‐\nmands.\n", "flag": "-Y", "long": "--param-alltgpt" }, { "name": "-Z --param-aptpl", "content": "set the 'activate persist through power loss' (APTPL) flag in the parameter block of\nthe PROUT command. Relevant for 'register', 'register and ignore existing key' and\n'register and move' sub-commands.\n", "flag": "-Z", "long": "--param-aptpl" }, { "name": "-K --param-rk", "content": "specify the reservation key found in the parameter block of the PROUT command. RK is\nassumed to be hex (up to 8 bytes long). Default value is 0. This option is needed by\nmost PROUT sub-commands.\n", "flag": "-K", "long": "--param-rk" }, { "name": "-S --param-sark", "content": "specify the service action reservation key found in the parameter block of the PROUT\ncommand. SARK is assumed to be hex (up to 8 bytes long). Default value is 0. This op‐\ntion is needed by some PROUT sub-commands.\n", "flag": "-S", "long": "--param-sark" }, { "name": "-P --preempt", "content": "Preempt is a sub-command of the PROUT command. Preempts the existing persistent reser‐\nvation (identified by --param-sark=SARK) with the registration key that is registered\nfor this ITL nexus (identified by --param-rk=RK). If a new reservation is estab‐\nlished as a result of the preemption then the supplied --prout-type=TYPE is used as\nthe type for this new reservation.\n", "flag": "-P", "long": "--preempt" }, { "name": "-A --preempt-abort", "content": "Preempt and Abort is a sub-command of the PROUT command. Preempts the existing persis‐\ntent reservation (identified by --param-sark=SARK) with the registration key that is\nregistered for this ITL nexus (identified by --param-rk=RK). If a new reservation is\nestablished as a result of the preemption then the supplied --prout-type=TYPE is used\nas the type for this new reservation. ACA and other pending tasks are aborted.\n", "flag": "-A", "long": "--preempt-abort" }, { "name": "-T --prout-type", "content": "specify the PROUT command's 'type' argument. Required by the 'register-move', 're‐\nserve', 'release' and 'preempt (and abort)' sub-commands. Valid TYPE values: 1-> write\nexclusive, 3-> exclusive access, 5-> write exclusive - registrants only, 6-> exclusive\naccess - registrants only, 7-> write exclusive - all registrants, 8-> exclusive access\n- all registrants. Default value is 0 (which is an invalid type). Each \"persistent\nreservation type\" is explained in more detail in a subsection of that name in the read\nreservation section of the PRIN command (section 6.15.3.3 of SPC-4 revision 37).\n", "flag": "-T", "long": "--prout-type" }, { "name": "-s --read-full-status", "content": "Read Full Status is a sub-command of the PRIN command. For each registration with the\ngiven SCSI device, it lists the reservation key and associated information. Trans‐\nportIDs, if supplied in the response, are decoded.\n", "flag": "-s", "long": "--read-full-status" }, { "name": "-k --read-keys", "content": "Read Keys is a sub-command of the PRIN command. Lists all the reservation keys regis‐\ntered (i.e. registrations) with the given SCSI device. This is the default sub-command\nfor the SCSI PRIN command.\n", "flag": "-k", "long": "--read-keys" }, { "name": "-y --readonly", "content": "Open DEVICE read-only. May be useful with PRIN commands if there are unwanted side ef‐\nfects with the default read-write open. When given twice is interpreted as forcing a\nread-write open thus overriding the SGPERSISTINRDONLY environment variable if\npresent. See the ENVIRONMENT VARIABLES section for more.\n", "flag": "-y", "long": "--readonly" }, { "name": "-r --read-reservation", "content": "Read Reservation is a sub-command of the PRIN command. List information about the cur‐\nrent holder of the reservation on the DEVICE. If there is no current reservation this\nwill be noted. Information about the current holder of the reservation includes its\nreservation key, scope and type.\n", "flag": "-r", "long": "--read-reservation" }, { "name": "-s --read-status", "content": "same as --read-full-status.\n", "flag": "-s", "long": "--read-status" }, { "name": "-G --register", "content": "Register is a sub-command of the PROUT command. It has 3 different actions depending\non associated parameters. a) add a new registration with '--param-rk=0' and\n'--param-sark='; b) Change an existing registration with '--param-rk='\nand '--param-sark='; or c) Delete an existing registration with\n'--param-rk=' and '--param-sark=0'.\n", "flag": "-G", "long": "--register" }, { "name": "-I --register-ignore", "content": "Register and Ignore Existing Key is a sub-command of the PROUT command. Similar to\n--register except that when changing a reservation key the old key is not specified.\nThe '--param-sark=' option should also be given.\n", "flag": "-I", "long": "--register-ignore" }, { "name": "-M --register-move", "content": "register (another initiator) and move (the reservation held by the current initiator\nto that other initiator) is a sub-command of the PROUT command. It requires the\ntransportID of the other initiator. [The standard uses the term IT nexus but the\npoint to stress is that there are two initiators (the one sending this command and an‐\nother one) but only one logical unit.] The --prout-type=TYPE and --param-rk=RK op‐\ntions need to match that of the existing reservation while --param-sark=SARK option\nspecifies the reservation key of the new (i.e. destination) registration.\n", "flag": "-M", "long": "--register-move" }, { "name": "-Q --relative-target-port", "content": "relative target port identifier that reservation is to be moved to by PROUT 'register\nand move' sub-command. RTPI is assumed to be hex in the range 0 to ffff inclusive. De‐\nfaults to 0 .\n", "flag": "-Q", "long": "--relative-target-port" }, { "name": "-L --release", "content": "Release is a sub-command of the PROUT command. It releases the current persistent\nreservation. The --prout-type=TYPE and --param-rk=RK options, matching the reserva‐\ntion, must also be specified.\n", "flag": "-L", "long": "--release" }, { "name": "-z --replace-lost", "content": "Replace Lost Reservation is a sub-command of the PROUT command. It \"begins a recovery\nprocess for the lost persistent reservation that is managed by application clients\".\nIt also stops the device server terminating commands due to a lost persistent reserva‐\ntion. Options should be be '--param-rk=0' (or not given), '--param-sark=' and\n--prout-type=TYPE.\n", "flag": "-z", "long": "--replace-lost" }, { "name": "-c --report-capabilities", "content": "Report Capabilities is a sub-command of the PRIN command. It lists information about\nthe aspects of persistent reservations that the DEVICE supports.\n", "flag": "-c", "long": "--report-capabilities" }, { "name": "-R --reserve", "content": "Reserve is a sub-command of the PROUT command. It creates a new persistent reservation\n(if permitted). The --prout-type=TYPE and --param-rk=RK options must also be speci‐\nfied.\n", "flag": "-R", "long": "--reserve" }, { "name": "-X --transport-id", "content": "The TIDS argument can take one of several forms. It can be a comma (or single space)\nseparated list of ASCII hex bytes representing a single TransportID as defined in\nSPC-4. They are usually 24 bytes long apart from in iSCSI. The TIDS argument may be a\ntransport specific form (e.g. \"sas,5000c50005b32001\" is clearer than an equivalent to\nthe hex byte form: \"6,0,0,0,5,0,c5,0,5,b3,20,1\"). The TIDS argument may be \"-\" in\nwhich case one or more TransportIDs can be read from stdin. The TIDS argument may be\nof the form \"file=\" in which case one or more TransportIDs can be read from a\nfile called . See the \"TRANSPORT IDs\" section below for more information.\n", "flag": "-X", "long": "--transport-id" }, { "name": "-U --unreg", "content": "optional when the PROUT register and move sub-command is invoked. If given it will un‐\nregister the current initiator (IT nexus) after the other initiator has been regis‐\ntered and the reservation moved to it. When not given the initiator (IT nexus) that\nsent the PROUT command remains registered.\n", "flag": "-U", "long": "--unreg" }, { "name": "-v --verbose", "content": "print out cdb of issued commands prior to execution. If used twice prints out the pa‐\nrameter block associated with the PROUT command prior to its execution as well. If\nused thrice decodes given transportID(s) as well. To see the response to a PRIN com‐\nmand in low level form use the --hex option.\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "print out version string. Ignore all other parameters.\n\n-? output usage message. Ignore all other parameters.\n", "flag": "-V", "long": "--version" }, { "name": "TRANSPORT IDs", "content": "TransportIDs are used in persistent reservations to identify initiators. The format of a\nTransportID differs depending on the type of transport being used. Their format is described\nin SPC-4 (in draft revision 37 see section 7.6.4).\n\nA TransportID is required for the PROUT 'register and move' sub-command and the PROUT 'regis‐\nter' sub-command can have zero, one or more TransportIDs.\n\nWhen the --transport-id=TIDS option is given then the TIDS argument may be a comma (or single\nspace) separated list of ASCII hex bytes that represent a single TransportID as defined in\nSPC-4. Alternatively the TIDS argument may be a transport specific string starting with ei‐\nther \"fcp,\", \"spi,\", \"sbp,\", \"srp,\", \"iqn\", \"sas,\" or \"sop,\". The \"iqn\" form is an iSCSI\nqualified name. Apart from \"iqn\" the other transport specific leadin string may be given in\nupper case (e.g. \"FCP,\").\n\nThe \"fcp,\" form should be followed by 16 ASCII hex digits that represent an initiator's\nNPORTNAME (e.g. \"fcp,10000000C9F3A571\"). The \"spi,\" form should be followed by \",\" (both decimal numbers). The \"sbp,\" form should be\nfollowed by 16 ASCII hex digits that represent an initiator's EUI-64 name. The \"srp,\" form\nshould be followed by 32 ASCII hex digits that represent an initiator port identifier. The\n\"sas,\" form should be followed by 16 ASCII hex digits that represent an initiator's port SAS\naddress (e.g. \"sas,5000c50005b32001\"). The \"sop,\" form takes a hex number that represents a\nrouting id.\n\nThere are two iSCSI qualified name forms. The shorter form contains the iSCSI name of the\ninitiator port (e.g. \"iqn.5886.com.acme.diskarrays-sn-a8675309\"). The longer form adds the\ninitiator session id (ISID in hex) separated by \",i,0x\". For example\n\"iqn.5886.com.acme.diskarrays-sn-a8675309,i,0x1234567890ab\". On the command line to stop\npunctuation in an iSCSI name being (mis)-interpreted by the shell, putting the option argu‐\nment containing the iSCSI name in double quotes is advised. iSCSI names are encoded in UTF-8\nso if non (7 bit) ASCII characters appear in the iSCSI name on the command line, there will\nbe difficulties if they are not encoded in UTF-8. The locale can be changed temporarily by\nprefixing the command line invocation of sgpersist with \"LANG=enUS.utf-8\" for example.\n\nAlternatively the TIDS argument may specify a file (or pipe) from which one or more Trans‐\nportIDs may be read. If the TIDS argument is \"-\" then stdin (standard input) is read. If the\nTIDS argument is of the form \"file=\" then a file called is read. A valid SPC-4\nTransportID is built from the transport specific string outlined in the previous paragraphs.\nThe parsing of the data read is relatively simple. Empty lines are ignored. Everything from\nand including a \"#\" on a line is ignored. Leading spaces and tabs are ignored. There can be\none transportID per line. The transportID can either be a comma, space or tab separated list\nof ASCII hex bytes that represent a TransportID as defined in SPC-4. Padding with zero bytes\nto a minimum length of 24 bytes is performed if necessary. The transportID may also be trans‐\nport specific string type discussed above.\n\nIn SPC-3 the SPECIPT bit set to one and TransportIDs were allowed for the PROUT register\nand ignore existing key sub-command. In SPC-4 that is disallowed yielding a CHECK CONDITION\nstatus with and ILLEGAL REQUEST sense key and an additional sense code set to INVALID FIELD\nIN PARAMETER LIST.\n" } ] }, "NOTES": { "content": "In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6\nseries any SCSI device name (e.g. /dev/sdc, /dev/st1m or /dev/sg3) can be specified. For ex‐\nample \"sgpersist --read-keys /dev/sdb\" will work in the 2.6 series kernels.\n\nThe only scope for PROUT commands supported in the current draft of SPC-4 is \"LUSCOPE\".\nHence there seems to be no point in offering an option to set scope to another value.\n\nMost errors with the PROUT sub-commands (e.g. missing or mismatched --prout-type=TYPE) will\nresult in a RESERVATION CONFLICT status. This can be a bit confusing when you know there is\nonly one (active) initiator: the \"conflict\" is with the SPC standard, not another initiator.\n\nSome recent disks accept some PRIN and PROUT sub-commands when the media is stopped. One ex‐\nception was setting the APTPL flag (with the --param-aptpl option) during a key register op‐\neration, it complained if the disk one stopped. The error indicated it wanted the disk spun\nup and when that happened, the registration was successful.\n", "subsections": [] }, "EXAMPLES": { "content": "These examples use Linux device names. For suitable device names in other supported Operating\nSystems see the sg3utils(8) man page.\n\nDue to the various option defaults the simplest example executes the 'read keys' sub-command\nof the PRIN command:\n\nsgpersist /dev/sdb\n\nThis is the same as the following (long-winded) command:\n\nsgpersist --in --read-keys --device=/dev/sdb\n\nTo read the current reservation either the '--read-reservation' form or the shorter '-r' can\nbe used:\n\nsgpersist -r /dev/sdb\n\nTo register the new reservation key 0x123abc the following could be used:\n\nsgpersist --out --register --param-sark=123abc /dev/sdb\n\nGiven the above registration succeeds, to reserve the DEVICE (with type 'write exclusive')\nthe following could be used:\n\nsgpersist --out --reserve --param-rk=123abc\n--prout-type=1 /dev/sdb\n\nTo release the reservation the following can be given (note that the --param-rk and\n--prout-type arguments must match those of the reservation):\n\nsgpersist --out --release --param-rk=123abc\n--prout-type=1 /dev/sdb\n\nFinally to unregister a reservation key (and not effect other registrations which is what\n'--clear' would do) the command is a little surprising:\n\nsgpersist --out --register --param-rk=123abc /dev/sdb\n\nNow have a close look at the difference between the register and unregister examples above.\n\nAn example file that is suitably formatted to pass transportIDs via a '--trans‐\nport-id=file=transportids.txt' option can be found in the examples sub-directory of the\nsg3utils package. There is also a simple test script called sgpersisttst.sh in the same\ndirectory.\n\nThe above sequence of commands was tested successfully on a Seagate Savvio 10K.3 disk and a\n1200 SSD both of which have SAS interfaces.\n", "subsections": [] }, "EXIT STATUS": { "content": "The exit status of sgpersist is 0 when it is successful. Otherwise see the sg3utils(8) man\npage.\n", "subsections": [] }, "ENVIRONMENT VARIABLES": { "content": "Currently there is one recognised environment variable: SGPERSISTINRDONLY. If present and\nonly if a PRIN command has been selected then the given DEVICE is opened read-only (e.g. in\nUnix that is with the ORDONLY flag). See the --readonly option.\n", "subsections": [] }, "AUTHOR": { "content": "Written by Douglas Gilbert\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 2004-2018 Douglas Gilbert\nThis software is distributed under the GPL version 2. There is NO warranty; not even for MER‐\nCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "sg3utils(sg3utils), scsires(internet)\n\n\n\nsg3utils-1.43 June 2018 SGPERSIST(8)", "subsections": [] } } } }