Schily's USER COMMANDS RMT(1) NAME rmt - remote magnetic tape protocol server SYNOPSIS /opt/schily/sbin/rmt /etc/rmt DESCRIPTION This is the description of the enhanced Schily SING version of the rmt remote tape server program. rmt is a program used by programs like star and ufsdump hat like to access remote magnetic tape drives and files through an interpro- cess communication connection. rmt is normally started up with an rexec(3) or rcmd(3) call. The rmt program accepts open, close, read, write and seek requests and requests that are specific to magnetic tapes. rmt performs the commands and then responds with a status indication. This Schily SING version of the rmt server gives full compa- tibility to the original BSD version, the enhanced Sun ver- sion and the enhanced GNU version. 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 or reimplement it's features. All responses are in ASCII and in one of the following two forms. Successful commands have responses of Anumber\n where number is the ASCII representation of a decimal number. Unsuccessful commands are responded to with Eerror-number\nerror-message\n 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). The protocol implements the following commands: Odevice\nmode\n Joerg Schilling Last change: Release 1.1 1 Schily's USER COMMANDS RMT(1) Odevice\nmode 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 suit- able for passing to open(2). If both, mode and symbolic_mode are used, they are separated by a space character; symbolic_mode appears on the same line as the numeric is in the same notation as it would appear 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 dif- ferent operating systems define all bits execpt the lowest two bits in a dif- ferent way. If a device is already open, it is closed before a new open is performed. A VERSION 1 client that is aware of the official mt_op codes should issue a I-1\n0\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 maps differing values to the official ones. Cdevice\n Close the currently open device or file. The argument device is ignored. Rcount\n Read count bytes of data from the open device or file. rmt performs the requested read(2) operation and responds with Acount-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. Wcount\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) operation is returned as Joerg Schilling Last change: Release 1.1 2 Schily's USER COMMANDS RMT(1) reply. Lwhence\noffset\n Perform an lseek(2) operation on open the device or file using the specified parameters. The return value from the lseek(2) operation is returned as reply. S The old non-portable status call. If the 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 with a new-line. ssub-command The new portable status call. If the open device is a magnetic tape, return members 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 fol- lowing 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. R return the content of the structure member mt_resid which contains the residual count of the last I/O. Joerg Schilling Last change: Release 1.1 3 Schily's USER COMMANDS RMT(1) 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. Ioperation\ncount\n Perform a MTIOCOP ioctl(2) command using the specified parameters. The parame- ters 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 dif- ferent architectures. But as in many cases Linux does not even follow this rule. If we know that we have been called by a 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) opcodes in the range 0..7. Local mt_op codes must be remapped to the official values before sendig them over the wire. The answer of the current version of rmt is 1. Other rmt implementa- tions send an error code back when this command is used. Joerg Schilling Last change: Release 1.1 4 Schily's USER COMMANDS RMT(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 offline). 7 Issue a MTNOP command (no opera- tion, set status only). ioperation\ncount\n Perform a MTIOCOP ioctl(2) command using the specified parameters. This command implements support for commands bejond MTWEOF..MTNOP (0..7). The parameters are interpreted as the ASCII representa- tions 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). Joerg Schilling Last change: Release 1.1 5 Schily's USER COMMANDS RMT(1) 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: USER=tape DEBUG If you like to get debug information, set this to a file name where rmt puts debug information. USER The name of a user (local to the magnetic tape server) that may use the services of the rmt server. A line USER=* grants access to all users. ACCESS The name of a user (local to the magnetic tape server) 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 for a file or file sub tree that may be accessed. SEE ALSO star(1), rcmd(3), rexec(3), 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. This implementation of rmt adds some security features to the server that make it behave slightly different from older implementations. Read the 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 the old rmt servers, create a file /etc/default/rmt and add the following lines to this file: Joerg Schilling Last change: Release 1.1 6 Schily's USER COMMANDS RMT(1) USER=* ACCESS=* * * Note that the three fields in the ACCESS= line need to be separated by a TAB character. 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 compati- ble to all existing implementations. It is the only known implementation that in addition tries to fix the data exchange problems between differen architectures. AUTHOR Joerg Schilling Seestr. 110 D-13353 Berlin Germany Mail bugs and suggestions to: schilling@fokus.gmd.de or js@cs.tu-berlin.de or joerg@schily.isdn.cs.tu-berlin.de Joerg Schilling Last change: Release 1.1 7