diff options
Diffstat (limited to 'gpxe/contrib/t2hproxy/README')
-rw-r--r-- | gpxe/contrib/t2hproxy/README | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/gpxe/contrib/t2hproxy/README b/gpxe/contrib/t2hproxy/README new file mode 100644 index 00000000..ce5e1e9b --- /dev/null +++ b/gpxe/contrib/t2hproxy/README @@ -0,0 +1,95 @@ +T2hproxy + +This is a TFTP to HTTP proxy. To the TFTP client it looks like a TFTP +server. To the HTTP server it looks like a HTTP client. So you can store +your boot files on the HTTP server. Or even create them with a CGI +program. E.g. if you can get dhcpd to send a filename which has strings +representing attributes of the client, as determined from the DHCP +request, then you can get the CGI program to parse this and send the +appropriate image, which might even be synthesised. + +There are two versions of the proxy, in Perl and in Java. + +1. The Perl version. + +This is the original quick Perl hack conceived in a moment of madness. +:-) Perl is great for prototyping. + +To run it, you need Perl 5.8.0 or later and all the Perl modules listed +at the top of the program installed. Edit and install the xinetd config +file as /etc/xinetd.d/t2hproxy and restart xinetd. The prefix is the +string that is prepended to all filenames to form the URL requested from +the HTTP server. Remember you need the trailing / if the filenames don't +start with /. + +This is only a proof-of concept. It has these drawbacks at the moment: + ++ (I don't consider this a draback, but some may.) It's started from +xinetd because xinetd handles all the socket listening, IP address +checking, rate limiting, etc. + ++ It has no cache. Use a proxy to do the caching (there's a --proxy +option). This also takes care of fetching from outside a firewall. + ++ It reads the entire HTTP content into memory before serving. Ideally +it should stream it from the HTTP server to minimise memory usage. This +is a serious drawback for booting lots of clients. Each instance of the +server will consume an amount of memory equal to the size of image +loaded. + ++ If the HTTP server is at the end of a slow link there is a delay +before the first data block is sent. The client may timeout before +then. Another reason for streaming, as this allows the first block to +be sent sooner. A local cache primed with the images in advance may +help. Using the blocksize option helps here because this causes the +server to send the OACK to the client immediately before the data is +fetched and this prevents it from starting up another connection. + ++ The transfer size may not be obtainable from the HTTP headers in all +cases, e.g. a CGI constructed image. This matters for clients that need +the tsize extension, which is not supported at the moment. + +If I'm feeling masochistic I may write a Java version, which should take +care of the multi-threading and streaming. + +2. The Java version + +The main problem with the Perl version is that it does not stream the +HTTP input but sucks it all in at once. As mentioned, this causes a +delay as well as requiring memory to hold the image. I could fix this by +doing the polling on the HTTP socket myself instead of letting LWP do +it, but that's for later. Java has streaming facilities as well as +threading and is also somewhat portable. So I decided to be masochistic +and give it a go. But boy is Java bureaucratic. + +You will need a Java 1.4 JRE, because I use the java.nio classes; and +the commons-httpclient and commons-logging jars from the +jakarta.apache.org project. As I understand it, there are several ways +to get those jars on your classpath. One is to put it in the directory +where your java extensions jars are kept, normally +$JAVA_HOME/jre/lib/ext. But it may not be writable to you. Another is to +set your $CLASSPATH variable to have those jars in the path. A third is +to use the -cp option of the java interpreter, see the shell script +runT2hproxy for details. + +All the source is in one Java file. build.xml is a "Makefile" for ant to +compile and jar it. You should then edit runT2proxy.sh as required, then +start it. As with the Perl version, the prefix is what's prepended to +the filenames requested by the TFTP client, and the proxy is the +host:port string for the proxy if you are using one. On *ix you will +need root permission to listen on ports below 1024 (TFTP is at 69 UDP by +default). + +Currently it logs to stderr, but you can change this by downloading and +installing the log4j jar from jakarta.apache.org and instructing +commons-logging to use that, with a command line property setting and a +property file. Destinations could be syslog, or a file, or an event +logger, or...; it's supposedly very flexible. + +3. Licensing + +All this code is GPLed. For details read the file COPYING found in the +Etherboot top directory since it currently bundled with Etherboot. I +don't see the point of including COPYING in every directory. + +Ken Yap, October 2003 |