--- name: "rmt-star" section: "8" platform: "linux" package: "star" version: "1.5a67-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/rmt-star/8" --- # rmt-star(8) remote magnetic tape protocol server ## NAME rmt - remote magnetic tape protocol server ## SYNOPSIS **/opt/schily/sbin/rmt**\ **/etc/rmt** ## DESCRIPTION This is the description of the enhanced **Schily** version of the **rmt** remote tape server program. **rmt** is a program used by programs like **star** and **ufsdump** that like to access remote magnetic tape drives and files through an interprocess communication connection. **rmt** is normally started up with an [**rexec**(3)](/rexec/3.md) or [**rcmd**(3)](/rcmd/3.md) call. The **rmt** program accepts **open**, **close**, **read**, **write** and **seek** requests as well as requests that are specific to magnetic tapes. **rmt** performs the commands and then responds with a status indication. This version of the rmt server gives full compatibility to the original BSD version, the enhanced Sun version and the enhanced GNU version. In addition to the Sun and GNU enhancements, it implements further abstractions for better cross platform compliance. It supports best speed and best compliance even when server and client code are running on different platforms. It is prepared to be installed as a user shell in the passwd file to create remote tape specific logins and security checking. To use the enhanced compatibility features, you need to either use the remote tape client code from **star** which is available in **librmt** or reimplement it's features. All responses are send back in ASCII and in one of the following two forms. Successful commands have responses of - **A***number\\n* where *number* is the ASCII representation of a decimal number that usually is the return code of the corresponding system call. Unsuccessful commands are responded to with - **E***error-number***\\n***error-message***\\n** where *error-number* is one of the possible error numbers described in [**intro**(2)](/intro/2.md), and *error-message* is the corresponding error string as retrieved by [**strerror**(3)](/strerror/3.md). The protocol implements the following commands: - **O***device***\\n***mode***\\n** - **O***device***\\n***mode symbolic\_mode***\\n** Open the specified *device* or file using the indicated *mode*. *device* is a full path name, and *mode* is an ASCII representation of a decimal number suitable for being passed as second parameter to [**open**(2)](/open/2.md). A variant of the **open** command includes the **symbolic\_mode** string which is a **GNU** extension. If both, *mode* and *symbolic\_mode* are present, they are separated by a space character; *symbolic\_mode* appears on the same line as the numeric mode. It is send using the same notation as used in a C source (e.g. **O\_RDWR\|O\_CREAT**). If the *symbolic\_mode* is send to the server, the numeric **mode** is ignored. The symbolic notation allows to send the expected open mode over the wire, using a system independent method. This is needed because different operating systems usually define all bits in a different way. An exception are the lowest two bits. The lowest two bits allow to code *O\_RCONLY*,*O\_WRONLY* and *O\_RDWR*. To prevent unexpected behavior, **rmt** masks the numeric open mode with **0x03** before using it as argument to the [**open**(2)](/open/2.md) call. If you need more bits in the second parameter ot [**open**(2)](/open/2.md), you need to use the symbolic mode. If no file */etc/default/rmt* exists, only filenames starting with /dev/ are accepted for security reasons. If a device is already open, it is closed before a new open is performed. A **RMT protocol VERSION 1** client should issue a\ **I***-1***\\n***0\\n*\ command just after opening a file or device. This is needed to tell the server that the client is aware of the official order of the *mt\_op* codes in the range 0..7 and that is maps deviating values to the official ones.\ - **C***device***\\n** Close the currently open device or file. The argument *device* is ignored.\ - **R***count***\\n** Read *count* bytes of data from the open device or file. **rmt** performs the requested [**read**(2)](/read/2.md) operation and responds with **A***count-read\\n* if the read operation was successful; otherwise an error in standard format is returned. If the read operation was successful, the data read is sent directly after the response described above.\ - **W***count***\\n** Write data to the open device or file. After reading the command specification, **rmt** reads *count* bytes from the network connection and aborts if a premature EOF is encountered. The return value from the [**write**(2)](/write/2.md) operation is returned as reply.\ - **L***whence***\\n***offset***\\n** Perform an [**lseek**(2)](/lseek/2.md) operation on the open device or file using the specified parameters. The return value from the [**lseek**(2)](/lseek/2.md) operation is returned as reply. On large file aware operating systems, **rmt** will correctly handle large [**lseek**(2)](/lseek/2.md) requests.\ - **S** The old non-portable status call. This call should not be used anymore, it has been replaced by the new **RMT protocol version 1** extended status call below. If the currently open device is a magnetic tape, return the magnetic tape status, as obtained with a **MTIOCGET** **ioctl** call. If the open device is not a magnetic tape, an error is returned. If the **MTIOCGET** operation was successful, an “ack” is sent with the size of the status buffer, then the status buffer is sent. As the status buffer is sent in binary, this command it considered outdated. Please use the extended status command instead. This command is not terminated by a new-line.\ - **s***sub-command* The new portable status call. This command is part of the **RMT protocol version 1**. If the currently open device is a magnetic tape, return a single specified member of the magnetic tape status structure, as obtained with a **MTIOCGET** **ioctl** call. If the open device is not a magnetic tape, an error is returned. If the **MTIOCGET** operation was successful, the numerical value of the structure member is returned in decimal. The following sub commands are supported: - T return the content of the structure member **mt\_type** which contains the type of the magnetic tape device.\ - D return the content of the structure member **mt\_dsreg** which contains the “drive status register”.\ - E return the content of the structure member **mt\_erreg** which contains the “error register”. This structure member must be retrieved first because it is cleared after each **MTIOCGET** **ioctl** call. The **librmt** will always retrieve the member **mt\_erreg** first when it is told to retrieve a complete status structure.\ - R return the content of the structure member **mt\_resid** which contains the residual count of the last I/O.\ - F return the content of the structure member **mt\_fileno** which contains the block number of the current tape position.\ - B return the content of the structure member **mt\_blkno** which contains the block number of the current tape position.\ - f return the content of the structure member **mt\_flags** which contains MTF\_ flags from the driver.\ - b return the content of the structure member **mt\_bf** which contains the optimum blocking factor. This command is not terminated with a new-line. - **I***operation***\\n***count***\\n** Perform a **MTIOCOP** [**ioctl**(2)](/ioctl/2.md) command using the specified parameters. The parameters are interpreted as the ASCII representations of the decimal values to place in the *mt\_op* and *mt\_count* fields of the structure used in the **ioctl** call. When the operation is successful the return value is the *count* parameter. Only Opcodes 0..7 are unique across different architectures. But as in many cases **Linux** does not even follow this rule. If we know that we have been called by a **RMT protocol VERSION 1** client, we may safely assume that the client is not using **Linux** mapping over the wire but the standard mapping described below: - \-1 Retrieve the version number of the **rmt** server and tell the server that the client is aware of the official order of the **MTIOCOP** [**ioctl**(2)](/ioctl/2.md) opcodes in the range 0..7. Local *mt\_op* codes must be remapped to the official values before sending them over the wire. The answer of the current version of **rmt** is 1. Old **rmt** implementations send an error code back when this command is used. Future **rmt** implementations with further enhancements will send an answer with a value \> 1. - 0 Issue a **MTWEOF** command (write *count* end-of-file records). - 1 Issue a **MTFSF** command (forward space over *count* file marks). - 2 Issue a **MTBSF** command (backward space over *count* file marks). - 3 Issue a **MTFSR** command (forward space *count* inter-record gaps). - 4 Issue a **MTBSR** command (backward space *count* inter-record gaps). - 5 Issue a **MTREW** command (rewind). - 6 Issue a **MTOFFL** command (rewind and put the drive off-line). - 7 Issue a **MTNOP** command (no operation, set status only). - **i***operation***\\n***count***\\n** Perform a **MTIOCOP** [**ioctl**(2)](/ioctl/2.md) command using the specified parameters. This command is a **RMT protocol VERSION 1** extension and implements support for commands beyond MTWEOF..MTNOP (0..7). The parameters are interpreted as the ASCII representations of the decimal values described below. They are converted into the local values *mt\_op* and *mt\_count* fields of the structure used in the **ioctl** call according to the actual values found in \. When the operation is successful the return value is the *count* parameter. - 0 Issue a **MTCACHE** command (switch cache on). - 1 Issue a **MTNOCACHE** command (switch cache off). - 2 Issue a **MTRETEN** command (retension the tape). - 3 Issue a **MTERASE** command (erase the entire tape). - 4 Issue a **MTEOM** command (position to end of media). - 5 Issue a **MTNBSF** command (backward space *count* files to BOF). - **v***\\n* Return the version of the **rmt** server. This is currently the decimal number 1. Any other command causes **rmt** to exit. ## FILES - /etc/default/rmt Default values can be set for the following options in /etc/default/rmt. For example: **DEBUG=**/tmp/rmt.debug\ **USER=**tape\ **ACCESS=**tape myhost.mydomain.org /dev/rmt/\* 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 **rmt** should put debug information. - **USER** The name of a user (local to the magnetic tape server) that may use the services of the **rmt** server. More than one **USER=***name* line is possible. A line **USER=**\* grants access to all users. - **ACCESS** This keyword is followed by three parameters separated by a TAB. The name of a user (local to the magnetic tape server host) that may use the services of the **rmt** server followed by the name of a host from where operation is granted and a file specifier pattern for a file or file sub tree that may be accessed if this **ACCESS** line matches. More than one **ACCESS=***name host path* line is possible. If standard input of **rmt** is not a socket from a remote host, **rmt** will compare the host entry from **/etc/default/rmt** 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 thr 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 [**star**(1)](/star/1.md), **ufsdump**(1), **ufsrestore**(1), [**intro**(2)](/intro/2.md), [**open**(2)](/open/2.md), [**close**(2)](/close/2.md), [**read**(2)](/read/2.md), [**write**(2)](/write/2.md), [**ioctl**(2)](/ioctl/2.md), [**lseek**(2)](/lseek/2.md), **getpeername(3)** [**rcmd**(3)](/rcmd/3.md), [**rexec**(3)](/rexec/3.md), [**strerror**(3)](/strerror/3.md), **mtio**(7) ## DIAGNOSTICS All responses are send to the network connection. They use the form described above. ## NOTES To use **rmt** as a remote file access protocol you need to use the symbolic open modes as e.g. the *O\_CREAT* flag is not unique between different architectures. In order to allow this implementation to be used as a remote file access protocol, it accepts file names up to 4096 bytes with the open command. Other **rmt** implementations allow no more than 64 bytes. The possibility to create a debug file by calling **rmt** *file* has been disabled for security reasons. If you like to debug **rmt** edit **/etc/default/rmt** and insert a **DEBUG** entry. This implementation of **rmt** adds some security features to the server that make it behave slightly different from older implementations. Read the above documentation about the file /etc/default/rmt to make sure your local installation is configured for your needs. To grant the same permissions as with old **rmt** servers, create a file /etc/default/rmt and add the following lines to this file: **USER=**\*\ **ACCESS=**\* \* \* Note that the three fields in the **ACCESS=** line need to be separated by a TAB character. Be very careful when designing patterns to match path names that may be accepted for *open*. If a pattern would allow to include */../* a possible intruder could vitually access any path on your system. ## BUGS None known. ## HISTORY The **rmt** command first appeared on BSD in march 1981. This **rmt** server is a new implementation that tries to be compatible to all existing implementations. It is the only known implementation that in addition tries to fix the data exchange problems between different architectures. ## AUTHOR ``` Joerg Schilling Seestr. 110 D-13353 Berlin Germany ``` Mail bugs and suggestions to: **schilling@fokus.fhg.de** or **js@cs.tu-berlin.de** or **joerg@schily.isdn.cs.tu-berlin.de**