wvtftp/README

   1 The Story of WvTFTPd
   2 or
   3 Why Would People Spend Time Writing a TFTP Server in this Day and Age?
   4 ======================================================================
   5
   6 WvTFTPd is a Trivial File Transfer Protocol server.
   7
   8 Why would anyone write a TFTP server in this day and age, you ask?  Well, TFTP
   9 can be useful, but we at Net Integration Technologies thought that we could
  10 make TFTP *much* more useful.  And using our WvStreams library, this task was
  11 actually pretty simple.
  12
  13 Here's a summary of what makes WvTFTPd special.
  14
  15 - The synchronous request/acknowledgement protocol used by TFTP was
  16   improved by cheating slightly and using a technique we call "Negative
  17   Latency".  This is a little time consuming to explain, but basically
  18   it means "sending data before the other end asks for it".  In case
  19   cheating on protocols worries people (as it should), we have tested
  20   our server with a couple different TFTP clients, and we haven't
  21   experienced any problems.  In addition, WvTFTPd ran 3.5 times faster
  22   than the other servers out there!
  23
  24 - in the traditional TFTP servers, when a client requests a file, that exact
  25   pathname needs to exist: even if tftpd is restricted to only serve files from
  26   /tftpboot, it still requires the /tftpboot as part of the filename.
  27   Our server doesn't mind if the client uses the full path or just a
  28   filename (in which case the file is fetched from the default
  29   directory).
  30
  31 - sometimes clients request the same file all the time, but you want to
  32   change which file goes with that client. For example, you might want
  33   to serve a different /tftpboot/kernel for different clients.  WvTFTPd
  34   makes this very easy to configure.
  35
  36 - port management: traditionally, tftp daemons run from inetd even
  37   though they use udp, which needs strange workarounds (flushing buffers
  38   in odd places) and requires port number changes at bad times. ACK
  39   messages from the client go to a different port than the original
  40   request, which makes it hard to pass TFTP through a firewall.  WvTFTPd
  41   handles all connections on the standard TFTP port (69), so you only
  42   need to forward that port to get TFTP access through a firewall.
  43
  44 - "adaptive retransmission": The TFTP protocol specifies that either the server
  45   or the client can timeout and resend requests.  This can cause some duplicate
  46   traffic, especially if a client isn't written correctly and responds to old
  47   DATA packets.  WvTFTP ignores all requests for retransmission and instead
  48   will retransmit after not receiving an ACK for two times the average return
  49   trip time so far.  Minimum and maximum timeouts are configurable.  This also
  50   applies to TFTP writes.
  51
  52 - large files: Some TFTP clients and servers can't handle files above 31 MB,
  53   due to the fact that the block number will roll over.  WvTFTP isn't one of
  54   them.  If you experience this problem, get a better client.
  55
  56 Compiling and Installing WvTFTPd
  57 ================================
  58
  59
  60 Configuring WvTFTPd
  61 ===================
  62
  63 The configuration file for WvTFTPd is /etc/wvtftpd.conf.  WvTFTPd will
  64 run fine without any special configuration, but in order to take
  65 advantage of some of its special features, you'll need to create a
  66 configuration file.
  67
  68 The first section of the configuration file might look like this (default
  69 values are shown):
  70
  71 [TFTP]
  72 Base dir = /tftpboot/
  73 Port = 69
  74 Min Timeout = 100
  75 Max Timeout = 5000
  76 Max Timeout Count = 1000
  77 Prefetch = 3
  78 Readonly = 1
  79 Default File =
  80 Strip Prefix =
  81
  82 "Base dir" is the default directory.  If a client requests a file
  83 without specifying the full path, the base dir is prepended.
  84
  85 "Port" specifies the port WvTFTP should use, if you don't want to use the
  86 standard, 69, for some reason.
  87
  88 "Min Timeout" gives the minimum timeout value in milliseconds.  WvTFTP will
  89 retransmit if it does not get an answer in twice the average RTT thus far or
  90 the "Min Timeout" value, whichever is greater.  You can also specify a "Max
  91 Timeout" as the maximum waiting time until retransmission.
  92
  93 If the number of timeouts reaches "Max Timeout Count", the transfer is
  94 aborted.
  95
  96 "Prefetch" specifies the amount of negative latency, that is, how many
  97 packets are sent out at a time.
  98
  99 "Readonly" determines if TFTP writes are allowed.  The default is 1 (writes
 100 not allowed).
 101
 102 "Default File" is the file sent to a client if the requested file is
 103 unavailable.
 104
 105 The path given as "Strip Prefix" is automatically stripped from the
 106 beginning of any client requests.  This is done before adding "base dir".
 107
 108 The second section is [TFTP Aliases].  It contains a list of filename
 109 overrides and per-client filename overrides. Regular filename overrides
 110 are of the form "filename = newfilename". Per-client filename overrides
 111 look like "IPAddress filename = clientnewfilename". Per-client filename
 112 overrides take precedence over regular overrides.
 113
 114 For example:
 115
 116 [TFTP Aliases]
 117 image = image2_4.img
 118 192.168.0.43 image = image2_5b.img
 119
 120 In this instance, if a user at 192.168.0.43 attempted to download the
 121 file "image", the file "image2_5b.img" would actually be sent.  Users
 122 from other machines will get the file "image2_4.img" when they request
 123 "image".
 124
 125 You can also specify one-time aliases in the [TFTP Alias Once] section.  The
 126 format is identical to [TFTP Aliases]; you may have global or per-client
 127 one-time aliases.  When a client asks for a file, WvTftp checks the [TFTP
 128 Alias Once] section first.  If a match is made, this alias is used, and when
 129 the download finishes the alias is removed from the section (regardless of
 130 whether the alias is global or client-specific).  Subsequent matching
 131 requests will then be checked against [TFTP Aliases] as normal.  Note that
 132 the [TFTP Alias Once] entry is only removed after a successful download; the
 133 entry will be left alone if a download fails.
 134
 135 The last sections are [Registered TFTP Clients] and [New TFTP Clients].
 136 [Registered TFTP Clients] holds a list of client IP addresses ("192.168.0.43
 137 = 1") that are known to the server.  When a client attempts to connect, if
 138 its address is not in [Registered TFTP Clients], it is added to [New TFTP
 139 Clients]. This has no function inside of WvTFTP itself but might be useful
 140 in some situations (such as in our Net Integrators).