Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RMT(1)			    Schily's USER COMMANDS			RMT(1)

       rmt - remote magnetic tape protocol server


       This  is	 the description of the	enhanced Schily	version	of the rmt re-
       mote 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) 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 ab-
       stractions 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  ei-
       ther  use  the  remote tape client code from star which is available in
       librmt or reimplement its features.

       All responses are send back in ASCII.  They are in one of the following
       two forms.

       Successful commands have	responses of


       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


       where  error-number  is	one of the possible error numbers described in
       intro(2), and error-message is the corresponding	error  string  as  re-
       trieved by strerror(3).	Note that the error number is valid on the re-
       mote system where the rmt code runs and may have	a different meaning on
       the local system.

       The protocol implements the following commands:


	      Odevice\nmode symbolic_mode\n
			     Open the specified	device or file 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).	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 separated by a space character;
			     symbolic_mode appears on the same line as the nu-
			     meric 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  nu-
			     meric mode	is ignored.  The symbolic notation al-
			     lows to send the  expected	 open  mode  over  the
			     wire, using a system independent method.  This is
			     needed because different operating	 systems  usu-
			     ally  define  all bits in a different way.	An ex-
			     ception 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 nu-
			     meric  open mode with 0x03	before using it	as ar-
			     gument 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	/usr/local/etc/rmt exists, only	 file-
			     names  starting with /dev/	are accepted for secu-
			     rity 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
			     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.

	      Cdevice\n	     Close the currently open device or	file.  The ar-
			     gument device is ignored.

	      Rcount\n	     Read count	bytes of data from the open device  or
			     file.   rmt performs the requested	read(2)	opera-
			     tion and responds with Acount-read\n if the  read
			     operation	was  successful; otherwise an error in
			     standard format is	returned.  If the read	opera-
			     tion  was	successful,  the data read is sent di-
			     rectly 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  re-
			     turned as reply.

			     Perform  an lseek(2) operation on the open	device
			     or	file using the specified parameters.  The  re-
			     turn  value  from	the  lseek(2) operation	is re-
			     turned as reply.

			     On	large file aware operating systems,  rmt  will
			     correctly handle large lseek(2) requests.

			     The following whence values are supported:

			     0	    Mapped to SEEK_SET.

			     1	    Mapped to SEEK_CUR.

			     2	    Mapped to SEEK_END.

			     3	    Mapped to SEEK_DATA	If avalable on the re-
				    mote system.

			     4	    Mapped to SEEK_HOLE	If avalable on the re-
				    mote system.

	      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 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 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.  If the cur-
			     rently open 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	device is not a	magnetic tape,
			     an	error is returned.  If the MTIOCGET  operation
			     was successful, the numerical value of the	struc-
			     ture member is returned in	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

			     E	    return the content of the structure	member
				    mt_erreg which contains the	"error	regis-

				    This  structure  member  must be retrieved
				    first because it  is  cleared  after  each
				    MTIOCGET  ioctl call.  The librmt will al-
				    ways 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

			     This command is not terminated with a new-line.

			     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	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.  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 MTI-
				    OCOP 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 er-
				    ror	 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).

			     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  the
			     ioctl  call  according to the actual values found
			     in	<sys/mtio.h>.  When the	operation is  success-
			     ful the return value is the count parameter.

			     0	    Issue a MTCACHE command (switch cache on).

			     1	    Issue  a  MTNOCACHE	 command (switch cache

			     2	    Issue a  MTRETEN  command  (retension  the

			     3	    Issue  a MTERASE command (erase the	entire

			     4	    Issue a MTEOM command (position to end  of

			     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.

	      The  file	/usr/local/etc/rmt allows to set up rules to limit the
	      accessibility of files based on rules.  This  feature  is	 typi-
	      cally  used  when	 the rmt run from a non	personal but task spe-
	      cific login.

	      Default values can be set	for the	following options in  /usr/lo-
	      cal/etc/rmt.  For	example:

	      ACCESS=tape /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 ac-
		     cess 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

		     If	standard input of rmt is not a socket  from  a	remote
		     host,  rmt	 will  compare	the  host  entry from /usr/lo-
		     cal/etc/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	match-
			       ing ACCESS= line.

			       If getpeername()	does not work for stdin.

		     NOT_IP    If  getpeername()  works	 for  stdin but	is not
			       connected to an internet	socket.

       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),	rmtopen(3),  rmtclose(3),  rmtread(3),
       rmtwrite(3), rmtseek(3),	rmtioctl(3), rmtstatus(3)

       All  responses  are  send to the	network	connection.  They use the form
       described above.

       To use rmt as a remote file access protocol you need to	use  the  sym-
       bolic open 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  ac-
       cess  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 /usr/lo-
       cal/etc/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 /usr/local/etc/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
       /usr/local/etc/rmt and add the following	lines to this file:

       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	virtually access any path on your sys-
       tem.  For this reason, /../ is not allowed to appear in a path  regard-
       less of the pattern.

       None known.

       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	imple-
       mentations.  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.

       Joerg Schilling
       Seestr. 110
       D-13353 Berlin

       Mail bugs and suggestions to: or

Joerg Schilling			  2018/06/09				RMT(1)


Want to link to this manual page? Use this URL:

home | help