summaryrefslogtreecommitdiff
path: root/lib/inets/src/tftp/tftp.erl
blob: 45d7852863ec0d5507fb8fc7becac18cee1f296a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
%%
%% %CopyrightBegin%
%% 
%% Copyright Ericsson AB 2005-2012. All Rights Reserved.
%% 
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%%
%%     http://www.apache.org/licenses/LICENSE-2.0
%%
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%% 
%% %CopyrightEnd%
%%
%%

%%%-------------------------------------------------------------------
%%% File    : tftp.erl
%%% Author  : Hakan Mattsson <hakan@erix.ericsson.se>
%%% Description : Trivial FTP
%%% Created : 18 May 2004 by Hakan Mattsson <hakan@erix.ericsson.se>
%%%-------------------------------------------------------------------
%%% 
%%% This is a complete implementation of the following IETF standards:
%%%
%%%    RFC 1350, The TFTP Protocol (revision 2).
%%%    RFC 2347, TFTP Option Extension.
%%%    RFC 2348, TFTP Blocksize Option.
%%%    RFC 2349, TFTP Timeout Interval and Transfer Size Options.
%%%
%%% The only feature that not is implemented in this release is
%%% the "netascii" transfer mode.
%%%
%%% The start/1 function starts a daemon process which, listens for
%%% UDP packets on a port. When it receives a request for read or
%%% write it spawns a temporary server process which handles the
%%% actual transfer of the file. On the client side the read_file/3
%%% and write_file/3 functions spawns a temporary client process which
%%% establishes contact with a TFTP daemon and performs the actual
%%% transfer of the file.
%%%
%%% Most of the options are common for both the client and the server
%%% side, but some of them differs a little. Here are the available
%%% options:
%%%     
%%%   {debug, Level}
%%%
%%%     Level = none | error | warning brief | normal | verbose | all
%%%     
%%%     Controls the level of debug printouts. The default is none.
%%%     
%%%   {host, Host}
%%%
%%%     The name or IP address of the host where the TFTP daemon
%%%     resides. This option is only used by the client. See
%%%     'inet' about valid host names.
%%%     
%%%   {port, Port}
%%%
%%%     Port = integer()
%%%     
%%%     The TFTP port where the daemon listens. It defaults to the
%%%     standardized number 69. On the server side it may sometimes
%%%     make sense to set it to 0, which means that the daemon just
%%%     will pick a free port (which is returned by the start/1
%%%     function).
%%%     
%%%     If a socket has somehow already has been connected, the
%%%     {udp, [{fd, integer()}]} option can be used to pass the
%%%     open file descriptor to gen_udp. This can be automated
%%%     a bit by using a command line argument stating the
%%%     prebound file descriptor number. For example, if the
%%%     Port is 69 and the file descriptor 22 has been opened by
%%%     setuid_socket_wrap. Then the command line argument
%%%     "-tftpd_69 22" will trigger the prebound file
%%%     descriptor 22 to be used instead of opening port 69.
%%%     The UDP option {udp, [{fd, 22}]} autmatically be added.
%%%     See init:get_argument/ about command line arguments and
%%%     gen_udp:open/2 about UDP options.
%%%
%%%   {port_policy, Policy}
%%%
%%%     Policy = random | Port | {range, MinPort, MaxPort}
%%%     Port = MinPort = MaxPort = integer()
%%%     
%%%     Policy for the selection of the temporary port which is used
%%%     by the server/client during the file transfer. It defaults to
%%%     'random' which is the standardized policy. With this policy a
%%%     randomized free port used. A single port or a range of ports
%%%     can be useful if the protocol should pass thru a firewall.
%%%   
%%%   {prebound_fd, InitArgFlag}
%%%
%%%     InitArgFlag = atom()
%%%
%%%     If a socket has somehow already has been connected, the
%%%     {udp, [{fd, integer()}]} option can be used to pass the
%%%     open file descriptor to gen_udp.
%%%
%%%     The prebound_fd option makes it possible to pass give the
%%%     file descriptor as a command line argument. The typical
%%%     usage is when used in conjunction with setuid_socket_wrap
%%%     to be able to open privileged sockets. For example if the
%%%     file descriptor 22 has been opened by setuid_socket_wrap
%%%     and you have choosen my_tftp_fd as init argument, the
%%%     command line should like this "erl -my_tftp_fd 22" and 
%%%     FileDesc should be set to my_tftpd_fd. This would 
%%%     automatically imply {fd, 22} to be set as UDP option.
%%%   
%%%   {udp, UdpOptions}
%%%
%%%      Options to gen_udp:open/2.
%%%
%%%   {use_tsize, Bool}
%%%
%%%     Bool = boolean()
%%%     
%%%     Flag for automated usage of the "tsize" option. With this set
%%%     to true, the write_file/3 client will determine the filesize
%%%     and send it to the server as the standardized "tsize" option.
%%%     A read_file/3 client will just acquire filesize from the
%%%     server by sending a zero "tsize".
%%%     
%%%   {max_tsize, MaxTsize}
%%%
%%%     MaxTsize = integer() | infinity
%%%     
%%%     Threshold for the maximal filesize in bytes. The transfer will
%%%     be aborted if the limit is exceeded. It defaults to
%%%     'infinity'.
%%%
%%%   {max_conn, MaxConn}
%%%   
%%%     MaxConn = integer() | infinity
%%%     
%%%     Threshold for the maximal number of active connections. The
%%%     daemon will reject the setup of new connections if the limit
%%%     is exceeded. It defaults to 'infinity'.
%%%     
%%%   {TftpKey, TftpVal}
%%%
%%%      TftpKey = string()
%%%      TftpVal = string()
%%%
%%%      The name and value of a TFTP option.
%%%      
%%%   {reject, Feature}
%%%   
%%%      Feature = Mode | TftpKey
%%%      Mode    = read | write
%%%      TftpKey = string()
%%%      
%%%      Control which features that should be rejected.
%%%      This is mostly useful for the server as it may restrict
%%%      usage of certain TFTP options or read/write access.
%%%
%%%   {callback, {RegExp, Module, State}}
%%%
%%%    	 RegExp = string()
%%%    	 Module = atom()
%%%    	 State  = term()
%%%    	 
%%%      Registration of a callback module. When a file is to be
%%%      transferred, its local filename will be matched to the
%%%      regular expressions of the registered callbacks. The first
%%%      matching callback will be used the during the transfer.The
%%%      callback module must implement the 'tftp' behaviour.
%%%
%%%      On the server side the callback interaction starts with a
%%%      call to open/5 with the registered initial callback
%%%      state. open/5 is expected to open the (virtual) file. Then
%%%      either the read/1 or write/2 functions are invoked
%%%      repeatedly, once per transfererred block. At each function
%%%      call the state returned from the previous call is
%%%      obtained. When the last block has been encountered the read/1
%%%      or write/2 functions is expected to close the (virtual)
%%%      file.and return its last state. The abort/3 function is only
%%%      used in error situations. prepare/5 is not used on the server
%%%      side.
%%%      
%%%      On the client side the callback interaction is the same, but
%%%      it starts and ends a bit differently. It starts with a call
%%%      to prepare/5 with the same arguments as open/5
%%%      takes. prepare/5 is expected to validate the TFTP options,
%%%      suggested by the user and return the subset of them that it
%%%      accepts. Then the options is sent to the server which will
%%%      perform the same TFTP option negotiation procedure. The
%%%      options that are accepted by the server is forwarded to the
%%%      open/5 function on the client side. On the client side the
%%%      open/5 function must accept all option as is or reject the
%%%      transfer. Then the callback interaction follows the same
%%%      pattern as described above for the server side. When the last
%%%      block is encountered in read/1 or write/2 the returned stated
%%%      is forwarded to the user and returned from read_file/3 or
%%%      write_file/3.
%%%-------------------------------------------------------------------

