Setting up a diskless boot

In this section I assume you want to boot a Linux kernel. Booting a FreeBSD kernel is documented elsewhere and does not require a generating a boot image. Booting a DOS kernel is similar, the main differences being in the way you set up the boot image.

Making a boot image

Etherboot expects to download a boot image in either ELF or tagged format containing the code to be executed. Briefly explained, a boot image has a wrapper around the pieces of code or data that need to be put in various places in the computer's memory. It contains a directory telling how large the pieces are and where they go in memory. It also says where to start execution.

A boot image is created using a utility program. The utility program is specific to the kernel you want to load. The version for Linux is called mkelf-linux or mknbi-linux and that for DOS is mknbi-dos. These utilities are distributed separately and can be obtained from Etherboot web site.

Compiling a custom kernel

The preferred method of running applications on the booted machine is to package an initial ramdisk (initrd) along with the kernel. This initrd can either provide all the files necessary for running the application (at a cost of using RAM to hold the files) or mount NFS filesystems to obtain other files. Therefore you will need to compile ramdisk options in your kernel. For an example of how an initrd is created and packaged, see the LTSP project sources.

After you have compiled the kernel, make the boot image, like this:

	mkelf-linux --output=/tftpdir/xterm.nb zImage initrd.gz
This puts the image in where the tftp daemon expects to find it, in this example /tftpdir. Make sure it is world-readable because typically the tftp daemon runs as an unprivileged user. It is recommended that you set a path explicitly for tftpd instead of relying on any defaults. For example, for inetd, the entry in /etc/inetd.conf looks like this (xinetd uses a different syntax, check the documentation):

tftp	dgram	udp	wait	root	/usr/sbin/tcpd	in.tftpd /tftpdir

Setting up a DHCP daemon

You need to set up a DHCP server to hand out an IP address and other configuration information to the client.

The main requirement of the DHCP server is that it needs to send out suitable configuration information. Prior to version 5.0.7, Etherboot accepted any DHCP offer (but see REQUIRE_VCI_ETHERBOOT below for an exception). Since version 5.0.7 Etherboot will not accept any DHCP offer where the server IP is empty (all zero) or the filename is empty. These offers are useless to Etherboot anyway so ignoring these offers will give it a better chance of picking the right DHCP server.

If you already have a DHCP server on your network for providing Windows clients with IP addresses, chances are that it is not a suitable DHCP server because it's only tailored to the single purpose of handing out client addresses. Suitable DHCP servers include the ISC DHCPD, available for most Unix/Linux systems. You can run such a DHCP server in parallel with the Windows one, provided you do not attempt to give Windows clients leases, in which case there would be a clash. You can exclude Windows clients in two ways. One is to register the only the MAC addresses of the diskless clients in /etc/dhcpd.conf, and to make sure that the server is declared "not authoritative". The second is to look for the Vendor Class Identifier of "Etherboot-5.x" in the DHCP discover packet.

If you already have a DHCP server on your network that does provide the server IP and the filename, then you have to either use that DHCP server by editing its configuration file. This may require the cooperation of the system admin if you are not the admin. If you are not able to configure the DHCP server, then proceed to the section on REQUIRE_VCI_ETHERBOOT.

The minimum information you need to put in /etc/dhcpd.conf is:

  1. The domain name of the machine.

  2. The Ethernet (MAC) address of the network card, which you generally obtain from a sticker on the card, a configuration program for the card, or in the last resort, from watching the output of Etherboot or from the packets sent from the card when trying to boot, using the debug option of DHCPD.

  3. The name of the boot image file, relative to the tftpdir directory.

  4. The IP address you intend to give it, or the dynamic range it is to come from.

  5. The TFTP server defaults to the DHCP server if not specified with next-server.

Here is a sample DHCP configuration for ISC dhcpd:

