Net::TFTPd - Perl extension for Trivial File Transfer Protocol Server

- NAME
- SYNOPSIS
- DESCRIPTION
- EXPORT

- %OPCODES

- Listener constructor

- `new()`
- CallBack

- Listener methods

- `waitRQ()`

- Request methods

- `processRQ()`
- `getFileName()`
- `getMode()`
- `getBlkSize()`
- `server()`
- `getPeerAddr()`
- `getPeerPort()`
- `getTotalBytes()`

- CREDITS
- AUTHOR
- SEE ALSO

# NAME

Net::TFTPd - Perl extension for Trivial File Transfer Protocol Server

# SYNOPSIS

      use strict;
      use Net::TFTPd;

      my $tftpdOBJ = Net::TFTPd->new('RootDir' => 'path/to/files')
        or die "Error creating TFTPd listener: %s", Net::TFTPd->error;

      my $tftpRQ = $tftpdOBJ->waitRQ(10)
        or die "Error waiting for TFTP request: %s", Net::TFTPd->error;

      $tftpRQ->processRQ()
        or die "Error processing TFTP request: %s", Net::TFTPd->error;

      printf "%u bytes has been transferred", $tftpRQ->getTotalBytes() || 0;

# DESCRIPTION

`Net::TFTPd` is a class implementing a simple Trivial File Transfer Protocol server in Perl as described in RFC1350.

`Net::TFTPd` also supports the TFTP Option Extension (as described in RFC2347), with the following options:

      RFC2348 TFTP Blocksize Option
      RFC2349 TFTP Timeout Interval and Transfer Size Options

# EXPORT

None by default.

## %OPCODES

The %OPCODES tag exports the %OPCODES hash:

      %OPCODES = (
        1       => 'RRQ',
        2       => 'WRQ',
        3       => 'DATA',
        4       => 'ACK',
        5       => 'ERROR',
        6       => 'OACK',
        'RRQ'   => 1,
        'WRQ'   => 2,
        'DATA'  => 3,
        'ACK'   => 4,
        'ERROR' => 5,
        'OACK'  => 6
      );

# Listener constructor

## `new()`

      $listener = new Net::TFTPd( ['RootDir' => 'path/to/files' | 'FileName' => 'path/to/file'] [, OPTIONS ] );

or

      $listener = Net::TFTPd->new( ['RootDir' => 'path/to/files' | 'FileName' => 'path/to/file'] [, OPTIONS ] );

Create a new Net::TFTPd object where 'path/to/files' is the default path to file repository or 'path/to/file' is the single file allowed for download, and OPTIONS are the default server options.

Valid options are:

      Option     Description                                        Default
      ------     -----------                                        -------
      LocalAddr  Interface to bind to (for multi-homed server)          any
      LocalPort  Port to bind server to                                  69
      Timeout    Timeout in seconds to wait for a request                10
      ACKtimeout Timeout in seconds to wait for an ACK packet             4
      ACKretries Maximum number of retries waiting for ACK                4
      Readable   Clients are allowed to read files                        1
      Writable   Clients are allowed to write files                       0
      BlkSize    Minimum blocksize to negotiate for transfers           512
      CallBack   Reference to code executed for each transferred block    -
      Debug      Activates debug mode (verbose)                           0
      Family     Address family IPv4/IPv6                              IPv4
                   Valid values for IPv4:
                     4, v4, ip4, ipv4, AF_INET (constant)
                   Valid values for IPv6:
                     6, v6, ip6, ipv6, AF_INET6 (constant)

NOTE: IPv6 requires IO::Socket::IP. Failback is IO::Socket::INET and only IPv4 support.

## CallBack

The CallBack code is called by processRQ method for each tranferred block.

The code receives (into @_ array) a reference to internal $request object.

Example:

      sub callback
      {
        my $req = shift;
        printf "block: %u\/%u\n", $req->{'_REQUEST_'}{'LASTACK'}, $req->{'_REQUEST_'}{'LASTBLK'};
      }

      my $tftpdOBJ = Net::TFTPd->new('RootDir' => 'c:/temp', 'Timeout' => 60, 'CallBack' => \&callback) or die Net::TFTPd->error;

# Listener methods

## `waitRQ()`

      $request = $listener->waitRQ([Timeout]);

Waits for a client request (RRQ or WRQ) and returns a $request object or undef if timed out.

If Timeout is missing, the timeout defined for $listener object is used instead.

When the method returns, the program should `fork()` and process the request invoking `processRQ()` while the parent process should re-start waiting for another request.

# Request methods

## `processRQ()`

      $ret = $request->processRQ();

Processes a request and returns 1 if success, undef if error.

## `getFileName()`

      $ret = $request->getFileName();

Returns the requested file name.

## `getMode()`

      $ret = $request->getMode();

Returns the transfer mode for the request.

## `getBlkSize()`

      $ret = $request->getBlkSize();

Returns the block size used for the transfer.

## `server()`

      $ret = $request->server();

Return IO::Socket::* object for the created server. All IO::Socket::* accessors can then be called.

## `getPeerAddr()`

      $ret = $request->getPeerAddr();

Returns the address of the requesting client.

## `getPeerPort()`

      $ret = $request->getPeerMode();

Returns the port of the requesting client.

## `getTotalBytes()`

      $ret = $request->getTotalBytes();

Returns the number of bytes transferred for the request.

# CREDITS

Thanks to Michael Vincent (<VINSWORLD>) for the NETASCII support, transferred bytes and IPv6 patches.

# AUTHOR

Luigino Masarati, <lmasarati@hotmail.com>

# SEE ALSO

the Net::TFTP manpage.

Net::TFTPd - Perl extension for Trivial File Transfer Protocol Server