Schily's USER COMMANDS                                   RSCSI(1)


NAME

     rscsi - remote generic SCSI transport protocol server


SYNOPSIS

     /opt/schily/sbin/rscsi


DESCRIPTION

     The rscsi command is a remote generic SCSI transport  server
     program.   rscsi  is  a  program  that is run locally on the
     machine with SCSI devices, it is  used  by  remote  programs
     like  cdrecord(1),  cdda2wav(1),  readcd(1),  and sformat(1)
     that like to access SCSI  devices  through  an  interprocess
     communication  connection  via  libscg.   rscsi  is normally
     started up with an rexec(3) or rcmd(3) call but it may  also
     be  connected via an internal pipe to an ssh(1) session that
     was set up by the remote user.

     The rscsi program accepts scg_open, scg_close,  scg_cmd  and
     similar  requests  that  are all related to the interface of
     libscg.  rscsi performs the commands and then responds  with
     a status indication.

     The rscsi program is prepared to  be  installed  as  a  user
     shell  in  the  passwd  file  to create remote SCSI specific
     logins and security checking.

     All requests are send to the rscsi program in ASCII and thus
     are byte order and machine independent.

     All responses are send back in ASCII and in one of the  fol-
     lowing two forms.

     All successful commands (except for  the  "S"  command  that
     sends SCSI commands) have responses of

          Anumber\n

     where number is the ASCII representation of a decimal number
     that  usually is the return code of the corresponding system
     call or function.

     All unsuccessful commands are responded to with

          Eerror-number\nerror-message\nxerror-len\nxerror-txt

     where error-number is one  of  the  possible  error  numbers
     described  in intro(2), and error-message is the correspond-
     ing error string as retrieved by strerror(3), xerror-len  is
     the  length  of the additional error text xerror-txt and may
     be 0. In case xerror-len is 0, no xerror-txt is send.   Note
     that  a  failed  SCSI  command that returned SCSI sense data

Joerg Schilling     Last change: Release 3.0                    1


Schily's USER COMMANDS                                   RSCSI(1)

     counts as a successful command and does not use the  default
     error format.

     The rscsi protocol implements the following commands:

          Vwhat\n     Return the version for several instances of
                      the  software  in  the  rscsi  server.  The
                      parameter  what  may  have  the   following
                      values:

                      0    Return SCG_VERSION from libscg on  the
                           rscsi  server.   This returns the ver-
                           sion string for  the  low  level  SCSI
                           transport adaptation layer.

                      1    Return SCG_AUTHOR from libscg  on  the
                           rscsi server.  This returns the author
                           name for the low level SCSI  transport
                           adaptation layer.

                      2    Return SCG_SCCS_ID from libscg on  the
                           rscsi  server.   This returns the SCCS
                           version string for the low level  SCSI
                           transport adaptation layer.

                      20   Return SCG_KVERSION from libscg on the
                           rscsi  server.   This returns the ver-
                           sion of kernel instance of the  driver
                           that  is underneath the low level SCSI
                           transport adaptation layer.

                           This call may not be supported for all
                           operating systems.

                      This    command    corresponds    to    the
                      scg_version(3) function from libscg.

          Odevice\n   Open the specified SCSI device.

                      See the description of the dev=  option  in
                      cdrecord(1)  for more information on possi-
                      ble values of the device parameter.

                      If a device is already open, it  is  closed
                      before a new open is performed.

                      This command corresponds to the scg_open(3)
                      function from libscg.

                      The return value in case of success is 0.

Joerg Schilling     Last change: Release 3.0                    2


Schily's USER COMMANDS                                   RSCSI(1)

          Cdevice\n   Close the currently open  device  or  file.
                      The argument device is ignored.

                      This    command    corresponds    to    the
                      scg_close(3) function from libscg.

                      The return value is the return  value  from
                      the scg_close(3) function.

          Dsize\n     Set  up  the  maximum  DMA  size  for   the
                      currently   open  SCSI  device.   The  size
                      parameter is the desired DMA size in bytes.

                      This    command    corresponds    to    the
                      scg_bufsize(3) function from libscg.

                      The returned value is the actual  DMA  size
                      that  could  be  set up.  This value may be
                      lower than the size parameter.

          Msize\n     Allocate a buffer  suitable  for  SCSI  DMA
                      transfers.

                      This    command    corresponds    to    the
                      scg_getbuf(3) function from libscg.

                      The returned value is the actual  DMA  size
                      that  could  be  set up.  This value may be
                      lower than the size parameter.

          F\n         Free a previously allocated buffer.

                      This    command    corresponds    to    the
                      scg_freebuf(3) function from libscg.

                      The return value in case of success is 0.

          N\n         Retrieve the maximum  permitted  value  for
                      the SCSI bus number.

                      This    command    corresponds    to    the
                      scg_numbus(3) function from libscg.

                      The return value is the return  value  from
                      the scg_numbus(3) function.

          Bbusno\nchan\n
                      Checks whether there is a SCSI bus  with  a
                      busnumber that is equal to busno.  The chan
                      parameter is currently ignored.

                      This    command    corresponds    to    the

