1. OVERVIEW The autoboot package consists of two daemons enabling your provisioning server to run a script-controlled DHCP and/or TFTP service. Every client request is passed to an user-defined executable (typically a script) that decides what to return to the client on its own. The idea is a bit like the "inetd" superserver and may be useful primarly for advanced configurations in DOCSIS cable network environments. The package is indented for ADVANCED network administrators. A decent understanding of the DHCP protocol is practically REQUIRED to write a DHCP server control script... 2. REQUIREMENTS Currently, autoboot compiles only under Linux. Porting the package to another POSIX/BSD-compilant OS should not be a difficult task, though. 3. BUILDING AND INSTALLATION The package uses a standard Makefile - just cd to the autoboot-* directory and type make. There is no configuration script, so depending on your system, several warnings may appear. Also, there always exists a possibility that a particular header file (.h) is available under a different location on your system and you will have to correct the source. Sorry :-) After a successful compilation, two executables should be available in the main package directory - autotftp and autodhcp. To install autoboot, just copy these files to a convenient location, eg. /usr/local/sbin. 4. USAGE Invoke autodhcp and autotftp with the "-h" option to receive usage instructions. 4.1 AUTOTFTP A typical beginner's invocation of autotftp would look like: # autotftp -t 600 -a 2048 -f -e "./test.sh %ip% %file%" Here's a brief explanation of the options: -t 600 Request timeout. Tells autotftp to kill the script after 10 minutes whether any data was returned or not. -a 2048 Sets the heap size for flood protection to 2048 entries. As a rule of thumb, set this parameter to the numer of hosts that are expected to connect to the server. Nothing special happens if this value is set incorrectly: If the heap size is overestimated, autotftp just takes more memory (one heap entry = ~28 bytes). If the heap size is underestimated, the flood protection may just not work sometimes... -f Tells autotftp not to go into the background. In conjunction with the -e option (log to stderr instead of syslog), this provides a more friendly way to see the server activities while you are mastering its usage ;-) The command string "./test.sh %ip% %file%" tells autotftp to run test.sh from the current directory (remember to set the +x permission on your script!) every time a request is received. The script is being passed the client's IP address as $1 and the requested filename (after it is slightly censored - see the -u and -x option descriptions) as $2. Everything that is outputted on stdout by the script gets returned to the tftp client just like it would be the contents of the requested file. Autotftp does NOT perform full buffering of the returned data, so you do not have to worry about any memory being allocated if you, for example, intend to generate a 1GB file :) 4.2 AUTODHCP Again, a first-try startup of autodhcp would look like: # autodhcp -t 10 -f -e "./dhcp.sh" -t 10 Request timeout in seconds. This HAS to be a REASONABLE value - a DHCP server cannot process more than ONE request simoultaneously. -f As in autotftp, causes autodhcp not to go into the background -e As above, "log to stderr instead of syslog". The dhcp script is the moment where everything gets a bit complicated :-) The DHCP request packet is being decoded by the autodhcp into a human-readable plaintext format and is passed to the standard input of the called executable (dhcp.sh in this example; remember about the +x permission :-). The executable is expected to return the response packet in a similar format on its stdout. The response is then encoded into binary, sent to the client (or the relay), and the request is considered completed. Understanding the packet dump and constructing a valid response actually REQUIRES that you have some experience with the DHCP protocol... For instance, you have to know that DHCP message type 01 is a DHCPDISCOVER, 02 is DHCPOFFER, 03 a DHCPREQUEST, etc. Sorry. Bear in mind that this software is useful only for really specific needs. For everything else there is ISC DHCPD :-) Back to the thing, an example request dump looks like: ---------------------8<--- CUT HERE ---8<---------------------------- source ip: a0.0.0.0 source port: i68 flags: h00:00 client hardware: h00:11:e3:0e:70:57 transaction id: h71:78:E0:3D requested address: a0.0.0.0 your address: a0.0.0.0 next server: a0.0.0.0 relay: a0.0.0.0 message type: h01 57: h02:24 lease time: -1 55: h01:03:06:0C:0F:11:17:1C:1D:1F:21:28:29:2A 60: h4C:69:6E:75:78:20:32:2E:36:2E:39:20:69:36:38:36 61: h01:00:03:47:90:C0:F5 end of message ---------------------8<--- CUT HERE ---8<---------------------------- As you can see, the packet dump consists of option:value pairs, one per line. Some options have their names (transaction id, client hardware, etc. - see the following section for more information), some are represented only by their DHCP numeric value. Every packet dump always ends with a "end of message" string, on a separate line. The response is also expected to contain such a string. The first character of the value field denotes its encoding. Basically, "s" stands for ASCII string, "a" for IP address list, "h" for a colon-separated "hexadecimal" string, and "i" is a four-byte, network-order integer. A response forged by the script may look like: ---------------------8<--- CUT HERE ---8<---------------------------- transaction id: h00:00:30:22 relay: a10.253.100.2 server id: hBADCAFE0 router: a10.253.0.1 requested address: a10.253.103.212 your address: a10.253.103.212 client hardware: h00:08:0E:D8:30:22 next server: a10.253.100.4 boot filename: s10.253.103.212.cfg lease time: i86400 tftp server: s10.253.100.4 message type: h05 time offset: i3600 dns server: a217.173.160.35, 217.173.160.6 subnet mask: a255.255.0.0 flags: h80:00 end of message ---------------------8<--- CUT HERE ---8<---------------------------- This is not necesarilly a valid response for the request above :-) Please note that the request was a DHCPDISCOVER, and this is an DHCPACK. This is merely an illustration. For a working example, see the EXAMPLES section. The field order in the response is irrevelant. 4.2.1 SUPPORTED ALIASES The supported DHCP option/field aliases are: IP raw packet properties: source address (considered only if no relay was specified) DHCP packet fields: next server, flags, client hardware, transaction id, requested address, your address, relay, boot filename DHCP options: message type, subnet mask, time offset, router, time server, dns server, log server, hostname, domainname, arp timeout, lease time, server id, requested address, tftp server Both the client and the control script can provide any other DHCP options by just using the option number. 5. PACKAGE STABILITY We have been using this software (both the DHCP and TFTP part) for about half a year in a production environment consisting of few thousand cable modems and another few thousand customer equipment devices. Generally, it works(*). The TFTP server is rock-solid and we are not afraid not to use the -f option. As for the DHCP server, we would recommend putting a watchdog on it, for example by running it in a script like: while true; do ./autoboot/autodhcp -f -t 3 ./dhcp.sh sleep 30s done Or performing some other crontab-based magic... (*) Please note, however, that the GPL license implies that this software is provided as-is, with no warranties or responsibilites. 6. EXAMPLES A working example (our configuration) is provided in the examples/ subdirectory. dhcp.awk - this is our DHCP server control script for configuring cable modems and CPEs. No kidding, it's in AWK and it references a SQL server few times every single request. Hardcore, eh? dhcp.sh - a wrapper around dhcp.awk, not really required getconfig.php - this is our TFTP file generator for generating modem configuration on-the-fly. It takes the configuration file pattern from the modem.src file, applies the modem options using some SQL queries and Smarty substitution and then encodes it into a binary form using Evvolve's "docsis" config file generator (http://docsis.sf.net) modem.src - this is the modem configuration template The other files in this subdirectory are our unsignificant debugging tools... 7. BUGS AND LIMITATIONS * The package works only under Linux. * The DHCP server sometimes exits without a good reason :-/ * The documentation is really poor... but come on, this software is intended for ADVANCED users, you should not need any documentation at all :-) 8. AUTHOR AND CREDITS Mateusz 'mteg' Golicz . Feel free to send any comments, patches, bugfixes, suggestions, etc. The author is not a native english speaker, and is aware of the fact that his english is far from perfect. Because of that, reports on grammar and vocabulary mistakes in this file are also welcome. Please forgive me, but I really have forgotten where have I taken the IP/UDP checksumming routines from (rawsend.c). I am sure it was a (L)GPL project, but I cannot recall its name or authors... Surely, they should be given credit here :-) 9. LICENSE GNU GPL 2: Please have a look at the COPYING file included in the package. If any other licensing scheme is requested, do not hesitate to contact me.