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

FreeBSD Manual Pages

  
 
  

home | help
RMT(1)			    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 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

	      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 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\n

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

	      Lwhence\noffset\n
			     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
				    register".

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

				    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
				    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	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.   If
			     we	 know that we have been	called by a RMT	proto-
			     col 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 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).

	      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 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
				    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
       /usr/local/etc/rmt
	      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:

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

		     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.

		     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),  rmtopen(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 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:

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

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	imple-
       mentations.  It is the only known implementation	that in	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:

       joerg.schilling@fokus.fraunhofer.de   or	  js@cs.tu-berlin.de   or  jo-
       erg@schily.isdn.cs.tu-berlin.de

Joerg Schilling			  Release 1.1				RMT(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | DIAGNOSTICS | NOTES | BUGS | HISTORY | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=srmt&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help