Obsolete code removal
[people/sha0/gpxe.git] / 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