RMT(1) Schilys 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 version(1,3,5) of the rmt
remote tape server program. rmt is a program used by programs like
star(1,4) and ufsdump that like to access(2,5) remote magnetic tape drives and
files through an interprocess communication connection. rmt is nor-
mally started up with an rexec(3) or rcmd(3) call.
The rmt program accepts open(2,3,n), close(2,7,n), read(2,n,1 builtins), write(1,2) 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(1,3,5) of the rmt server gives full compatibility to the original
BSD version(1,3,5), the enhanced Sun version(1,3,5) 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(1,8) the passwd(1,5) file(1,n) 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(1,4) which is available in(1,8)
librmt or reimplement it's features.
All responses are send(2,n) back in(1,8) ASCII and in(1,8) one of the following two
forms.
Successful commands have responses of
Anumber\n
where number is the ASCII representation of a decimal number that usu-
ally is the return code of the corresponding system call. Unsuccessful
commands are responded to with
Eerror-number\nerror-message\n
where error-number is one of the possible error(8,n) numbers described in(1,8)
intro(1,2,3,4,5,6,7,8)(2), and error-message is the corresponding error(8,n) string(3,n) as
retrieved by strerror(3).
The protocol implements the following commands:
Odevice\nmode\n
Odevice\nmode symbolic_mode\n
Open the specified device or file(1,n) using the indi-
cated 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,3,n)(2). A variant of the open(2,3,n) command includes
the symbolic_mode string(3,n) which is a GNU exten-
sion. 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(2,n) using the same notation
as used in(1,8) a C source (e.g. O_RDWR|O_CREAT). If
the symbolic_mode is send(2,n) to the server, the
numeric mode is ignored. The symbolic notation
allows to send(2,n) the expected open(2,3,n) mode over the
wire, using a system independent method. This is
needed because different operating systems usu-
ally define all bits in(1,8) 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(2,3,n) mode with 0x03 before
using it as argument to the open(2,3,n)(2) call. If you
need more bits in(1,8) the second parameter ot
open(2,3,n)(2), you need to use the symbolic mode.
If no file(1,n) /etc/default/rmt exists, only file-
names starting with /dev/ are accepted for secu-
rity reasons.
If a device is already open(2,3,n), it is closed before
a new open(2,3,n) is performed.
A RMT protocol VERSION 1 client should issue a
I-1\n0\n
command just after opening a file(1,n) or device. This
is needed to tell the server that the client is
aware of the official order of the mt_op codes in(1,8)
the range 0..7 and that is maps deviating values
to the official ones.
Cdevice\n Close the currently open(2,3,n) device or file. The
argument device is ignored.
Rcount\n Read count bytes of data from the open(2,3,n) device or
file. rmt performs the requested read(2,n,1 builtins)(2) opera-
tion and responds with Acount-read\n if(3,n) the read(2,n,1 builtins)
operation was successful; otherwise an error(8,n) in(1,8)
standard format is returned. If the read(2,n,1 builtins) opera-
tion was successful, the data read(2,n,1 builtins) is sent
directly after the response described above.
Wcount\n Write data to the open(2,3,n) device or file. After
reading the command specification, rmt reads
count bytes from the network connection and
aborts if(3,n) a premature EOF is encountered. The
return value from the write(1,2)(2) operation is
returned as reply.
Lwhence\noffset\n
Perform an lseek(2) operation on the open(2,3,n) device
or file(1,n) using the specified parameters. The
return value from the lseek(2) operation is
returned as reply.
On large file(1,n) aware operating systems, 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,3,5) 1 extended status
call below. If the currently open(2,3,n) device is a
magnetic tape, return the magnetic tape status,
as obtained with a MTIOCGET ioctl call. If the
open(2,3,n) device is not a magnetic tape, an error(8,n) is
returned. If the MTIOCGET operation was success-
ful, an "ack" is sent with the size of the status
buffer, then the status buffer is sent. As the
status buffer is sent in(1,8) binary, this command it
considered outdated. Please use the extended sta-
tus command instead. This command is not termi-
nated by a new-line.
ssub-command The new portable status call. This command is
part of the RMT protocol version(1,3,5) 1. If the cur-
rently open(2,3,n) device is a magnetic tape, return a
single specified member of the magnetic tape sta-
tus structure, as obtained with a MTIOCGET ioctl
call. If the open(2,3,n) device is not a magnetic tape,
an error(8,n) is returned. If the MTIOCGET operation
was successful, the numerical value of the struc-
ture member is returned in(1,8) decimal. The follow-
ing 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(8,n) regis-
ter".
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.
Ioperation\ncount\n
Perform a MTIOCOP ioctl(2) command using the
specified parameters. The parameters are inter-
preted as the ASCII representations of the deci-
mal values to place in(1,8) the mt_op and mt_count
fields of the structure used in(1,8) 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(1,8)
many cases Linux does not even follow this rule.
If we know that we have been called by a RMT pro-
tocol 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(1,3,5) number of the rmt
server and tell the server that the client
is aware of the official order of the MTI-
OCOP ioctl(2) opcodes in(1,8) 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(1,3,5) of rmt
is 1. Old rmt implementations send(2,n) an
error(8,n) code back when this command is used.
Future rmt implementations with further
enhancements will send(2,n) an answer with a
value > 1.
0 Issue a MTWEOF command (write(1,2) count end-
of-file records).
1 Issue a MTFSF command (forward space over
count file(1,n) marks).
2 Issue a MTBSF command (backward space over
count file(1,n) 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(7,n,1 builtins)
status only).
ioperation\ncount\n
Perform a MTIOCOP ioctl(2) command using the
specified parameters. This command is a RMT pro-
tocol VERSION 1 extension and implements support
for commands beyond MTWEOF..MTNOP (0..7). The
parameters are interpreted as the ASCII represen-
tations of the decimal values described below.
They are converted into the local values mt_op
and mt_count fields of the structure used in(1,8) the
ioctl call according to the actual values found
in(1,8) <sys/mtio.h>. When the operation is success-
ful the return value is the count parameter.
0 Issue a MTCACHE command (switch(1,n) cache on).
1 Issue a MTNOCACHE command (switch(1,n) 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(1,3,5) 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(7,n,1 builtins) for the following options in(1,8)
/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(7,n,1 builtins) this to a file(1,n)
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(2,5) 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(1,5)) that may use the services of the rmt server
followed by the name of a host(1,5) from where operation is
granted and a file(1,n) specifier pattern for a file(1,n) or file(1,n)
sub tree that may be accessed if(3,n) this ACCESS line
matches. More than one ACCESS=name host(1,5) path line is
possible.
If standard input of rmt is not a socket(2,7,n) from a remote
host(1,5), rmt will compare the host(1,5) 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(1,8) the match-
ing ACCESS= line.
ILLEGAL_SOCKET
If getpeername(1,2)() does not work for stdin.
NOT_IP If getpeername(1,2)() works for stdin but is not
connected to an internet socket.
SEE ALSO
star(1,4)(1), ufsdump(1), ufsrestore(1), intro(1,2,3,4,5,6,7,8)(2), open(2,3,n)(2), close(2,7,n)(2),
read(2,n,1 builtins)(2), write(1,2)(2), ioctl(2), lseek(2), getpeername(1,2)(3) rcmd(3),
rexec(3), strerror(3), mtio(7)
DIAGNOSTICS
All responses are send(2,n) to the network connection. They use the form
described above.
NOTES
To use rmt as a remote file(1,n) access(2,5) protocol you need to use the sym-
bolic open(2,3,n) modes as e.g. the O_CREAT flag is not unique between differ-
ent architectures.
In order to allow this implementation to be used as a remote file(1,n)
access(2,5) protocol, it accepts file(1,n) names up to 4096 bytes with the open(2,3,n)
command. Other rmt implementations allow no more than 64 bytes.
The possibility to create a debug file(1,n) by calling rmt file(1,n) 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(1,n) /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(1,n)
/etc/default/rmt and add the following lines to this file:
USER=*
ACCESS=* * *
Note that the three fields in(1,8) 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(2,3,n). If a pattern would allow to include /../ a possible
intruder could vitually access(2,5) any path on your system.
BUGS
None known.
HISTORY
The rmt command first appeared on BSD in(1,8) march 1981. This rmt server is
a new implementation that tries to be compatible to all existing imple-
mentations. It is the only known implementation that in(1,8) 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
Joerg Schilling Release 1.1 RMT(1)