-module(tftp).

%%-------------------------------------------------------------------
%% Interface
%%-------------------------------------------------------------------

%% Public functions
-export([
	 read_file/3,
	 write_file/3,
	 start/1,
	 info/1,
	 change_config/2,
	 start/0
	]).

%% Application local functions
-export([
	 start_standalone/1,
	 start_service/1,
	 stop_service/1, 
	 services/0,
	 service_info/1
	]).


-type peer() :: {PeerType :: inet | inet6,
		 PeerHost :: inet:ip_address(),
		 PeerPort :: port()}.

-type access() :: read | write.

-type options() :: [{Key :: string(), Value :: string()}].

-type error_code() :: undef | enoent | eacces | enospc |
		      badop | eexist | baduser | badopt |
		      integer().

-callback prepare(Peer :: peer(),
		  Access :: access(),
		  Filename :: file:name(),
		  Mode :: string(),
		  SuggestedOptions :: options(),
		  InitialState :: [] | [{root_dir, string()}]) ->
    {ok, AcceptedOptions :: options(), NewState :: term()} |
    {error, {Code :: error_code(), string()}}.

-callback open(Peer :: peer(),
	       Access :: access(),
	       Filename :: file:name(),
	       Mode :: string(),
	       SuggestedOptions :: options(),
	       State :: [] | [{root_dir, string()}] | term()) ->
    {ok, AcceptedOptions :: options(), NewState :: term()} |
    {error, {Code :: error_code(), string()}}.

