Index of /autoboot
Name Last modified Size Description
![[DIR]](/icons/back.gif)
Parent Directory 27-May-2007 23:43 -
![[ ]](/icons/compressed.gif)
autoboot-20050827.ta..> 27-Aug-2005 00:22 65k GZIP compressed docume>
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 <mtg@elsat.net.pl>. 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.