Provided by: sg3-utils_1.17-2_i386 bug

NAME

       sg_persist - use the Persistent Reservation In and Out SCSI commands to
       manipulate registrations and reservations

SYNOPSIS

       sg_persist [<options>] [<scsi_device>]

DESCRIPTION

       This utility allows Persistent reservations  and  registrations  to  be
       queried  and  changed.  Persistent  reservations  and registrations are
       queried by sub-commands (called "service  actions"  in  SPC-3)  of  the
       Persistent  Reservation In (PRIN) SCSI command. Persistent reservations
       and  registrations  are  changed  by  sub-commands  of  the  Persistent
       Reservation Out (PROUT) SCSI command.

       It is relatively safe to query the state of Persistent reservations and
       registrations. With no options this utility defaults to the  READ  KEYS
       sub-command  of  the  PRIN  command.  Other  PRIN sub-commands are READ
       RESERVATION, REPORT CAPABILITIES and READ FULL STATUS.

       Before trying to change Persistent reservations and registrations users
       should  be  aware  of what they are doing! The relevant sections of the
       SCSI Primary Commands document (SPC-3 most recent  draft  revision  21d
       dated  14th February 2005) are sections 5.6 (general information), 6.11
       (for PRIN) and 6.12 (for PROUT). To safeguard against  accidental  use,
       the  ’--out’  option  must  be  given  when  a  PROUT sub-command (e.g.
       ’--register’) is used.

       The older SCSI Reserve  and  Release  commands  (both  6  and  10  byte
       variants)  are  not  supported  by  this utility. In SPC-3, Reserve and
       Release are deprecated, replaced  by  Persistent  Reservations.  See  a
       utility  called  ’scsires’  for support of the SCSI Reserve and Release
       commands.

       The <scsi_device> is required by all variants  of  this  utility  apart
       from  ’--help’  (’-h’).  The  <scsi_device>  can  be given either as an
       argument (typically but not  necessarily  the  last  one)  or  via  the
       ’--device=<scsi_device>’ (or ’-d <scsi_device’) option.

       SPC-3  does  not  use the term "sub-command". It uses the term "service
       action" for this and for part of a field’s name in the parameter  block
       associated  with  the  PROUT  command (i.e. "service action reservation
       key"). To lessen the potential confusion  the  term  "sub-command"  has
       been introduced.

OPTIONS

       --clear | -C
              Clear  is  a  sub-command  of the PROUT command. It releases the
              persistent reservation (if any)  and  clears  all  registrations
              from the device. It is required to supply a reservation key that
              is registered for this I_T_L nexus (identified by --param-rk).

       --device=<scsi_device> | -d <scsi_device>
              This utility needs to have a scsi_device to be  specified.  This
              can  either  be as an argument to ’--device’ or ’-d’ or just the
              first non-option argument.

       --help | -h
              output a usage message.

       --hex | -H
              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-3.

       --in | -i
              specify  that  a  Persistent  Reservation  In  SCSI  command  is
              required. This is the default.

       --out | -o
              specify  that  a  Persistent  Reservation  Out  SCSI  command is
              required.

       --no-inquiry | -n
              the default action is to do a standard INQUIRY SCSI 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.

       --param-alltgpt | -Y
              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.

       --param-aptpl | -Z
              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.

       --param-rk=<h> | -K <h>
              specify the reservation key found in the parameter block of  the
              PROUT  command.  Argument  is  assumed  to be hex (up to 8 bytes
              long). Default value is 0. This option is needed by  most  PROUT
              sub-commands.

       --param-sark=<h> | -S <h>
              specify   the  service  action  reservation  key  found  in  the
              parameter block of the PROUT command. Argument is assumed to  be
              hex  (up  to  8 bytes long).  Default value is 0. This option is
              needed by some PROUT sub-commands.

       --preempt | -P
              Preempt is a sub-command of  the  PROUT  command.  Preempts  the
              existing  persistent  reservation (identified by ’--param-sark’)
              with the registration key that  is  registered  for  this  I_T_L
              nexus  (identified  by  ’--param-rk’).  The associated ’--prout-
              type<h>’ option needs to match the type of the reservation.

       --preempt-abort | -A
              Preempt and  Abort  is  a  sub-command  of  the  PROUT  command.
              Preempts  the  existing  persistent  reservation  (identified by
              ’--param-sark’) with the registration key that is registered for
              this  I_T_L  nexus  (identified by ’--param-rk’). The associated
              ’--prout-type<h>’  option  needs  to  match  the  type  of   the
              reservation. ACA and other pending tasks are aborted.

       --prout-type=<h> | -T <h>
              specify  the  PROUT  command’s  ’type’ argument. Required by the
              ’register-move’, ’reserve’, ’release’ and ’preempt (and  abort)’
              sub-commands.   Valid   arguments:   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).

       --read-full-status | -s
              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.

       --read-keys | -k
              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  PRIN  SCSI
              command.

       --read-reservation | -r
              Read  Reservation  is  a  sub-command  of the PRIN command. List
              information about the current holder of the reservation  on  the
              given  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.

       --read-status | -s
              same as ’read-full-status’.

       --register | -G
              Register  is  a  sub-command  of  the  PROUT  command.  It has 3
              different actions depending on associated parameters. 1)  add  a
              new    registration    with    ’--param-rk=0’    and   ’--param-
              sark=<new_rk>’.  2)  Change  an   existing   registration   with
              ’--param-rk=<old_rk>’ and ’--param-sark=<new_rk>’.  3) Delete an
              existing registration with ’--param-rk=<old_rk>’  and  ’--param-
              sark=0’.

       --register-ignore | -I
              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 ’--prout-
              sark=<new_rk>’ option should also be given.

       --register-move | -M
              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 target.]  The ’--param-
              type=<h>’ and ’--param-rk=<h>’ options need to match that of the
              existing  reservation  while ’--param-sark=<h>’ option specifies
              the reservation key of the new (i.e. destination)  registration.

       --relative-target-port=<h> | -Q <h>
              relative  target  port number that reservation is to be moved to
              by PROUT ’register and move’ sub-command. <h> is assumed  to  be
              hex in the range 0 to ffff inclusive. Defaults to 0 .

       --release | -L
              Release  is  a sub-command of the PROUT command. It releases the
              current  persistent  reservation.  The  ’--prout-type=<h>’   and
              ’--prout-rk=<h>’ options, matching the reservation, must also be
              specified.

       --report-capabilities | -c
              Report Capabilities is a sub-command of  the  PRIN  command.  It
              lists  information  about the aspects of persistent reservations
              that the given device supports.

       --reserve | -R
              Reserve is a sub-command of the PROUT command. It creates a  new
              persistent  reservation  (if  permitted). The ’--prout-type=<h>’
              and ’--prout-rk=<h>’ options must also be specified.

       --transport-id=<h>,<h>... | -X <h>,<h>...
              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 on the command  line.   The  argument  is  a  comma
              separated  list  of  hex  numbers  representing the bytes of the
              transportID. The list of hex numbers will  be  padded  out  with
              zeroes to 24 bytes which is the minimum length of a transportID.
              A transportID longer than 24 bytes (e.g. for  iSCSI)  is  padded
              with zeroes so its length is a multiple of 4.

       --transport-id=- | -X -
              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 zeroes
              to  24  bytes  which  is  the minimum length of a transportID. A
              transportID longer than 24 bytes (e.g. for iSCSI) is padded with
              zeroes so its length is a multiple of 4.

       --unreg | -U
              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.

       --verbose | -v
              print  out  cdb  of  issued commands prior to execution. If used
              twice prints out the parameter block associated with  the  PROUT
              command  prior  to its execution as well. If used thrice decodes
              given transportID(s) as well. To see  the  response  to  a  PRIN
              command in low level form use the ’--hex’ option.

       --version | -V
              print out version string. Ignore all other parameters.

       -?     output usage message. Ignore all other parameters.