Joerg Schilling     Last change: Release 3.0                    3


Schily's USER COMMANDS                                   RSCSI(1)

                      scg_havebus(3) function from libscg.

                      The return value is the return  value  from
                      the scg_havebus(3) function.

          Tbusno\nchan\ntarget\nlun\n
                      Set the SCSI target address to busno,  tar-
                      get,  lun.  The parameter chan is currently
                      ignored.

                      This    command    corresponds    to    the
                      scg_settarget(3) function from libscg.

                      The return value is the return  value  from
                      the scg_havebus(3) function.

          I\n         Retrieve the  SCSI  initiator  ID  for  the
                      current SCSI bus.

                      This    command    corresponds    to    the
                      scg_initiator_id(3) function from libscg.

                      The return value is the return  value  from
                      the scg_initiator_id(3) function.

          A\n         Check whether the current target is or  may
                      be an ATAPI device.

                      This    command    corresponds    to    the
                      scg_isatapi(3) function from libscg.

                      The return value is the return  value  from
                      the scg_isatapi(3) function.

          Rwhat\n     Perform a SCSI reset.  The  parameter  what
                      may have the following values:

                      0    Test whether a SCSI reset is supported
                           as with the SCG_RESET_NOP parameter.

                      1    Perform a SCSI target  reset  as  with
                           the SCG_RESET_TGT parameter.

                      2    Perform a SCSI bus reset as  with  the
                           SCG_RESET_BUS parameter.

                      This    command    corresponds    to    the
                      scg_reset(3) function from libscg.

                      The return value is the return  value  from
                      the scg_reset(3) function.

Joerg Schilling     Last change: Release 3.0                    4


Schily's USER COMMANDS                                   RSCSI(1)

          Scount\nflags\ncdb_len\nsense_len\ntimeout\n
                      Send  a  SCSI  command  to  the   currently
                      selected  target.   This  command takes the
                      following parameters:

                      count
                           The DMA count for this command. If the
                           command  is  a  command that transfers
                           data to the target, the  related  data
                           is  send  directly after the SCSI com-
                           mand  descriptor   block.    that   is
                           described above.

                      flags
                           The flags that apply to this SCSI com-
                           mand:

                           1    Tell the  kernel  that  the  SCSI
                                command  will  transfer data from
                                the target  to  the  host.   This
                                corresponds  to  the  flag  value
                                SCG_RECV_DATA.

                           2    Tell the kernel to send the  SCSI
                                command with disconnect/reconnect
                                enabled.  This corresponds to the
                                flag  value  SCG_DISRE_ENA.  This
                                flag  is  not  supported  on  all
                                platforms.

                           4    Make the kernel  silent  on  SCSI
                                errors.   This corresponds to the
                                flag value SCG_SILENT.  This flag
                                is  not  supported  on  all plat-
                                forms.

                           8    Tell the kernel to retry the SCSI
                                command  in  case  of a retryable
                                SCSI   transport   error.    This
                                corresponds  to  the  flag  value
                                SCG_CMD_RETRY.  This flag is  not
                                supported on all platforms.

                           16   Tell the kernel to send the  SCSI
                                command   with  parity  disabled.
                                This  corresponds  to  the   flag
                                value SCG_NOPARITY.  This flag is
                                not supported on all platforms.

                      cdb_len
                           The SCSI command descriptor length for
                           this   command.    The   SCSI  command

Joerg Schilling     Last change: Release 3.0                    5


Schily's USER COMMANDS                                   RSCSI(1)

                           descriptor has to  be  send  with  the
                           correct  length directly after the new
                           line past the timeout value.

                      sense_len
                           The  amount  of  sense  data  that  is
                           expected  in  return  of a failed SCSI
                           command that produces SCSI sense data.

                      timeout
                           The timeout for the  SCSI  command  in
                           seconds.  Fractions of a second may be
                           specified by sending a floating  point
                           number.

                      The reply for a SCSI command that could  be
                      send to the target is:

                      Acount\nerror\nerrno\nscb\nsense_count\n

                      count
                           The DMA count  of  any  data  returned
                           from  the  target.   If  this count is
                           nonzero,  the  data   is   send   back
                           directly  after  the  reply block men-
                           tioned above.

                      error
                           A SCSI error classification  from  one
                           of the following values:

                           0    No error  occurred.   This  value
                                corresponds    to    the    value
                                SCG_NO_ERROR .

                           1    A retryable error occurred  while
                                trying to transport the SCSI com-
                                mand to the target.   This  value
                                corresponds    to    the    value
                                SCG_RETRYABLE .

                           2    A fatal error occurred while try-
                                ing to transport the SCSI command
                                to  the   target.    This   value
                                corresponds    to    the    value
                                SCG_FATAL .

