rmt(8)

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 magnet

ic tape drives and files through an interprocess 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 as well as requests that are specific to magnetic tapes.

rmt performs the commands and then responds with a status indica

tion.

This version of the rmt server gives full compatibility to

the original BSD version, the enhanced Sun version and the en

hanced GNU version. In addition to the Sun and GNU enhancements,

it implements further abstractions for better cross platform com

pliance. 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

Anumber_n

where number is the ASCII representation of a decimal num

ber that usually is the return code of the corresponding system

call. Unsuccessful commands are responded to with

Eerror-numbernerror-messagen

where error-number is one of the possible error numbers

described in intro(2), and error-message is the corresponding er

ror string as retrieved by strerror(3).

The protocol implements the following commands:

Odevicenmoden

Odevicenmode symbolic_moden

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). A variant of the open

command includes the symbolic_mode string which is a GNU exten

sion. If both, mode and symbolic_mode are present, they are sep

arated 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, us

ing a system independent method. This is needed because differ

ent 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 be

havior, rmt masks the numeric open mode with 0x03 before using it

as argument to the open(2) call. If you need more bits in the

second parameter ot open(2), you need to use the symbolic mode.

If no file /etc/default/rmt exists,

only filenames starting with /dev/ are accepted for security rea

sons.

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-1n0_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.

Cdevicen Close the currently open device or

file. The argument device is ignored.

Rcountn 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.

Wcountn 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 en

countered. The return value from the write(2) operation is re

turned as reply.

Lwhencenoffsetn

Perform an lseek(2) operation on the

open device or file using the specified parameters. The return

value from the lseek(2) operation is returned as reply.

On large file aware operating sys

tems, rmt will correctly handle large lseek(2) 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

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.
ssub-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

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 regis

ter".

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 fac

tor.

This command is not terminated with

a new-line.

Ioperationncountn

Perform a MTIOCOP ioctl(2) 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

ing 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 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 (for

ward space over count file marks).

2 Issue a MTBSF command (back

ward space over count file marks).

3 Issue a MTFSR command (for

ward space count inter-record gaps).

4 Issue a MTBSR command (back

ward 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 op

eration, set status only).

ioperationncountn

Perform a MTIOCOP ioctl(2) command

using the specified parameters. This command is a RMT protocol

VERSION 1

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 <sys/mtio.h>. 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 (posi

tion to end of media).

5 Issue a MTNBSF command (back

ward 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

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 con

nections 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), ufsdump(1), ufsrestore(1), intro(2), open(2),

close(2), read(2), write(2), ioctl(2), lseek(2), getpeername(3)

rcmd(3), rexec(3), strerror(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.

In order to allow this implementation to be used as a re

mote 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 im

plementations. Read the above documentation about the file

/etc/default/rmt to make sure your local installation is config

ured 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 implementa

tion that in addition tries to fix the data exchange problems be

tween 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

Joerg Schilling Release 1.1

RMT(1)