Net::TFTPd(3pm)

💖 Net::TFTPd — the manual, but make it cute 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about Net::TFTPd, a Perl extension that gives you a whole Trivial File Transfer Protocol server. yes really. a whole server. in Perl. she's serving (literally) ✨

---

🌸 NAME 🌸

Net::TFTPd — Perl extension for Trivial File Transfer Protocol Server 🎀

---

🦋 SYNOPSIS 🦋

the vibe is: you make a listener, you wait for a request, you process that request, you brag about the bytes. periodt.

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;

no cap, that's the whole lifecycle right there 🫶

---

💜 DESCRIPTION 💜

Net::TFTPd is a class that implements a simple Trivial File Transfer Protocol server in Perl, exactly as described in RFC1350. she's a whole class. she does the thing.

and not only that — Net::TFTPd also supports the TFTP Option Extension (as described in RFC2347), with these options:

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

like?? she read the RFCs so you don't have to. iconic behavior 👑

---

✨ EXPORT ✨

None by default. nope, not a single thing. you gotta ask. consent is key 💅

🎀 %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
);

it goes both ways. number → name, name → number. bilingual queen 🧚

---

🌈 Listener constructor 🌈

new() 🌟

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

or, if you prefer the arrow-y way:

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

so what's happening: you create a new Net::TFTPd object. 'path/to/files' is the default path to the file repository, OR 'path/to/file' is the single file that's allowed for download (pick one, bestie), and OPTIONS are the default server options. ✨

valid options are:

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

NOTE: IPv6 requires IO::Socket::IP. Failback is IO::Socket::INET and only IPv4 support. so if you're trying to be all v6 and fancy without IO::Socket::IP, she will simply not. 😭

🍓 CallBack 🍓

the CallBack code gets called by the processRQ method for each transferred block. every. single. one. she's keeping you posted fr fr.

the code receives (into the @_ array) a reference to the 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;

look at her, peeking at '_REQUEST_' internals like it's nothing. nosy in the best way 🙈

---

💫 Listener methods 💫

waitRQ() ⏳

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

waits for a client request (RRQ or WRQ) and returns a $request object, or undef if it timed out. she's just sitting there, patiently, like a bestie waiting for you to text back.

if Timeout is missing, the timeout defined for the $listener object is used instead. respect the defaults. 💅

when the method returns, the program should fork() and process the request by invoking processRQ(), while the parent process should re-start waiting for another request. yes, that's the whole pattern — parent keeps listening, child does the work. main character energy for the parent, side quest for the child 👑

---

🌟 Request methods 🌟

processRQ() 🔥

$ret = $request->processRQ();

processes a request and returns 1 if success, undef if error. that's it, that's the method.

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 the IO::Socket::* object for the created server. all IO::Socket::* accessors can then be called. go wild, she's giving you the whole socket 💖

getPeerAddr() 📍

$ret = $request->getPeerAddr();

returns the address of the requesting client.

getPeerPort() 🔌

$ret = $request->getPeerMode();

returns the port of the requesting client.

(ngl that's exactly what the page says — the method is getPeerPort() and the call inside is $request->getPeerMode(). i'm not touching it. i report, you decide 🙈)

getTotalBytes() 🧮

$ret = $request->getTotalBytes();

returns the number of bytes transferred for the request. the receipts!! 💅

---

💐 CREDITS 💐

thanks to Michael Vincent (<<VINSWORLD>>) for the NETASCII support, transferred bytes and IPv6 patches. king behavior, we love to see it 🫶✨

---

👑 AUTHOR 👑

Luigino Masarati, <lmasarati@hotmail.com> 💖

---

🌈 SEE ALSO 🌈

Net::TFTP.

---

and that's the whole page bestie!! this one goes out as perl v5.36.0, dated 2022-10-13, from the lovely folks in the User Contributed Perl Documentation corner of the world 🎀 go transfer some files, you got this 💜🦋