RSCSI(1)

📦
version 2022.10.16 · 2 versions
, in opensuse-leap 16.0

🎀 NAME 🎀

rscsi — remote generic SCSI transport protocol server. This is rscsi(1) from Schily´s USER COMMANDS, and yes bestie, it's giving low-level SCSI realness. 💅

✨ SYNOPSIS ✨

/opt/schily/sbin/rscsi

💖 DESCRIPTION 💖

Okay so picture this: rscsi is a remote generic SCSI transport server program. It runs locally on the machine that actually has the SCSI devices, and it's the bestie that remote programs like cdrecord(1), cdda2wav(1), readcd(1), and sformat(1) call when they want 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. It is also prepared to be installed as a user shell in the passwd file, so you can create remote SCSI specific logins and do security checking. 👑

All requests are sent to the rscsi program in ASCII, which means byte order and machine independent — no cap, it just works across machines. All responses are sent back in ASCII too, in one of the following 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 corresponding 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 sent. 🫶 Note that a failed SCSI command that returned SCSI sense data counts as a successful command and does not use the default error format. Important vibe check!

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 version 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 version 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 possible 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.
  • 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 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, target, 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.
  • 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 command descriptor block. that is described above.
    • flags — The flags that apply to this SCSI command:
      • 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 platforms.
      • 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 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
error
errno
scb
sense_count

Okay bestie, here's what each of those fields is actually telling you 💅

  • count — the DMA count of any data that came back from the target. And here's the tea: if this count is nonzero, that data gets sent back directly after the reply block we just described. So like, right on its heels. 🫶
  • error — a SCSI error classification, and it's always one of these four values:
    • 0 — no error happened at all. This one corresponds to the value SCG_NO_ERROR. ✨
    • 1 — a retryable error happened while trying to transport the SCSI command to the target. This corresponds to the value SCG_RETRYABLE.
    • 2 — a fatal error happened while trying to transport the SCSI command to the target. This corresponds to the value SCG_FATAL. 😭
    • 3 — a SCSI timeout happened. This corresponds to the value SCG_TIMEOUT.
  • errno — any possible UNIX errno value for the SCSI command.
  • scb — the SCSI status byte. That's it, that's the whole field. 🎀
  • sense_count — the sense count returned for the SCSI command. The SCSI sense data gets sent back directly after any possible SCSI DMA data received from the target.

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

And the return value? Yeah, it's the return value from the scg_cmd(3) function. No cap.

Any other command causes rscsi to exit. Literally just dips. 💀

🌸 FILES 🌸

  • /etc/default/rscsi — default values can be set here for the following options. 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. (Yes, that's a real rule, do not come for me.)

  • DEBUG — if you like to get debug information, set this to a file name where rscsi should put debug information. 🐛
  • 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, so go off. And a line USER=* grants access to all users. 👑
  • ACCESS — this keyword is followed by six parameters separated by a TAB. It's the name of a user (local to the RSCSI server host) that may use the services of the rscsi server, followed by the name of a host from where operation is granted, followed by a SCSI device specification. That spec is made of bus-number, channel (ignored for now 🙈), target-id and lun, and it specifies 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, then it matches any possible value for the related part of the SCSI device specification. Wildcard energy. ✨ More than one ACCESS=name host SCSI-device line is possible.

Now, 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. And listen: 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. iykyk 🫶
  • 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. That's the whole thing, bestie — the replies just vibe in the format we already covered. 🌈

🎀 NOTES 🎀

So the possibility to create a debug file by calling rscsi file has been disabled for security reasons. 🚨 Like, gone. If you like to debug rscsi, edit /etc/default/rscsi and insert a DEBUG entry instead. That's the way now.

🍓 BUGS 🍓

None currently known. Iconic behaviour, honestly.

Mail bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues.

The mailing list archive may be found at:

https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de

⭐ HISTORY ⭐

The rscsi command was written by Joerg Schilling in June 2000 and is now maintained by the schilytools project authors. A legend. 👑

🌸 AUTHOR 🌸

Joerg Schilling and the schilytools project authors.

🔥 INTERFACE STABILITY 🔥

The interfaces provided by rscsi are designed for long term stability. But — and this is the important part — since 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. So like, not our fault if the OS switches things up on us. 😭

🧚 SOURCE DOWNLOAD 🧚

The source code for rscsi is included in the schilytools project and may be retrieved from the schilytools project at Codeberg at

https://codeberg.org/schilytools/schilytools

The download directory is

https://codeberg.org/schilytools/schilytools/releases

Okay that's the whole page, bestie — go forth and serve some SCSI 💅✨ Written by Joerg Schilling, dated 2022/09/09, and it's the RSCSI(1) man page, mwah 🫶🎀

📦 where this page comes from