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 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 com-
munication 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 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 compati-
bility features, you need to either use the remote tape
client code from star which is available in librmt or reim-
plement its features.
All responses are send back in ASCII. They are in one of the
following two forms.
Successful 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. 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-
Joerg Schilling Last change: 2020/09/04 1
Schily's USER COMMANDS RMT(1)
ing error string as retrieved by strerror(3). Note that the
error number is valid on the remote system where the rmt
code runs and may have a different meaning on the local sys-
tem.
The protocol implements the following commands:
Odevice\nmode\n
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 being passed as second parame-
ter to open(2). 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 sym-
bolic notation allows to send the
expected open mode over the wire, using
a system independent method. This is
needed because different operating sys-
tems usually define all bits in a dif-
ferent way. An exception are the lowest
two bits. The lowest two bits allow to
code O_RDONLY,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)
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 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\n0\n
command just after opening a file or
Joerg Schilling Last change: 2020/09/04 2
Schily's USER COMMANDS RMT(1)
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.
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
reply.
Lwhence\noffset\n
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 systems,
rmt will correctly handle large lseek(2)
requests.
The following whence values are sup-
ported:
0 Mapped to SEEK_SET.
1 Mapped to SEEK_CUR.
2 Mapped to SEEK_END.
3 Mapped to SEEK_DATA If avalable on
the remote system.
4 Mapped to SEEK_HOLE If avalable on
the remote system.
Joerg Schilling Last change: 2020/09/04 3
Schily's USER COMMANDS RMT(1)
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 mag-
netic 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 out-
dated. Please use the extended status
command instead. This command is not
terminated by a new-line.
ssub-command The new portable status call. This com-
mand 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 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. The librmt will always
retrieve the member mt_erreg first
when it is told to retrieve a com-
plete status structure.
Joerg Schilling Last change: 2020/09/04 4
Schily's USER COMMANDS RMT(1)
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 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. In many cases
Linux does not even follow this rule and
could cause harm to tape media in case
an old non RMT protocol VERSION 1 aware
rmt client connects from UNIX to Linux
or from Linux to UNIX. 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 the 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
Joerg Schilling Last change: 2020/09/04 5
Schily's USER COMMANDS RMT(1)
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 implementa-
tions 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 opera-
tion, set status only).
ioperation\ncount\n
Perform a MTIOCOP ioctl(2) 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 param-
eters 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
Joerg Schilling Last change: 2020/09/04 6
Schily's USER COMMANDS RMT(1)
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
The file /etc/default/rmt allows to set up rules to
limit the accessibility of files based on rules. This
feature is typically used when the rmt run from a non
personal but task specific login.
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 informa-
tion.
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
Joerg Schilling Last change: 2020/09/04 7
Schily's USER COMMANDS RMT(1)
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 the 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), getpeer-
name(3), rcmd(3), rexec(3), strerror(3), mtio(7), rmto-
pen(3), rmtclose(3), rmtread(3), rmtwrite(3), rmtseek(3),
rmtioctl(3), rmtstatus(3)
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
Joerg Schilling Last change: 2020/09/04 8
Schily's USER COMMANDS RMT(1)
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 /../ in the path, a possible intruder could virtu-
ally access any path on your system. For this reason, /../
is not allowed to appear in a path regardless of the pat-
tern.
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 different architectures.
This rmt implementation has been written in 1994 by Joerg
Schilling. In 2000, support for RMT VERSION 1 has been
added and a mapping to work around the non-standard Linux
mtio opcodes in the range 0..7 has been added. rmt is still
maintained by Joerg Schilling.
AUTHOR
Joerg Schilling
D-13353 Berlin
Germany
Mail bugs and suggestions to:
joerg@schily.net
Joerg Schilling Last change: 2020/09/04 9
Man(1) output converted with
man2html
Schily's Home