option domain-name "ken.net.au";
option domain-name-servers 192.168.0.1;
option broadcast-address 192.168.0.255;
use-host-decl-names on;
subnet 192.168.0.0 netmask 255.255.255.0 {
	host xterm {
		hardware ethernet 08:00:2B:B7:F3:80;
		fixed-address xterm.ken.net.au;
		filename "/tftpdir/xterm.nb";
	}
}
The declaration "use-host-decl-names on" tells dhcpd to include the name xterm in the reply so that it can be used as part of pathname to mount by NFS, etc.

If your tftp server is not the same as the DHCP server, use the next-server declaration to specify a tftp server.

The 2.4.4 and above kernels can do a separate DHCP request to obtain an address. Kernels in the 2.2 series use BOOTP. However user space DHCP configuration is now preferred.

More information about DHCP can be found at the DHCP FAQ.

If you are on a local network that is not directly connected to the Internet, you can use the "private" IP addresses 192.168.x.y (or in the other ranges mentioned in RFC1918). Otherwise please ask either your network administrator or your Internet service provider for your own IP address(es).

You could use a bootp daemon instead of a DHCP daemon. However DHCP is preferred as DHCP provides more information to control the boot process. Also there is a bug in some old versions of bootpd where unnecessarily large reply packets are sent, causing packet fragmentation at the UDP level, and dropping of the packets by Etherboot. DHCPD can emulate bootpd if that's what you really want.

REQUIRE_VCI_ETHERBOOT

You may need to Etherboot in an environment where you have to install your own DHCP server, and it may interfere with the existing DHCP server. Etherboot has a feature designed to overcome this problem. It consists of two parts:

The first part is Etherboot contains code that when it sends out a DHCPDISCOVER request, a tag containing a Vendor Class Identifier of "Etherboot-x.y" is sent out, where x.y is the version number, currently 5.2. The 5 and the 2 are printable digits, not binary values, i.e. byte values 53 and 50 respectively. This allows the server to identify Etherboot clients and ignore all others.

The second part is Etherboot can be conditionally compiled to require a Vendor Encapsulated Option containing a VCI of "Etherboot", otherwise it will ignore the DHCPOFFER. The option is not compiled in by default because it would cause Etherboot to not boot in plain setups. The server we want to respond will include this tag in DHCPOFFERs and while other servers (e.g. Windows servers) may respond, they will be ignored.

Vendor Encapsulated Option is supported in ISC DHCPD 2 or 3. (It's not documented in DHCPD 2, but it works.) Other DHCP servers may support VEO. (It's a RFC2132 option.) In ISC DHCPD 3, follow the documentation for declaring a VEO scope. In ISC DHCPD 2 the magic line required is:

option vendor-encapsulated-options 3c:09:45:74:68:65:72:62:6f:6f:74:ff;
Put this in the appropriate scope. Translation: Vendor Encapsulation Options (Option 43) encloses: Vendor Class Identifier (Option 60 = 0x3c), length 9, value "Etherboot"; End of Options (Option 255 = 0xff).

If you have a DHCP server already running for the subnet, you probably should specify that your additional ISC DHCPD server is not authoritative for the the subnet, or it will veto (NAK) existing client IP address allocations, upsetting the status quo. See the ISC DHCPD options documentation.

Here is a practical document describing how it is done.

Setting up a tftp daemon

Now set up a tftp daemon. This means installing the tftp package and making sure that the tftp service is active in /etc/inetd.conf. If you want to be very careful you may wish to use the secure (-s) option of tftpd, this chroots to the specified directory, but then your pathnames in /etc/dhcpd.conf must be relative to the new root directory.

If you are booting many clients you should be aware of the limitations of running tftpd from inetd. Typically inetd has limits on how often a daemon can be spawned, to detect runaway daemons. If many clients request the tftp service within a short period, inetd may shutdown that service. If you have a setup where there are many clients, it may be better to use an improved replacement for inetd, such as xinetd. Another possibility is to install a better tftp daemon like atftp at the Etherboot web site. This one can be run as a standalone daemon, avoiding *inetd limitations and it multithreads internally.