1RMT(1)                      Schily´s USER COMMANDS                      RMT(1)
2
3
4

NAME

6       rmt - remote magnetic tape protocol server
7

SYNOPSIS

9       /opt/schily/sbin/rmt
10       /etc/rmt
11
12

DESCRIPTION

14       This  is  the  description  of  the  enhanced Schily version of the rmt
15       remote tape server program.  rmt is a program  used  by  programs  like
16       star  and  ufsdump  that like to access remote magnetic tape drives and
17       files through an interprocess communication connection.   rmt  is  nor‐
18       mally started up with an rexec(3) or rcmd(3) call.
19
20       The  rmt  program accepts open, close, read, write and seek requests as
21       well as requests that are specific to magnetic tapes.  rmt performs the
22       commands and then responds with a status indication.
23
24       This version of the rmt server gives full compatibility to the original
25       BSD version, the enhanced Sun version and the enhanced GNU version.  In
26       addition  to  the  Sun  and  GNU  enhancements,  it  implements further
27       abstractions for better cross platform compliance.   It  supports  best
28       speed  and best compliance even when server and client code are running
29       on different platforms.  It is prepared to be installed as a user shell
30       in  the  passwd file to create remote tape specific logins and security
31       checking.  To use the enhanced  compatibility  features,  you  need  to
32       either  use the remote tape client code from star which is available in
33       librmt or reimplement its features.
34
35       All responses are send back in ASCII.  They are in one of the following
36       two forms.
37
38       Successful commands have responses of
39
40              Anumber\n
41
42       where  number is the ASCII representation of a decimal number that usu‐
43       ally is the return code of the corresponding system call.  Unsuccessful
44       commands are responded to with
45
46              Eerror-number\nerror-message\n
47
48       where  error-number  is  one of the possible error numbers described in
49       intro(2), and  error-message  is  the  corresponding  error  string  as
50       retrieved  by  strerror(3).  Note that the error number is valid on the
51       remote system where the rmt code runs and may have a different  meaning
52       on the local system.
53
54       The protocol implements the following commands:
55
56              Odevice\nmode\n
57
58              Odevice\nmode symbolic_mode\n
59                             Open the specified device or file using the indi‐
60                             cated mode.  device is a full path name, and mode
61                             is  an  ASCII  representation of a decimal number
62                             suitable for being passed as second parameter  to
63                             open(2).   A variant of the open command includes
64                             the symbolic_mode string which is  a  GNU  exten‐
65                             sion.    If  both,  mode  and  symbolic_mode  are
66                             present, they are separated by a space character;
67                             symbolic_mode  appears  on  the  same line as the
68                             numeric mode.  It is send using the same notation
69                             as used in a C source (e.g.  O_RDWR|O_CREAT).  If
70                             the symbolic_mode is  send  to  the  server,  the
71                             numeric  mode  is ignored.  The symbolic notation
72                             allows to send the expected open  mode  over  the
73                             wire, using a system independent method.  This is
74                             needed because different operating  systems  usu‐
75                             ally  define  all  bits  in  a  different way. An
76                             exception are the lowest two  bits.   The  lowest
77                             two  bits  allow  to  code  O_RDONLY,O_WRONLY and
78                             O_RDWR.   To  prevent  unexpected  behavior,  rmt
79                             masks  the  numeric  open  mode  with 0x03 before
80                             using it as argument to the open(2) call.  If you
81                             need   more  bits  in  the  second  parameter  ot
82                             open(2), you need to use the symbolic mode.
83
84                             If no file /etc/default/rmt  exists,  only  file‐
85                             names  starting with /dev/ are accepted for secu‐
86                             rity reasons.
87
88                             If a device is already open, it is closed  before
89                             a new open is performed.
90
91                             A RMT protocol VERSION 1 client should issue a
92                             I-1\n0\n
93                             command just after opening a file or device. This
94                             is needed to tell the server that the  client  is
95                             aware of the official order of the mt_op codes in
96                             the range 0..7 and that is maps deviating  values
97                             to the official ones.
98
99              Cdevice\n      Close  the  currently  open  device or file.  The
100                             argument device is ignored.
101
102              Rcount\n       Read count bytes of data from the open device  or
103                             file.   rmt performs the requested read(2) opera‐
104                             tion and responds with Acount-read\n if the  read
105                             operation  was  successful; otherwise an error in
106                             standard format is returned.  If the read  opera‐
107                             tion  was  successful,  the  data  read  is  sent
108                             directly after the response described above.
109
110              Wcount\n       Write data to the open  device  or  file.   After
111                             reading  the  command  specification,  rmt  reads
112                             count  bytes  from  the  network  connection  and
113                             aborts  if  a  premature EOF is encountered.  The
114                             return  value  from  the  write(2)  operation  is
115                             returned as reply.
116
117              Lwhence\noffset\n
118                             Perform  an lseek(2) operation on the open device
119                             or file  using  the  specified  parameters.   The
120                             return  value  from  the  lseek(2)  operation  is
121                             returned as reply.
122
123                             On large file aware operating systems,  rmt  will
124                             correctly handle large lseek(2) requests.
125
126                             The following whence values are supported:
127
128                             0      Mapped to SEEK_SET.
129
130                             1      Mapped to SEEK_CUR.
131
132                             2      Mapped to SEEK_END.
133
134                             3      Mapped  to  SEEK_DATA  If  avalable on the
135                                    remote system.
136
137                             4      Mapped to SEEK_HOLE  If  avalable  on  the
138                                    remote system.
139
140              S              The  old  non-portable  status  call.   This call
141                             should not be used anymore, it has been  replaced
142                             by the new RMT protocol version 1 extended status
143                             call below.  If the currently open  device  is  a
144                             magnetic  tape,  return the magnetic tape status,
145                             as obtained with a MTIOCGET ioctl call.   If  the
146                             open  device  is not a magnetic tape, an error is
147                             returned.  If the MTIOCGET operation was success‐
148                             ful, an “ack” is sent with the size of the status
149                             buffer, then the status buffer is sent.   As  the
150                             status  buffer is sent in binary, this command it
151                             considered outdated. Please use the extended sta‐
152                             tus  command instead.  This command is not termi‐
153                             nated by a new-line.
154
155              ssub-command   The new portable status call.   This  command  is
156                             part  of the RMT protocol version 1.  If the cur‐
157                             rently open device is a magnetic tape,  return  a
158                             single specified member of the magnetic tape sta‐
159                             tus structure, as obtained with a MTIOCGET  ioctl
160                             call.  If the open device is not a magnetic tape,
161                             an error is returned.  If the MTIOCGET  operation
162                             was successful, the numerical value of the struc‐
163                             ture member is returned in decimal.  The  follow‐
164                             ing sub commands are supported:
165
166                             T      return the content of the structure member
167                                    mt_type which contains  the  type  of  the
168                                    magnetic tape device.
169
170                             D      return the content of the structure member
171                                    mt_dsreg which contains the “drive  status
172                                    register”.
173
174                             E      return the content of the structure member
175                                    mt_erreg which contains the “error  regis‐
176                                    ter”.
177
178                                    This  structure  member  must be retrieved
179                                    first because it  is  cleared  after  each
180                                    MTIOCGET  ioctl  call.   The  librmt  will
181                                    always retrieve the member mt_erreg  first
182                                    when  it  is  told  to retrieve a complete
183                                    status structure.
184
185                             R      return the content of the structure member
186                                    mt_resid which contains the residual count
187                                    of the last I/O.
188
189                             F      return the content of the structure member
190                                    mt_fileno  which contains the block number
191                                    of the current tape position.
192
193                             B      return the content of the structure member
194                                    mt_blkno  which  contains the block number
195                                    of the current tape position.
196
197                             f      return the content of the structure member
198                                    mt_flags  which  contains  MTF_ flags from
199                                    the driver.
200
201                             b      return the content of the structure member
202                                    mt_bf  which contains the optimum blocking
203                                    factor.
204
205                             This command is not terminated with a new-line.
206
207              Ioperation\ncount\n
208                             Perform a  MTIOCOP  ioctl(2)  command  using  the
209                             specified  parameters.  The parameters are inter‐
210                             preted as the ASCII representations of the  deci‐
211                             mal  values  to  place  in the mt_op and mt_count
212                             fields of the structure used in the  ioctl  call.
213                             When the operation is successful the return value
214                             is the count parameter.  Only  Opcodes  0..7  are
215                             unique  across  different architectures.  In many
216                             cases Linux does not even follow  this  rule  and
217                             could cause harm to tape media in case an old non
218                             RMT protocol VERSION 1 aware rmt client  connects
219                             from  UNIX to Linux or from Linux to UNIX.  If we
220                             know that we have been called by a  RMT  protocol
221                             VERSION  1  client, we may safely assume that the
222                             client is not using the Linux  mapping  over  the
223                             wire but the standard mapping described below:
224
225                             -1     Retrieve  the  version  number  of the rmt
226                                    server and tell the server that the client
227                                    is aware of the official order of the MTI‐
228                                    OCOP ioctl(2) opcodes in the  range  0..7.
229                                    Local  mt_op codes must be remapped to the
230                                    official values before sending  them  over
231                                    the wire.
232
233                                    The  answer  of the current version of rmt
234                                    is 1.  Old  rmt  implementations  send  an
235                                    error code back when this command is used.
236                                    Future rmt  implementations  with  further
237                                    enhancements  will  send  an answer with a
238                                    value > 1.
239
240                             0      Issue a MTWEOF command (write  count  end-
241                                    of-file records).
242
243                             1      Issue  a MTFSF command (forward space over
244                                    count file marks).
245
246                             2      Issue a MTBSF command (backward space over
247                                    count file marks).
248
249                             3      Issue a MTFSR command (forward space count
250                                    inter-record gaps).
251
252                             4      Issue  a  MTBSR  command  (backward  space
253                                    count inter-record gaps).
254
255                             5      Issue a MTREW command (rewind).
256
257                             6      Issue a MTOFFL command (rewind and put the
258                                    drive off-line).
259
260                             7      Issue a MTNOP command (no  operation,  set
261                                    status only).
262
263              ioperation\ncount\n
264                             Perform  a  MTIOCOP  ioctl(2)  command  using the
265                             specified parameters.  This command is a RMT pro‐
266                             tocol  VERSION 1 extension and implements support
267                             for commands beyond  MTWEOF..MTNOP  (0..7).   The
268                             parameters are interpreted as the ASCII represen‐
269                             tations of the decimal  values  described  below.
270                             They  are  converted  into the local values mt_op
271                             and mt_count fields of the structure used in  the
272                             ioctl  call  according to the actual values found
273                             in <sys/mtio.h>.  When the operation is  success‐
274                             ful the return value is the count parameter.
275
276                             0      Issue a MTCACHE command (switch cache on).
277
278                             1      Issue  a  MTNOCACHE  command (switch cache
279                                    off).
280
281                             2      Issue a  MTRETEN  command  (retension  the
282                                    tape).
283
284                             3      Issue  a MTERASE command (erase the entire
285                                    tape).
286
287                             4      Issue a MTEOM command (position to end  of
288                                    media).
289
290                             5      Issue  a  MTNBSF  command  (backward space
291                                    count files to BOF).
292
293              v\n            Return the version of the  rmt  server.  This  is
294                             currently the decimal number 1.
295
296       Any other command causes rmt to exit.
297

