1tftp(3) Erlang Module Definition tftp(3)
2
6 tftp - Trivial FTP.
7
9 This is a complete implementation of the following IETF standards:
10 * RFC 1350, The TFTP Protocol (revision 2)
12 * RFC 2347, TFTP Option Extension
14 * RFC 2348, TFTP Blocksize Option
16 * RFC 2349, TFTP Timeout Interval and Transfer Size Options
18 The only feature that not is implemented is the "netascii" transfer
20 mode.
21 The start/1 function starts a daemon process listening for UDP packets
23 on a port. When it receives a request for read or write, it spawns a
24 temporary server process handling the transfer.
25 On the client side, function read_file/3 and write_file/3 spawn a tem‐
27 porary client process establishing contact with a TFTP daemon and per‐
28 form the file transfer.
29 tftp uses a callback module to handle the file transfer. Two such call‐
31 back modules are provided, tftp_binary and tftp_file. See read_file/3
32 and write_file/3 for details. You can also implement your own callback
33 modules, see CALLBACK FUNCTIONS. A callback module provided by the user
34 is registered using option callback, see DATA TYPES.
35
37 A TFTP server can be configured to start statically when starting the
38 Inets application. Alternatively, it can be started dynamically (when
39 Inets is already started) by calling the Inets application API
40 inets:start(tftpd, ServiceConfig) or inets:start(tftpd, ServiceConfig,
41 How), see inets(3) for details. The ServiceConfig for TFTP is described
42 in the DATA TYPES section.
43 The TFTP server can be stopped using inets:stop(tftpd, Pid), see
45 inets(3) for details.
46 The TPFT client is of such a temporary nature that it is not handled as
48 a service in the Inets service framework.
49
51 ServiceConfig = Options
52 Options = [option()]
54 Most of the options are common for both the client and the server side,
56 but some of them differs a little. The available option()s are as fol‐
57 lows:
58 {debug, Level}:
60 Level = none | error | warning | brief | normal | verbose | all
61 Controls the level of debug printouts. Default is none.
63 {host, Host}:
65 Host = hostname(), see inet(3).
66 The name or IP address of the host where the TFTP daemon resides.
68 This option is only used by the client.
69 {port, Port}:
71 Port = int()
72 The TFTP port where the daemon listens. Defaults is the standard‐
74 ized number 69. On the server side, it can sometimes make sense to
75 set it to 0, meaning that the daemon just picks a free port (which
76 one is returned by function info/1).
77 If a socket is connected already, option {udp, [{fd, integer()}]}
79 can be used to pass the open file descriptor to gen_udp. This can
80 be automated by using a command-line argument stating the prebound
81 file descriptor number. For example, if the port is 69 and file
82 descriptor 22 is opened by setuid_socket_wrap, the command-line
83 argument "-tftpd_69 22" triggers the prebound file descriptor 22 to
84 be used instead of opening port 69. The UDP option {udp, [{fd,
85 22}]} is automatically added. See init:get_argument/ about command-
86 line arguments and gen_udp:open/2 about UDP options.
87 {port_policy, Policy}:
89 Policy = random | Port | {range, MinPort, MaxPort}
90 Port = MinPort = MaxPort = int()
92 Policy for the selection of the temporary port that is used by the
94 server/client during the file transfer. Default is random, which is
95 the standardized policy. With this policy a randomized free port is
96 used. A single port or a range of ports can be useful if the proto‐
97 col passes through a firewall.
98 {udp, Options}:
100 Options = [Opt], see gen_udp:open/2.
101 {use_tsize, Bool}:
103 Bool = bool()
104 Flag for automated use of option tsize. With this set to true, the
106 write_file/3 client determines the filesize and sends it to the
107 server as the standardized tsize option. A read_file/3 client
108 acquires only a filesize from the server by sending a zero tsize.
109 {max_tsize, MaxTsize}:
111 MaxTsize = int() | infinity
112 Threshold for the maximal filesize in bytes. The transfer is
114 aborted if the limit is exceeded. Default is infinity.
115 {max_conn, MaxConn}:
117 MaxConn = int() | infinity
118 Threshold for the maximal number of active connections. The daemon
120 rejects the setup of new connections if the limit is exceeded.
121 Default is infinity.
122 {TftpKey, TftpVal}:
124 TftpKey = string()
125 TftpVal = string()
126 Name and value of a TFTP option.
128 {reject, Feature}:
130 Feature = Mode | TftpKey
131 Mode = read | write
132 TftpKey = string()
133 Controls which features to reject. This is mostly useful for the
135 server as it can restrict the use of certain TFTP options or
136 read/write access.
137 {callback, {RegExp, Module, State}}:
139 RegExp = string()
140 Module = atom()
141 State = term()
142 Registration of a callback module. When a file is to be trans‐
144 ferred, its local filename is matched to the regular expressions of
145 the registered callbacks. The first matching callback is used dur‐
146 ing the transfer. See read_file/3 and write_file/3.
147 The callback module must implement the tftp behavior, see CALLBACK
149 FUNCTIONS.
150 {logger, Module}:
152 Module = module()()
153 Callback module for customized logging of errors, warnings, and
155 info messages. The callback module must implement the tftp_logger
156 behavior, see LOGGER FUNCTIONS. The default module is tftp_logger.
157 {max_retries, MaxRetries}:
159 MaxRetries = int()
160 Threshold for the maximal number of retries. By default the
162 server/client tries to resend a message up to five times when the
163 time-out expires.
164
166 change_config(daemons, Options) -> [{Pid, Result}]
167 Types:
169 Options = [option()]
171 Pid = pid()
172 Result = ok | {error, Reason}
173 Reason = term()
174 Changes configuration for all TFTP daemon processes.
176 change_config(servers, Options) -> [{Pid, Result}]
178 Types:
180 Options = [option()]
182 Pid = pid()
183 Result = ok | {error, Reason}
184 Reason = term()
185 Changes configuration for all TFTP server processes.
187 change_config(Pid, Options) -> Result
189 Types:
191 Pid = pid()
193 Options = [option()]
194 Result = ok | {error, Reason}
195 Reason = term()
196 Changes configuration for a TFTP daemon, server, or client
198 process.
199 info(daemons) -> [{Pid, Options}]
201 Types:
203 Pid = [pid()()]
205 Options = [option()]
206 Reason = term()
207 Returns information about all TFTP daemon processes.
209 info(servers) -> [{Pid, Options}]
211 Types:
213 Pid = [pid()()]
215 Options = [option()]
216 Reason = term()
217 Returns information about all TFTP server processes.
219 info(Pid) -> {ok, Options} | {error, Reason}
221 Types:
223 Options = [option()]
225 Reason = term()
226 Returns information about a TFTP daemon, server, or client
228 process.
229 read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallback‐
231 State} | {error, Reason}
232 Types:
234 RemoteFilename = string()
236 LocalFilename = binary | string()
237 Options = [option()]
238 LastCallbackState = term()
239 Reason = term()
240 Reads a (virtual) file RemoteFilename from a TFTP server.
242 If LocalFilename is the atom binary, tftp_binary is used as
244 callback module. It concatenates all transferred blocks and
245 returns them as one single binary in LastCallbackState.
246 If LocalFilename is a string and there are no registered call‐
248 back modules, tftp_file is used as callback module. It writes
249 each transferred block to the file named LocalFilename and
250 returns the number of transferred bytes in LastCallbackState.
251 If LocalFilename is a string and there are registered callback
253 modules, LocalFilename is tested against the regexps of these
254 and the callback module corresponding to the first match is
255 used, or an error tuple is returned if no matching regexp is
256 found.
257 start(Options) -> {ok, Pid} | {error, Reason}
259 Types:
261 Options = [option()]
263 Pid = pid()
264 Reason = term()
265 Starts a daemon process listening for UDP packets on a port.
267 When it receives a request for read or write, it spawns a tempo‐
268 rary server process handling the actual transfer of the (vir‐
269 tual) file.
270 write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCall‐
272 backState} | {error, Reason}
273 Types:
275 RemoteFilename = string()
277 LocalFilename = binary() | string()
278 Options = [option()]
279 LastCallbackState = term()
280 Reason = term()
281 Writes a (virtual) file RemoteFilename to a TFTP server.
283 If LocalFilename is a binary, tftp_binary is used as callback
285 module. The binary is transferred block by block and the number
286 of transferred bytes is returned in LastCallbackState.
287 If LocalFilename is a string and there are no registered call‐
289 back modules, tftp_file is used as callback module. It reads the
290 file named LocalFilename block by block and returns the number
291 of transferred bytes in LastCallbackState.
292 If LocalFilename is a string and there are registered callback
294 modules, LocalFilename is tested against the regexps of these
295 and the callback module corresponding to the first match is
296 used, or an error tuple is returned if no matching regexp is
297 found.
298
300 A tftp callback module is to be implemented as a tftp behavior and
301 export the functions listed in the following.
302 On the server side, the callback interaction starts with a call to
304 open/5 with the registered initial callback state. open/5 is expected
305 to open the (virtual) file. Then either function read/1 or write/2 is
306 invoked repeatedly, once per transferred block. At each function call,
307 the state returned from the previous call is obtained. When the last
308 block is encountered, function read/1 or write/2 is expected to close
309 the (virtual) file and return its last state. Function abort/3 is only
310 used in error situations. Function prepare/5 is not used on the server
311 side.
312 On the client side, the callback interaction is the same, but it starts
314 and ends a bit differently. It starts with a call to prepare/5 with the
315 same arguments as open/5 takes. prepare/5 is expected to validate the
316 TFTP options suggested by the user and to return the subset of them
317 that it accepts. Then the options are sent to the server, which per‐
318 forms the same TFTP option negotiation procedure. The options that are
319 accepted by the server are forwarded to function open/5 on the client
320 side. On the client side, function open/5 must accept all option as-is
321 or reject the transfer. Then the callback interaction follows the same
322 pattern as described for the server side. When the last block is
323 encountered in read/1 or write/2, the returned state is forwarded to
324 the user and returned from read_file/3 or write_file/3.
325 If a callback (performing the file access in the TFTP server) takes too
327 long time (more than the double TFTP time-out), the server aborts the
328 connection and sends an error reply to the client. This implies that
329 the server releases resources attached to the connection faster than
330 before. The server simply assumes that the client has given up.
331 If the TFTP server receives yet another request from the same client
333 (same host and port) while it already has an active connection to the
334 client, it ignores the new request if the request is equal to the first
335 one (same filename and options). This implies that the (new) client
336 will be served by the already ongoing connection on the server side. By
337 not setting up yet another connection, in parallel with the ongoing
338 one, the server consumes less resources.
339
341 Module:abort(Code, Text, State) -> ok
342 Types:
344 Code = undef | enoent | eacces | enospc
346 | badop | eexist | baduser | badopt
347 | int()
348 Text = string()
349 State = term()
350 Invoked when the file transfer is aborted.
352 The callback function is expected to clean up its used resources
354 after the aborted file transfer, such as closing open file
355 descriptors and so on. The function is not invoked if any of the
356 other callback functions returns an error, as it is expected
357 that they already have cleaned up the necessary resources. How‐
358 ever, it is invoked if the functions fail (crash).
359 Module:open(Peer, Access, Filename, Mode, SuggestedOptions, State) ->
361 {ok, AcceptedOptions, NewState} | {error, {Code, Text}}
362 Types:
364 Peer = {PeerType, PeerHost, PeerPort}
366 PeerType = inet | inet6
367 PeerHost = ip_address()
368 PeerPort = integer()
369 Access = read | write
370 Filename = string()
371 Mode = string()
372 SuggestedOptions = AcceptedOptions = [{Key, Value}]
373 Key = Value = string()
374 State = InitialState | term()
375 InitialState = [] | [{root_dir, string()}]
376 NewState = term()
377 Code = undef | enoent | eacces | enospc
378 | badop | eexist | baduser | badopt
379 | int()
380 Text = string()
381 Opens a file for read or write access.
383 On the client side, where the open/5 call has been preceded by a
385 call to prepare/5, all options must be accepted or rejected.
386 On the server side, where there is no preceding prepare/5 call,
388 no new options can be added, but those present in SuggestedOp‐
389 tions can be omitted or replaced with new values in AcceptedOp‐
390 tions.
391 Module:prepare(Peer, Access, Filename, Mode, SuggestedOptions, Initial‐
393 State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}
394 Types:
396 Peer = {PeerType, PeerHost, PeerPort}
398 PeerType = inet | inet6
399 PeerHost = ip_address()
400 PeerPort = integer()
401 Access = read | write
402 Filename = string()
403 Mode = string()
404 SuggestedOptions = AcceptedOptions = [{Key, Value}]
405 Key = Value = string()
406 InitialState = [] | [{root_dir, string()}]
407 NewState = term()
408 Code = undef | enoent | eacces | enospc
409 | badop | eexist | baduser | badopt
410 | int()
411 Text = string()
412 Prepares to open a file on the client side.
414 No new options can be added, but those present in SuggestedOp‐
416 tions can be omitted or replaced with new values in AcceptedOp‐
417 tions.
418 This is followed by a call to open/4 before any read/write
420 access is performed. AcceptedOptions is sent to the server,
421 which replies with the options that it accepts. These are then
422 forwarded to open/4 as SuggestedOptions.
423 Module:read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} |
425 {error, {Code, Text}}
426 Types:
428 State = NewState = term()
430 Bin = binary()
431 FileSize = int()
432 Code = undef | enoent | eacces | enospc
433 | badop | eexist | baduser | badopt
434 | int()
435 Text = string()
436 Reads a chunk from the file.
438 The callback function is expected to close the file when the
440 last file chunk is encountered. When an error is encountered,
441 the callback function is expected to clean up after the aborted
442 file transfer, such as closing open file descriptors, and so on.
443 In both cases there will be no more calls to any of the callback
444 functions.
445 Module:write(Bin, State) -> {more, NewState} | {last, FileSize} |
447 {error, {Code, Text}}
448 Types:
450 Bin = binary()
452 State = NewState = term()
453 FileSize = int()
454 Code = undef | enoent | eacces | enospc
455 | badop | eexist | baduser | badopt
456 | int()
457 Text = string()
458 Writes a chunk to the file.
460 The callback function is expected to close the file when the
462 last file chunk is encountered. When an error is encountered,
463 the callback function is expected to clean up after the aborted
464 file transfer, such as closing open file descriptors, and so on.
465 In both cases there will be no more calls to any of the callback
466 functions.
467
469 A tftp_logger callback module is to be implemented as a tftp_logger
470 behavior and export the following functions:
471
473 Logger:error_msg(Format, Data) -> ok | exit(Reason)
474 Types:
476 Format = string()
478 Data = [term()]
479 Reason = term()
480 Logs an error message. See error_logger:error_msg/2 for details.
482 Logger:info_msg(Format, Data) -> ok | exit(Reason)
484 Types:
486 Format = string()
488 Data = [term()]
489 Reason = term()
490 Logs an info message. See error_logger:info_msg/2 for details.
492 Logger:warning_msg(Format, Data) -> ok | exit(Reason)
494 Types:
496 Format = string()
498 Data = [term()]
499 Reason = term()
500 Logs a warning message. See error_logger:warning_msg/2 for
502 details.
503Ericsson AB inets 6.5.2.4 tftp(3)