contrib/t2hproxy/README

   1 T2hproxy
   2
   3 This is a TFTP to HTTP proxy. To the TFTP client it looks like a TFTP
   4 server. To the HTTP server it looks like a HTTP client. So you can store
   5 your boot files on the HTTP server. Or even create them with a CGI
   6 program. E.g. if you can get dhcpd to send a filename which has strings
   7 representing attributes of the client, as determined from the DHCP
   8 request, then you can get the CGI program to parse this and send the
   9 appropriate image, which might even be synthesised.
  10
  11 There are two versions of the proxy, in Perl and in Java.
  12
  13 1. The Perl version.
  14
  15 This is the original quick Perl hack conceived in a moment of madness.
  16 :-) Perl is great for prototyping.
  17
  18 To run it, you need Perl 5.8.0 or later and all the Perl modules listed
  19 at the top of the program installed. Edit and install the xinetd config
  20 file as /etc/xinetd.d/t2hproxy and restart xinetd. The prefix is the
  21 string that is prepended to all filenames to form the URL requested from
  22 the HTTP server. Remember you need the trailing / if the filenames don't
  23 start with /.
  24
  25 This is only a proof-of concept. It has these drawbacks at the moment:
  26
  27 + (I don't consider this a draback, but some may.) It's started from
  28 xinetd because xinetd handles all the socket listening, IP address
  29 checking, rate limiting, etc.
  30
  31 + It has no cache. Use a proxy to do the caching (there's a --proxy
  32 option). This also takes care of fetching from outside a firewall.
  33
  34 + It reads the entire HTTP content into memory before serving. Ideally
  35 it should stream it from the HTTP server to minimise memory usage. This
  36 is a serious drawback for booting lots of clients. Each instance of the
  37 server will consume an amount of memory equal to the size of image
  38 loaded.
  39
  40 + If the HTTP server is at the end of a slow link there is a delay
  41 before the first data block is sent.  The client may timeout before
  42 then.  Another reason for streaming, as this allows the first block to
  43 be sent sooner.  A local cache primed with the images in advance may
  44 help. Using the blocksize option helps here because this causes the
  45 server to send the OACK to the client immediately before the data is
  46 fetched and this prevents it from starting up another connection.
  47
  48 + The transfer size may not be obtainable from the HTTP headers in all
  49 cases, e.g. a CGI constructed image. This matters for clients that need
  50 the tsize extension, which is not supported at the moment.
  51
  52 If I'm feeling masochistic I may write a Java version, which should take
  53 care of the multi-threading and streaming.
  54
  55 2. The Java version
  56
  57 The main problem with the Perl version is that it does not stream the
  58 HTTP input but sucks it all in at once. As mentioned, this causes a
  59 delay as well as requiring memory to hold the image. I could fix this by
  60 doing the polling on the HTTP socket myself instead of letting LWP do
  61 it, but that's for later. Java has streaming facilities as well as
  62 threading and is also somewhat portable.  So I decided to be masochistic
  63 and give it a go.  But boy is Java bureaucratic.
  64
  65 You will need a Java 1.4 JRE, because I use the java.nio classes; and
  66 the commons-httpclient and commons-logging jars from the
  67 jakarta.apache.org project. As I understand it, there are several ways
  68 to get those jars on your classpath. One is to put it in the directory
  69 where your java extensions jars are kept, normally
  70 $JAVA_HOME/jre/lib/ext. But it may not be writable to you. Another is to
  71 set your $CLASSPATH variable to have those jars in the path. A third is
  72 to use the -cp option of the java interpreter, see the shell script
  73 runT2hproxy for details.
  74
  75 All the source is in one Java file. build.xml is a "Makefile" for ant to
  76 compile and jar it. You should then edit runT2proxy.sh as required, then
  77 start it. As with the Perl version, the prefix is what's prepended to
  78 the filenames requested by the TFTP client, and the proxy is the
  79 host:port string for the proxy if you are using one. On *ix you will
  80 need root permission to listen on ports below 1024 (TFTP is at 69 UDP by
  81 default).
  82
  83 Currently it logs to stderr, but you can change this by downloading and
  84 installing the log4j jar from jakarta.apache.org and instructing
  85 commons-logging to use that, with a command line property setting and a
  86 property file.  Destinations could be syslog, or a file, or an event
  87 logger, or...; it's supposedly very flexible.
  88
  89 3. Licensing
  90
  91 All this code is GPLed. For details read the file COPYING found in the
  92 Etherboot top directory since it currently bundled with Etherboot. I
  93 don't see the point of including COPYING in every directory.
  94
  95 Ken Yap, October 2003