Joerg Schilling     Last change: Release 3.0                    6


Schily's USER COMMANDS                                   RSCSI(1)

                           3    A SCSI  timeout  occurred.   This
                                value  corresponds  to  the value
                                SCG_TIMEOUT .

                      errno
                           Any possible UNIX errno value for  the
                           SCSI command.

                      scb  The SCSI status byte

                      sense_count
                           The sense count returned for the  SCSI
                           command.   The SCSI sense data is send
                           back directly after any possible  SCSI
                           DMA data received from the target.

                           This  command   corresponds   to   the
                           scg_cmd(3) function from libscg.

                           The return value is the  return  value
                           from the scg_cmd(3) function.

     Any other command causes rscsi to exit.


FILES

     /etc/default/rscsi
          Default values can be set for the following options  in
          /etc/default/rscsi.  For example:

          DEBUG=/tmp/rscsi.debug
          USER=rscsi
          ACCESS=rscsi   myhost.mydomain.org 1    -1   3    0

          All keywords must be on the beginning of a line.

          DEBUG
               If you like to get debug information, set this  to
               a  file name where rscsi should put debug informa-
               tion.

          USER The name of a user (local  to  the  RSCSI  server)
               that  may  use  the  services of the rscsi server.
               More than one USER=name line is possible.  A  line
               USER=* grants access to all users.

          ACCESS
               This  keyword  is  followed  by   six   parameters
               separated  by a TAB.  The name of a user (local to
               the RSCSI server host) that may use  the  services

Joerg Schilling     Last change: Release 3.0                    7


Schily's USER COMMANDS                                   RSCSI(1)

               of the rscsi server followed by the name of a host
               from where operation is granted followed by a SCSI
               device  specification  that  is made of bus-number
               channel (ignored for now) target-id and  lun  that
               specify a SCSI device that may be accessed if this
               ACCESS line matches.  If one or  more  entries  of
               the bus-number channel target-id lun specification
               is set to -1, this matches any possible value  for
               the related part of the SCSI device specification.
               More than one ACCESS=name host SCSI-device line is
               possible.

               If standard input of rscsi is not a socket from  a
               remote  host,  rscsi  will  compare the host entry
               from   /etc/default/rscsi   with   the   following
               strings:

               PIPE      If stdin is a UNIX pipe.

                         If you like to allow remote  connections
                         that  use  the ssh protocol, you need to
                         use the word PIPE instead  of  the  real
                         hostname in the matching ACCESS= line.

               ILLEGAL_SOCKET
                         If  getpeername()  does  not  work   for
                         stdin.

               NOT_IP    If getpeername() works for stdin but  is
                         not connected to an internet socket.


SEE ALSO

     cdrecord(1),  cdda2wav(1),  readcd(1),  sformat(1),  ssh(1),
     intro(2),  open(2),  close(2),  read(2), write(2), ioctl(2),
     getpeername(3) rcmd(3), rexec(3), strerror(3)


DIAGNOSTICS

     All responses are send to the network connection.  They  use
     the form described above.


NOTES

     The possibility to create a debug file by calling rscsi file
     has  been  disabled  for  security  reasons.  If you like to
     debug rscsi  edit  /etc/default/rscsi  and  insert  a  DEBUG
     entry.


BUGS

     None known.


HISTORY


Joerg Schilling     Last change: Release 3.0                    8


Schily's USER COMMANDS                                   RSCSI(1)

     The rscsi command has been developed by Joerg  Schilling  in
     June 2000.


AUTHOR

     Joerg Schilling
     Seestr. 110
     D-13353 Berlin
     Germany

     Mail bugs and suggestions to:

     joerg.schilling@fokus.fraunhofer.de or js@cs.tu-berlin.de or
     joerg@schily.isdn.cs.tu-berlin.de


INTERFACE STABILITY

     The interfaces provided by rscsi are designed for long  term
     stability.   As  rscsi depends on interfaces provided by the
     underlying operating system, the stability of the interfaces
     offered  by  rscsi depends on the interface stability of the
     OS interfaces. Modified interfaces in  the  OS  may  enforce
     modified interfaces in rscsi.

Joerg Schilling     Last change: Release 3.0                    9


Man(1) output converted with man2html


FhG Schily's Home VED powered