NOTES

       In  the  2.4  series  of  Linux kernels the given device must be a SCSI
       generic (sg) device. In the 2.6  series  any  SCSI  device  name  (e.g.
       /dev/sdc,  /dev/st1m  or  /dev/sg3)  can  be  specified.   For  example
       "sg_persist --read-keys /dev/sda" will work in the 2.6 series  kernels.

       The  only  scope  for  PROUT commands supported in the current draft of
       SPC-3 is "LU_SCOPE". Hence there seems to be no point  in  offering  an
       option to set scope to another value.

       Most  errors  with  the  PROUT sub-commands (e.g. missing or mismatched
       ’--prout-type=<h>’  option)  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.

EXAMPLES

       Due  to  defaults  the  simplest  example executes the ’read keys’ sub-
       command of the PRIN command:

          sg_persist /dev/sda

       This is the same as the following (long-winded) command:

          sg_persist --in --read-keys --device=/dev/sda

       To read the current reservation either the ’--read-reservation’ form or
       the shorter ’-r’ can be used:

          sg_persist -r /dev/sda

       To  register  the  new  reservation key 0x123abc the following could be
       used:

          sg_persist --out --register --param-sark=123abc /dev/sda

       Given the above registration succeeds,  to  reserve  the  given  device
       (with type ’write exclusive’) the following could be used:

          sg_persist --out --reserve --param-rk=123abc
                     --prout-type=1 /dev/sda

       To  release  the  reservation the following can be given (note that the
       --param-rk  and  --prout-type  arguments  must  match  those   of   the
       reservation):

          sg_persist --out --release --param-rk=123abc
                     --prout-type=1 /dev/sda

       Finally   to  unregister  a  reservation  key  (and  not  effect  other
       registrations which is what ’--clear’ would do) the command is a little
       surprising:

          sg_persist --out --register --param-rk=123abc /dev/sda

       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 the
       ’-transport-id=-’  option can be found in the examples sub-directory of
       the sg3_utils package. That file is called ’transport_ids.txt’.

AUTHOR

       Written by Doug Gilbert

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2004 Douglas Gilbert
       This software is distributed under the  GPL  version  2.  There  is  NO
       warranty;  not  even  for  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.

SEE ALSO

       scsires(internet), examples/sg_persist_tst.sh(sg3_utils tarball)