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. If
217 we know that we have been called by a RMT proto‐
218 col VERSION 1 client, we may safely assume that
219 the client is not using Linux mapping over the
220 wire but the standard mapping described below:
221 -1 Retrieve the version number of the rmt
223 server and tell the server that the client
224 is aware of the official order of the MTI‐
225 OCOP ioctl(2) opcodes in the range 0..7.
226 Local mt_op codes must be remapped to the
227 official values before sending them over
228 the wire.
229 The answer of the current version of rmt
231 is 1. Old rmt implementations send an
232 error code back when this command is used.
233 Future rmt implementations with further
234 enhancements will send an answer with a
235 value > 1.
236 0 Issue a MTWEOF command (write count end-
238 of-file records).
239 1 Issue a MTFSF command (forward space over
241 count file marks).
242 2 Issue a MTBSF command (backward space over
244 count file marks).
245 3 Issue a MTFSR command (forward space count
247 inter-record gaps).
248 4 Issue a MTBSR command (backward space
250 count inter-record gaps).
251 5 Issue a MTREW command (rewind).
253 6 Issue a MTOFFL command (rewind and put the
255 drive off-line).
256 7 Issue a MTNOP command (no operation, set
258 status only).
259 ioperation\ncount\n
261 Perform a MTIOCOP ioctl(2) command using the
262 specified parameters. This command is a RMT pro‐
263 tocol VERSION 1 extension and implements support
264 for commands beyond MTWEOF..MTNOP (0..7). The
265 parameters are interpreted as the ASCII represen‐
266 tations of the decimal values described below.
267 They are converted into the local values mt_op
268 and mt_count fields of the structure used in the
269 ioctl call according to the actual values found
270 in <sys/mtio.h>. When the operation is success‐
271 ful the return value is the count parameter.
272 0 Issue a MTCACHE command (switch cache on).
274 1 Issue a MTNOCACHE command (switch cache
276 off).
277 2 Issue a MTRETEN command (retension the
279 tape).
280 3 Issue a MTERASE command (erase the entire
282 tape).
283 4 Issue a MTEOM command (position to end of
285 media).
286 5 Issue a MTNBSF command (backward space
288 count files to BOF).
289 v\n Return the version of the rmt server. This is
291 currently the decimal number 1.
292 Any other command causes rmt to exit.
294
296 /etc/default/rmt
297 The file /etc/default/rmt allows to set up rules to limit the
298 accessibility of files based on rules. This feature is typi‐
299 cally used when the rmt run from a non personal but task spe‐
300 cific login.
301 Default values can be set for the following options in
303 /etc/default/rmt. For example:
304 DEBUG=/tmp/rmt.debug
306 USER=tape
307 ACCESS=tape myhost.mydomain.org /dev/rmt/*
308 All keywords must be on the beginning of a line.
310 DEBUG If you like to get debug information, set this to a file
312 name where rmt should put debug information.
313 USER The name of a user (local to the magnetic tape server)
315 that may use the services of the rmt server. More than
316 one USER=name line is possible. A line USER=* grants
317 access to all users.
318 ACCESS This keyword is followed by three parameters separated by
320 a TAB. The name of a user (local to the magnetic tape
321 server host) that may use the services of the rmt server
322 followed by the name of a host from where operation is
323 granted and a file specifier pattern for a file or file
324 sub tree that may be accessed if this ACCESS line
325 matches. More than one ACCESS=name host path line is
326 possible.
327 If standard input of rmt is not a socket from a remote
329 host, rmt will compare the host entry from
330 /etc/default/rmt with the following strings:
331 PIPE If stdin is a UNIX pipe.
333 If you like to allow remote connections that
335 use the ssh protocol, you need to use the word
336 PIPE instead of the real hostname in the match‐
337 ing ACCESS= line.
338 ILLEGAL_SOCKET
340 If getpeername() does not work for stdin.
341 NOT_IP If getpeername() works for stdin but is not
343 connected to an internet socket.
344
346 star(1), ufsdump(1), ufsrestore(1), intro(2), open(2), close(2),
347 read(2), write(2), ioctl(2), lseek(2), getpeername(3), rcmd(3),
348 rexec(3), strerror(3), mtio(7), rmtopen(3), rmtclose(3), rmtread(3),
349 rmtwrite(3), rmtseek(3), rmtioctl(3), rmtstatus(3)
350
353 All responses are send to the network connection. They use the form
354 described above.
355
357 To use rmt as a remote file access protocol you need to use the sym‐
358 bolic open modes as e.g. the O_CREAT flag is not unique between differ‐
359 ent architectures.
360 In order to allow this implementation to be used as a remote file
362 access protocol, it accepts file names up to 4096 bytes with the open
363 command. Other rmt implementations allow no more than 64 bytes.
364 The possibility to create a debug file by calling rmt file has been
366 disabled for security reasons. If you like to debug rmt edit
367 /etc/default/rmt and insert a DEBUG entry.
368 This implementation of rmt adds some security features to the server
370 that make it behave slightly different from older implementations.
371 Read the above documentation about the file /etc/default/rmt to make
372 sure your local installation is configured for your needs.
373 To grant the same permissions as with old rmt servers, create a file
375 /etc/default/rmt and add the following lines to this file:
376 USER=*
378 ACCESS=* * *
379 Note that the three fields in the ACCESS= line need to be separated by
381 a TAB character.
382 Be very careful when designing patterns to match path names that may be
384 accepted for open. If a pattern would allow to include /../ in the
385 path, a possible intruder could virtually access any path on your sys‐
386 tem. For this reason, /../ is not allowed to appear in a path regard‐
387 less of the pattern.
388
390 None known.
391
393 The rmt command first appeared on BSD in march 1981. This rmt server is
394 a new implementation that tries to be compatible to all existing imple‐
395 mentations. It is the only known implementation that in addition tries
396 to fix the data exchange problems between different architectures.
397
400 Joerg Schilling
401 Seestr. 110
402 D-13353 Berlin
403 Germany
404 Mail bugs and suggestions to:
406 joerg.schilling@fokus.fraunhofer.de or js@cs.tu-berlin.de or
408 joerg@schily.isdn.cs.tu-berlin.de
409Joerg Schilling Release 1.1 RMT(1)