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 You need to have a recent version of the WvStreams library and header files
  60 installed on your system to use WvTFTPd.  We recommend version 4.0 or higher.
  61 You can download WvStreams from
  62
  63     http://open.nit.ca/wiki/index.php?page=WvStreams
  64
  65 You also require the "pkg-config" program, unless you want to modify the
  66 Makefile and insert the appropriate paths.
  67
  68 WvTFTPd installs itself into <prefix>/sbin and the man page into
  69 <prefix>/man, where <prefix> is the same prefix to which WvStreams is
  70 installed (typically "/usr" or "/usr/local").  Again, edit the Makefile if
  71 you wish to change this.  Eventually WvTFTPd might have a configure script
  72 to do this.
  73
  74 To compile WvTFTPd, untar the package to somewhere like /usr/src and type
  75 "make".  If there were no errors, type "make install".  Root privileges are,
  76 of course, required to install the program.
  77
  78 Configuring WvTFTPd
  79 ===================
  80
  81 The configuration file for WvTFTPd is /etc/wvtftpd.conf.  WvTFTPd will
  82 run fine without any special configuration, but in order to take
  83 advantage of some of its special features, you'll need to create a
  84 configuration file.
  85
  86 The first section of the configuration file might look like this (default
  87 values are shown):
  88
  89 [TFTP]
  90 Base dir = /tftpboot/
  91 Port = 69
  92 Min Timeout = 100
  93 Max Timeout = 5000
  94 Max Timeout Count = 80
  95 Prefetch = 3
  96 Readonly = 1
  97 Default File =
  98 Strip Prefix =
  99 Overwrite existing file = 0
 100 Client directory = 0
 101 Create client directory = 0
 102
 103 "Base dir" is the default directory.  If a client requests a file
 104 without specifying the full path, the base dir is prepended.
 105
 106 "Port" specifies the port WvTFTP should use, if you don't want to use the
 107 standard, 69, for some reason.
 108
 109 "Min Timeout" gives the minimum timeout value in milliseconds.  WvTFTP will
 110 retransmit if it does not get an answer in twice the average RTT thus far or
 111 the "Min Timeout" value, whichever is greater.  You can also specify a "Max
 112 Timeout" as the maximum waiting time until retransmission.
 113
 114 If the number of timeouts reaches "Max Timeout Count", the transfer is
 115 aborted.
 116
 117 "Prefetch" specifies the amount of negative latency, that is, how many
 118 packets are sent out at a time.
 119
 120 "Readonly" determines if TFTP writes are allowed.  The default is 1 (writes
 121 not allowed).
 122
 123 "Default File" is the file sent to a client if the requested file is
 124 unavailable.
 125
 126 The path given as "Strip Prefix" is automatically stripped from the
 127 beginning of any client requests.  This is done before adding "base dir".
 128
 129 "Overwrite existing file" specifies if existing files should be overwritten
 130 when the client uploads a file with the same name.  If the file exists and
 131 this is set to 0 then the upload will fail.  The default is to not overwrite
 132 existing files (0).
 133
 134 "Client directory" specifies if the client IP address should be appended to
 135 the "Base dir" when a file is uploaded. This will cause clients to upload
 136 into their own directory.  If the client directory does not exist and the
 137 "Create client directory" directive is set to false (0) then the upload will
 138 fail.  The default is to not append the client IP address to the "Base dir"
 139 when a file is uploaded (0).
 140
 141 "Create client directory" will create the client's directory when the client
 142 uploads a file (assuming "Client Directory" is set to 1; otherwise, this
 143 option does nothing).  The directory is a subdirectory of "Base dir" and is
 144 the IP address of the client (e.g /tftpboot/127.0.0.1). The default is to
 145 not create the client directory (0).
 146
 147 The second section is [TFTP Aliases].  It contains a list of filename
 148 overrides and per-client filename overrides. Regular filename overrides
 149 are of the form "filename = newfilename". Per-client filename overrides
 150 look like "IPAddress filename = clientnewfilename". Per-client filename
 151 overrides take precedence over regular overrides.
 152
 153 For example:
 154
 155 [TFTP Aliases]
 156 default/image = image2_4.img
 157 192.168.0.43/image = image2_5b.img
 158
 159 In this instance, if a user at 192.168.0.43 attempted to download the
 160 file "image", the file "image2_5b.img" would actually be sent.  Users
 161 from other machines will get the file "image2_4.img" when they request
 162 "image".
 163
 164 You can also specify one-time aliases in the [TFTP Alias Once] section.  The
 165 format is identical to [TFTP Aliases]; you may have global or per-client
 166 one-time aliases.  When a client asks for a file, WvTftp checks the [TFTP
 167 Alias Once] section first.  If a match is made, this alias is used, and when
 168 the download finishes the alias is removed from the section (regardless of
 169 whether the alias is global or client-specific).  Subsequent matching
 170 requests will then be checked against [TFTP Aliases] as normal.  Note that
 171 the [TFTP Alias Once] entry is only removed after a successful download; the
 172 entry will be left alone if a download fails.
 173
 174 The last sections are [Registered TFTP Clients] and [New TFTP Clients].
 175 [Registered TFTP Clients] holds a list of client IP addresses ("192.168.0.43
 176 = 1") that are known to the server.  When a client attempts to connect, if
 177 its address is not in [Registered TFTP Clients], it is added to [New TFTP
 178 Clients]. This has no function inside of WvTFTP itself but might be useful
 179 in some situations (such as in our Net Integrators).