. \" @(#)rscsi.1	1.5 09/11/15 Copyr 2000-2008 J. Schilling
. \"  Manual Seite fuer rscsi
. \"
.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a
.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o
.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u
.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A
.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O
.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U
.if t .ds s \\(*b
.if t .ds S SS
.if n .ds a ae
.if n .ds o oe
.if n .ds u ue
.if n .ds s sz
.TH RSCSI 1 "Release 3.0" "J\*org Schilling" "Schily\'s USER COMMANDS"
.SH NAME
rscsi \- remote generic SCSI transport protocol server
.SH SYNOPSIS
.B /opt/schily/sbin/rscsi

.SH DESCRIPTION
.IX  "rscsi command"  ""  "\fLrscsi\fP \(em remote generic SCSI transport protocol server"
.IX  "remote generic SCSI transport protocol server"  ""  "remote generic SCSI transport protocol server \(em \fLrscsi\fP"
The
.B rscsi
command is a
remote generic SCSI transport server program.
.B rscsi
is a program that is run locally on the machine with SCSI devices,
it is used by remote programs like
.BR cdrecord (1),
.BR cdda2wav (1),
.BR readcd (1),
and
.BR sformat (1)
that like to access SCSI devices
through an interprocess communication connection
via
.BR libscg .
.B rscsi
is normally started up with an
.BR rexec (3)
or
.BR rcmd (3)
call but it may also be connected via an internal pipe to an
.BR ssh (1)
session that was set up by the remote user.
.LP
The
.B rscsi
program accepts 
.BR scg_open ,
.BR scg_close ,
.B scg_cmd
and
similar requests that are all related to the interface of 
.BR libscg .
.B rscsi
performs the commands and then responds with a status indication.
.LP
The 
.B rscsi 
program is prepared to be installed as a 
.B user shell
in the passwd
file to create remote SCSI specific logins and security checking.
.LP
All requests are send to the
.B rscsi
program in 
.SM ASCII
and thus are byte order and machine independent.
.LP
All responses are send back in
.SM ASCII
and in one of the following two forms.
.LP
All successful commands (except for the "S" command that sends SCSI commands) have responses of
.IP
.BI A number\en
.LP
where
.I number
is the
.SM ASCII
representation of a decimal number that usually is the return
code of the corresponding system call or function.
.sp
All unsuccessful commands are responded to with
.IP
.BI E error-number \en error-message \en xerror-len\fB\en\fIxerror-txt
.LP
where
.I error-number
is one of the possible error
numbers described in
.BR intro (2),
and
.I error-message
is the corresponding error string as retrieved by
.BR strerror (3),
.I xerror-len
is the length of the additional error text 
.I xerror-txt
and may be 0. In case
.I xerror-len
is 0, no
.I xerror-txt
is send.
Note that a failed SCSI command that returned SCSI sense data counts as
a successful command and does not use the default error format.
.LP
.ne 15
The 
.B rscsi 
protocol implements the
following commands:
.RS
.br
.ne 7
.TP 12
.BI V what \en
Return the 
.B version 
for several instances of the software in the
.B rscsi
server.
The parameter
.B what
may have the following values:
.RS
.TP
.B 0
Return
.B SCG_VERSION
from
.B libscg
on the
.B rscsi
server.
This returns the version string for the low level SCSI transport adaptation layer.
.TP
.B 1
Return
.B SCG_AUTHOR
from
.B libscg
on the
.B rscsi
server.
This returns the author name for the low level SCSI transport adaptation layer.
.TP
.B 2
Return
.B SCG_SCCS_ID
from
.B libscg
on the
.B rscsi
server.
This returns the SCCS version string for the low level SCSI transport adaptation layer.
.TP
.B 20
Return
.B SCG_KVERSION
from
.B libscg
on the
.B rscsi
server.
This returns the version of kernel instance of the driver that is underneath the
low level SCSI transport adaptation layer.
.sp
This call may not be supported for all operating systems.
.PP
.sp
This command corresponds to the
.BR scg_version (3)
function from
.BR libscg .
.RE
.br
.ne 7
.TP
.BI O device \en
Open the specified SCSI
.IR device .
.sp
See the description of the
.B dev=
option in
.BR cdrecord (1)
for more information on possible values of the 
.I device
parameter.
.sp
If a device is already open, it is
closed before a new open is performed.
.sp
This command corresponds to the
.BR scg_open (3)
function from
.BR libscg .
.sp
The return value in case of success is 0.
.br
.ne 7
.TP
.BI C device \en
Close the currently open device or file.  The argument
.I device
is ignored.
.sp
This command corresponds to the
.BR scg_close (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_close (3)
function.
.br
.ne 7
.TP
.BI D size \en
Set up the maximum DMA size for the currently open SCSI device.
The
.I size
parameter is the desired DMA size in bytes.
.sp
This command corresponds to the
.BR scg_bufsize (3)
function from
.BR libscg .
.sp
The returned value is the actual DMA size that could be set up.
This value may be lower than the 
.I size
parameter.
.br
.ne 7
.TP
.BI M size \en
Allocate a buffer suitable for SCSI DMA transfers.
.sp
This command corresponds to the
.BR scg_getbuf (3)
function from
.BR libscg .
.sp
The returned value is the actual DMA size that could be set up.
This value may be lower than the 
.I size
parameter.
.br
.ne 7
.TP
.B F\en
Free a previously allocated buffer.
.sp
This command corresponds to the
.BR scg_freebuf (3)
function from
.BR libscg .
.sp
The return value in case of success is 0.
.br
.ne 7
.TP
.B N\en
Retrieve the maximum permitted value for the SCSI bus number.
.sp
This command corresponds to the
.BR scg_numbus (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_numbus (3)
function.
.br
.ne 7
.TP
.BI B busno \en chan \en
Checks whether there is a SCSI bus with a busnumber that is equal to
.IR busno .
The 
.I chan
parameter is currently ignored.
.sp
This command corresponds to the
.BR scg_havebus (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_havebus (3)
function.
.br
.ne 7
.TP
.BI T busno \en chan \en target\fB\en\fIlun\fB\en
Set the SCSI target address to
.IR busno ", " target ", " lun .
The parameter
.I chan
is currently ignored.
.sp
This command corresponds to the
.BR scg_settarget (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_havebus (3)
function.
.br
.ne 7
.TP
.B I\en
Retrieve the SCSI initiator ID for the current SCSI bus.
.sp
This command corresponds to the
.BR scg_initiator_id (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_initiator_id (3)
function.
.br
.ne 7
.TP
.B A\en
Check whether the current target is or may be an ATAPI device.
.sp
This command corresponds to the
.BR scg_isatapi (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_isatapi (3)
function.
.br
.ne 7
.TP
.BI R what \en
Perform a SCSI reset. The parameter
.I what
may have the following values:
.RS
.TP
0
Test whether a SCSI reset is supported as with the
.B SCG_RESET_NOP
parameter.
.TP
1
Perform a SCSI target reset as with the
.B SCG_RESET_TGT
parameter.
.TP
2
Perform a SCSI bus reset as with the
.B SCG_RESET_BUS
parameter.
.PP
.sp
This command corresponds to the
.BR scg_reset (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_reset (3)
function.
.RE
.br
.ne 7
.TP
.BI S count \en flags \en\fIcdb_len\fB\en\fIsense_len\fB\en\fItimeout\fB\en
Send a SCSI command to the currently selected target.
This command takes the following parameters:
.RS
.TP
.B 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 command descriptor block.
that is described above.
.TP
.B flags
The flags that apply to this SCSI command:
.RS
.TP
.B 1
Tell the kernel that the SCSI command will transfer data from the target to the host.
This corresponds to the flag value
.BR SCG_RECV_DATA .
.TP
.B 2
Tell the kernel to send the SCSI command with disconnect/reconnect enabled.
This corresponds to the flag value
.BR SCG_DISRE_ENA .
This flag is not supported on all platforms.
.TP
.B 4
Make the kernel silent on SCSI errors.
This corresponds to the flag value
.BR SCG_SILENT .
This flag is not supported on all platforms.
.TP
.B 8
Tell the kernel to retry the SCSI command in case of a retryable SCSI transport error.
This corresponds to the flag value
.BR SCG_CMD_RETRY .
This flag is not supported on all platforms.
.TP
.B 16
Tell the kernel to send the SCSI command with parity disabled.
This corresponds to the flag value
.BR SCG_NOPARITY .
This flag is not supported on all platforms.
.RE
.TP
.B cdb_len
The SCSI command descriptor length for this command.
The SCSI command descriptor has to be send with the correct length directly after the new line past the 
.B timeout
value. 
.TP
.B sense_len
The amount of sense data that is expected in return of a failed SCSI command that
produces SCSI sense data.
.TP
.B timeout
The timeout for the SCSI command in seconds.
Fractions of a second may be specified by sending a floating point number.
.PP
The reply for a SCSI command that could be send to the target is:
.sp
.BI A count \en error \en\fIerrno\fB\en\fIscb\fB\en\fIsense_count\fB\en
.TP
.B 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 mentioned above.
.TP
.B error
A SCSI error classification from one of the following values:
.RS
.sp
.ne 3
.TP
.B 0
No error occurred.
This value corresponds to the value
.B SCG_NO_ERROR .
.sp
.ne 3
.TP
.B 1
A retryable error occurred while trying to transport the SCSI command to the target.
This value corresponds to the value
.B SCG_RETRYABLE .
.sp
.ne 3
.TP
.B 2
A fatal error occurred while trying to transport the SCSI command to the target.
This value corresponds to the value
.B SCG_FATAL .
.sp
.ne 3
.TP
.B 3
A SCSI timeout occurred.
This value corresponds to the value
.B SCG_TIMEOUT .
.RE
.sp
.ne 3
.TP
.B errno
Any possible 
.B "UNIX errno
value for the SCSI command.
.sp
.ne 3
.TP
.B scb
The SCSI status byte
.sp
.ne 3
.TP
.B 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.
.sp
This command corresponds to the
.BR scg_cmd (3)
function from
.BR libscg .
.sp
The return value is the return value from the
.BR scg_cmd (3)
function.
.RE
.RE
.LP
Any other command causes
.B rscsi
to exit.
.SH FILES
.TP
/etc/default/rscsi
Default values can be set for the following options in /etc/default/rscsi.
For example:
.sp
.BR DEBUG= /tmp/rscsi.debug
.br
.BR USER= rscsi
.br
.BR ACCESS= "rscsi	myhost.mydomain.org	1	-1	3	0"
.sp
All keywords must be on the beginning of a line.
.RS
.TP
.B DEBUG
If you like to get debug information, set this to a file name where 
.B rscsi
should put debug information.
.TP
.B USER
The name of a user (local to the RSCSI server) that may use
the services of the
.B rscsi
server.
More than one
.BI USER= name
line is possible.
A line
.BR USER= *
grants access to all users.
.TP
.B ACCESS
This keyword is followed by six parameters separated by a TAB.
The
.B name 
of a user (local to the RSCSI server host) that may use
the services of the
.B rscsi
server followed by the 
.B "name of a host
from where operation is granted 
followed by a 
.B "SCSI device
specification that is made of
.B bus-number
.BR channel " (ignored for now)
.B target-id
and
.B lun
that specify a SCSI device that may be accessed if this 
.B ACCESS
line matches.
If one or more entries of the
.B bus-number
.B channel
.B target-id
.B lun
specification is set to -1, this matches any possible value
for the related part of the SCSI device specification.
More than one
.BI ACCESS= "name host SCSI-device"
line is possible.
.sp
If standard input of 
.B rscsi
is not a socket from a remote host, 
.B rscsi
will compare the 
.B "host entry 
from 
.B /etc/default/rscsi
with the following strings:
.RS
.TP 10
.B PIPE
If 
.B stdin
is a 
.SM UNIX 
pipe.
.sp
If you like to allow remote connections that use the
.B ssh
protocol, you need to use the word
.B PIPE
instead of the real hostname in the matching
.B ACCESS=
line.
.TP
.B ILLEGAL_SOCKET
If 
.B getpeername()
does not work for
.BR stdin .
.TP
.B NOT_IP
If 
.B getpeername()
works for
.B stdin
but is not connected to an internet socket.
.RE
.RE
.SH "SEE ALSO"
.BR cdrecord (1),
.BR cdda2wav (1),
.BR readcd (1),
.BR sformat (1),
.BR ssh (1),
.BR intro (2),
.BR open (2),
.BR close (2),
.BR read (2),
.BR write (2),
.BR ioctl (2),
.BR getpeername(3)
.BR rcmd (3),
.BR rexec (3),
.BR strerror (3)

.SH DIAGNOSTICS
All responses are send to the network connection.
They use the form described above.
.SH NOTES
.LP
The possibility to create a debug file by calling
.BI rscsi " file
has been disabled for security reasons.
If you like to debug
.B rscsi
edit
.B /etc/default/rscsi
and insert a 
.B DEBUG
entry.
.SH BUGS
.LP
None known.
.SH HISTORY
.LP
The 
.B rscsi
command has been developed by J\*org Schilling in June 2000. 

.SH AUTHOR
.nf
J\*org Schilling
Seestr. 110
D-13353 Berlin
Germany
.fi
.PP
Mail bugs and suggestions to:
.PP
.B
joerg.schilling@fokus.fraunhofer.de
or
.B
js@cs.tu-berlin.de
or
.B
joerg@schily.isdn.cs.tu-berlin.de
.br
.ne 7
.SH "INTERFACE STABILITY
The interfaces provided by 
.B rscsi
are designed for long term stability.
As
.B rscsi
depends on interfaces provided by the underlying operating system,
the stability of the interfaces offered by
.B rscsi
depends on the interface stability of the OS interfaces. 
Modified interfaces in the OS may enforce modified interfaces
in 
.BR rscsi .