tftp

COMMON DATA TYPES

      ServiceConfig = Options
      Options = [option()]
      option() -- see below

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}

Controls the level of debug printouts. The default is none.

{host, Host}

Host = hostname() see inet(3)

The name or IP address of the host where the TFTP daemon resides. This option is only used by the client.

{port, Port}

Port = int()

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 one is returned by the info/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}]} automatically 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 = int()

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 through a firewall.

{udp, Options}

Options = [Opt] see gen_udp:open/2

{use_tsize, Bool}

Bool = bool()

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 = int() | 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 = int() | 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. See read_file/3 and write_file/3.

The callback module must implement the tftp behavior, CALLBACK FUNCTIONS.

{logger, Module}

Module = module()()

Callback module for customized logging of error, warning and info messages. >The callback module must implement the tftp_logger behavior, LOGGER FUNCTIONS. The default module is tftp_logger.

{max_retries, MaxRetries}

MaxRetries = int()

Threshold for the maximal number of retries. By default the server/client will try to resend a message up to 5 times when the timeout expires.

CALLBACK FUNCTIONS

A tftp callback module should be implemented as a tftp behavior and export the functions listed below.

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 transferred 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 are 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 state is forwarded to the user and returned from read_file/3 or write_file/3.

If a callback (which performs the file access in the TFTP server) takes too long time (more than the double TFTP timeout), the server will abort the connection and send an error reply to the client. This implies that the server will release resources attached to the connection faster than before. The server simply assumes that the client has given up.

If the TFTP server receives yet another request from the same client (same host and port) while it already has an active connection to the client, it will simply ignore the new request if the request is equal with the first one (same filename and options). This implies that the (new) client will be served by the already ongoing connection on the server side. By not setting up yet another connection, in parallel with the ongoing one, the server will consumer lesser resources.