FILES

299       /etc/default/rmt
300              The  file  /etc/default/rmt  allows to set up rules to limit the
301              accessibility of files based on rules.  This  feature  is  typi‐
302              cally  used  when  the rmt run from a non personal but task spe‐
303              cific login.
304
305              Default  values  can  be  set  for  the  following  options   in
306              /etc/default/rmt.  For example:
307
308              DEBUG=/tmp/rmt.debug
309              USER=tape
310              ACCESS=tape    myhost.mydomain.org /dev/rmt/*
311
312              All keywords must be on the beginning of a line.
313
314              DEBUG  If  you like to get debug information, set this to a file
315                     name where rmt should put debug information.
316
317              USER   The name of a user (local to the  magnetic  tape  server)
318                     that  may  use the services of the rmt server.  More than
319                     one USER=name line is possible.   A  line  USER=*  grants
320                     access to all users.
321
322              ACCESS This keyword is followed by three parameters separated by
323                     a TAB.  The name of a user (local to  the  magnetic  tape
324                     server  host) that may use the services of the rmt server
325                     followed by the name of a host from  where  operation  is
326                     granted  and  a file specifier pattern for a file or file
327                     sub tree  that  may  be  accessed  if  this  ACCESS  line
328                     matches.   More  than  one  ACCESS=name host path line is
329                     possible.
330
331                     If standard input of rmt is not a socket  from  a  remote
332                     host,    rmt   will   compare   the   host   entry   from
333                     /etc/default/rmt with the following strings:
334
335                     PIPE      If stdin is a UNIX pipe.
336
337                               If you like to allow  remote  connections  that
338                               use  the ssh protocol, you need to use the word
339                               PIPE instead of the real hostname in the match‐
340                               ing ACCESS= line.
341
342                     ILLEGAL_SOCKET
343                               If getpeername() does not work for stdin.
344
345                     NOT_IP    If  getpeername()  works  for  stdin but is not
346                               connected to an internet socket.
347

SEE ALSO

349       star(1),  ufsdump(1),  ufsrestore(1),  intro(2),   open(2),   close(2),
350       read(2),   write(2),   ioctl(2),   lseek(2),  getpeername(3),  rcmd(3),
351       rexec(3), strerror(3), mtio(7),  rmtopen(3),  rmtclose(3),  rmtread(3),
352       rmtwrite(3), rmtseek(3), rmtioctl(3), rmtstatus(3)
353
354

DIAGNOSTICS

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

NOTES

360       To use rmt as a remote file access protocol you need to  use  the  sym‐
361       bolic open modes as e.g. the O_CREAT flag is not unique between differ‐
362       ent architectures.
363
364       In order to allow this implementation to  be  used  as  a  remote  file
365       access  protocol,  it accepts file names up to 4096 bytes with the open
366       command.  Other rmt implementations allow no more than 64 bytes.
367
368       The possibility to create a debug file by calling  rmt  file  has  been
369       disabled  for  security  reasons.   If  you  like  to  debug  rmt  edit
370       /etc/default/rmt and insert a DEBUG entry.
371
372       This implementation of rmt adds some security features  to  the  server
373       that  make  it  behave  slightly  different from older implementations.
374       Read the above documentation about the file  /etc/default/rmt  to  make
375       sure your local installation is configured for your needs.
376
377       To  grant  the  same permissions as with old rmt servers, create a file
378       /etc/default/rmt and add the following lines to this file:
379
380       USER=*
381       ACCESS=* * *
382
383       Note that the three fields in the ACCESS= line need to be separated  by
384       a TAB character.
385
386       Be very careful when designing patterns to match path names that may be
387       accepted for open.  If a pattern would allow to  include  /../  in  the
388       path,  a possible intruder could virtually access any path on your sys‐
389       tem.  For this reason, /../ is not allowed to appear in a path  regard‐
390       less of the pattern.
391

BUGS

393       None known.
394

HISTORY

396       The rmt command first appeared on BSD in march 1981. This rmt server is
397       a new implementation that tries to be compatible to all existing imple‐
398       mentations.  It is the only known implementation that in addition tries
399       to fix the data exchange problems between different architectures.
400
401
402       This rmt implementation has been written in 1994  by  Joerg  Schilling.
403       In 2000, support for RMT VERSION 1 has been added and a mapping to work
404       around the non-standard Linux mtio opcodes in the range 0..7  has  been
405       added.  rmt is still maintained by Joerg Schilling.
406

AUTHOR

408       Joerg Schilling
409       Seestr. 110
410       D-13353 Berlin
411       Germany
412
413       Mail bugs and suggestions to:
414
415       joerg.schilling@fokus.fraunhofer.de or joerg@schily.net
416
417
418
419Joerg Schilling                   2018/06/09                            RMT(1)
Impressum