1RMT(1) Schily´s USER COMMANDS RMT(1)
2
6 rmt - remote magnetic tape protocol server
7
9 /opt/schily/sbin/rmt
10 /etc/rmt
11
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 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 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 All responses are send back in ASCII. They are in one of the following
36 two forms.
37 Successful commands have responses of
39 Anumber\n
41 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 Eerror-number\nerror-message\n
47 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 The protocol implements the following commands:
55 Odevice\nmode\n
57 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 If no file /etc/default/rmt exists, only file‐
85 names starting with /dev/ are accepted for secu‐
86 rity reasons.
87 If a device is already open, it is closed before
89 a new open is performed.
90 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 Cdevice\n Close the currently open device or file. The
100 argument device is ignored.
101 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 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 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 On large file aware operating systems, rmt will
124 correctly handle large lseek(2) requests.
125 The following whence values are supported:
127 0 Mapped to SEEK_SET.
129 1 Mapped to SEEK_CUR.
131 2 Mapped to SEEK_END.
133 3 Mapped to SEEK_DATA If avalable on the
135 remote system.
136 4 Mapped to SEEK_HOLE If avalable on the
138 remote system.
139 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 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 T return the content of the structure member
167 mt_type which contains the type of the
168 magnetic tape device.
169 D return the content of the structure member
171 mt_dsreg which contains the “drive status
172 register”.
173 E return the content of the structure member
175 mt_erreg which contains the “error regis‐
176 ter”.
177 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 R return the content of the structure member
186 mt_resid which contains the residual count
187 of the last I/O.
188 F return the content of the structure member
190 mt_fileno which contains the block number
191 of the current tape position.
192 B return the content of the structure member
194 mt_blkno which contains the block number
195 of the current tape position.
196 f return the content of the structure member
198 mt_flags which contains MTF_ flags from
199 the driver.
200 b return the content of the structure member
202 mt_bf which contains the optimum blocking
203 factor.
204 This command is not terminated with a new-line.
206 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 -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 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 0 Issue a MTWEOF command (write count end-
241 of-file records).
242 1 Issue a MTFSF command (forward space over
244 count file marks).
245 2 Issue a MTBSF command (backward space over
247 count file marks).
248 3 Issue a MTFSR command (forward space count
250 inter-record gaps).
251 4 Issue a MTBSR command (backward space
253 count inter-record gaps).
254 5 Issue a MTREW command (rewind).
256 6 Issue a MTOFFL command (rewind and put the
258 drive off-line).
259 7 Issue a MTNOP command (no operation, set
261 status only).
262 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 0 Issue a MTCACHE command (switch cache on).
277 1 Issue a MTNOCACHE command (switch cache
279 off).
280 2 Issue a MTRETEN command (retension the
282 tape).
283 3 Issue a MTERASE command (erase the entire
285 tape).
286 4 Issue a MTEOM command (position to end of
288 media).
289 5 Issue a MTNBSF command (backward space
291 count files to BOF).
292 v\n Return the version of the rmt server. This is
294 currently the decimal number 1.
295 Any other command causes rmt to exit.
297
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 Default values can be set for the following options in
306 /etc/default/rmt. For example:
307 DEBUG=/tmp/rmt.debug
309 USER=tape
310 ACCESS=tape myhost.mydomain.org /dev/rmt/*
311 All keywords must be on the beginning of a line.
313 DEBUG If you like to get debug information, set this to a file
315 name where rmt should put debug information.
316 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 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 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 PIPE If stdin is a UNIX pipe.
336 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 ILLEGAL_SOCKET
343 If getpeername() does not work for stdin.
344 NOT_IP If getpeername() works for stdin but is not
346 connected to an internet socket.
347
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
356 All responses are send to the network connection. They use the form
357 described above.
358
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 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 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 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 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 USER=*
381 ACCESS=* * *
382 Note that the three fields in the ACCESS= line need to be separated by
384 a TAB character.
385 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
393 None known.
394
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 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
408 Joerg Schilling
409 Seestr. 110
410 D-13353 Berlin
411 Germany
412 Mail bugs and suggestions to:
414 joerg.schilling@fokus.fraunhofer.de or joerg@schily.net
416Joerg Schilling 2018/06/09 RMT(1)