-callback read(State :: term()) -> {more, binary(), NewState :: term()} |
				   {last, binary(), integer()} |
				   {error, {Code :: error_code(), string()}}.

-callback write(binary(), State :: term()) ->
    {more, NewState :: term()} |
    {last, FileSize :: integer()} |
    {error, {Code :: error_code(), string()}}.

-callback abort(Code :: error_code(), string(), State :: term()) -> 'ok'.

-include("tftp.hrl").


%%-------------------------------------------------------------------
%% read_file(RemoteFilename, LocalFilename, Options) ->
%%   {ok, LastCallbackState} | {error, Reason}
%%
%% RemoteFilename     = string()
%% LocalFilename      = binary | string()
%% Options            = [option()]
%% LastCallbackState  = term()
%% Reason             = term()
%%
%% Reads a (virtual) file from a TFTP server
%%
%% If LocalFilename is the atom 'binary', tftp_binary will be used as
%% callback module. It will concatenate all transferred blocks and
%% return them as one single binary in the CallbackState.
%%
%% When LocalFilename is a string, it will be matched to the
%% registered callback modules and hopefully one of them will be
%% selected. By default, tftp_file will be used as callback module. It
%% will write each transferred block to the file named
%% LocalFilename. The number of transferred bytes will be returned as
%% LastCallbackState.
%%-------------------------------------------------------------------

read_file(RemoteFilename, LocalFilename, Options) ->
    tftp_engine:client_start(read, RemoteFilename, LocalFilename, Options).
    
%%-------------------------------------------------------------------
%% write(RemoteFilename, LocalFilename, Options) ->
%%   {ok, LastCallbackState} | {error, Reason}
%%
%% RemoteFilename    = string()
%% LocalFilename     = binary() | string()
%% Options           = [option()]
%% LastCallbackState = term()
%% Reason            = term()
%%
%% Writes a (virtual) file to a TFTP server
%% 
%% If LocalFilename is a binary, tftp_binary will be used as callback
%% module. The binary will be transferred block by block and the number
%% of transferred bytes will be returned as LastCallbackState.
%%
%% When LocalFilename is a string, it will be matched to the
%% registered callback modules and hopefully one of them will be
%% selected. By default, tftp_file will be used as callback module. It
%% will read the file named LocalFilename block by block. The number
%% of transferred bytes will be returned as LastCallbackState.
%%-------------------------------------------------------------------

write_file(RemoteFilename, LocalFilename, Options) ->
    tftp_engine:client_start(write, RemoteFilename, LocalFilename, Options).

%%-------------------------------------------------------------------
%% start(Options) -> {ok, Pid} | {error, Reason}
%% 
%% Options = [option()]
%% Pid     = pid()
%% Reason  = term()
%%
%% Starts a daemon process which listens for udp packets on a
%% port. When it receives a request for read or write it spawns
%% a temporary server process which handles the actual transfer
%% of the (virtual) file.
%%-------------------------------------------------------------------

start(Options) ->
    tftp_engine:daemon_start(Options).

%%-------------------------------------------------------------------
%% info(Pid) -> {ok, Options} | {error, Reason}
%% 
%% Options = [option()]
%% Reason  = term()
%%
%% Returns info about a tftp daemon, server or client process
%%-------------------------------------------------------------------

info(Pid) ->
    tftp_engine:info(Pid).

%%-------------------------------------------------------------------
%% change_config(Pid, Options) -> ok | {error, Reason}
%% 
%% Options = [option()]
%% Reason  = term()
%%
%% Changes config for a tftp daemon, server or client process
%% Must be used with care.
%%-------------------------------------------------------------------

change_config(Pid, Options) ->
    tftp_engine:change_config(Pid, Options).

%%-------------------------------------------------------------------
%% start() -> ok | {error, Reason}
%% 
%% Reason = term()
%%
%% Start the application
%%-------------------------------------------------------------------

start() ->
    application:start(inets).

%%-------------------------------------------------------------------
%% Inets service behavior
%%-------------------------------------------------------------------

start_standalone(Options) ->
    start(Options).

start_service(Options) ->
    tftp_sup:start_child(Options).

stop_service(Pid) ->
    tftp_sup:stop_child(Pid).

services() ->
    tftp_sup:which_children().

service_info(Pid) ->
    info(Pid).