This is the README file for the Etherboot package. This document explains how to install, configure and use the Etherboot package. The instructions here apply to version 4.0 of Etherboot.
Etherboot is a package for creating ROM images that can download code over the network to be executed on an x86 computer. Typically the computer is diskless and the code is Linux, but these are not the only possibilities. The code uses the bootp, tftp and NFS Internet Protocols.
Etherboot supports the following network hardware (in no particular order): 3c503, 3c507, 3c509, 3c905b, NE1000, NE2000 (also the PCI cards, with the nepci driver), WD8003, WD8013, SMC8216/8416, Lance based cards such as the NE2100 and NI6510 (also the PCI Lance cards), Crystal CS89x0, Intel EtherExpress Pro, SMC 83c170 EPIC/100, SMC9000, Realtek 8139, NI5210, Schneider and Koch G16, and Tiara (Fujitsu Lancard). All Etherboot drivers are autoprobing, which means they attempt to detect the hardware addresses at which the card is installed. It's fairly easy to write a driver if you are familiar with Ethernet hardware interfacing. Please contact me for more information if you are interested in doing so or are interested in having a driver written.
This document and related documents are also kept online at the Etherboot Home Page. This will in general have the latest distributions and documentation.
For a talk/tutorial type introduction to what Etherboot does and how to set it up, see my SLUG talk. You may wish to review this before reading further.
An older version of this README, which is now out of date, can be accessed via this link.
There is a mailing list for all netbooting related issues. To subscribe follow the instructions on the Etherboot home page.
With the exception of the following section, the information on diskless booting is not specific to Etherboot but can be used for the Netboot package also.
This section is Etherboot specific.
Unpack the distribution using gunzip and tar, using either of the following commands:
tar zxvf etherboot-4.0.tar.gz
gunzip < etherboot-4.0.tar.gz | tar xvf -
Precompiled ROM images are provided in the bin/ directory but you may wish to review the options compiled in and make your own versions. For the 32 bit version you need a recent release of gcc and the binutils tools. This package was compiled with the tools from a RedHat 5.2 distribution but it should work with any recent Linux distribution. For the 16 bit version you need the bcc tools from the Embedded Linux Kernel Subset (ELKS) project, for more details see the notes on 16 bit Etherboot. You need the 16 bit version only if you intend to run Etherboot on a 286 or 086/088 PC.
Assuming you have decided to make the 32 bit version, you only have to go to src-32/, edit the options in Config and say make. This will create all the ROM images available. The .lzrom images are the same as the .rom images. Since the .lzrom images are smaller and work exactly the same, there is no real reason to use .rom images any more, unless you are nervous about compression algorithm patents. We believe the algorithm used does not infringe patents, having been in public use for some time, but we do not know all the legal ramifications. See here for more details.
Here is a brief description of the options available:
Basic options:
-DDHCP_SUPPORT - Use DHCP instead of BOOTP (default on)
-DIMAGE_MENU - Allow to interactively chose between different
bootimages; read vendortags.html for further
information.
-DMOTD - Display message of the day; read vendortags.html
for further information.
-DANSIESC - evaluate a subset of common ANSI escape sequences
when displaying the message of the day; this
probably does not make sense unless you also
define -DMOTD or at least -DIMAGE_MENU.
Combining this option with -DSERIAL_CONSOLE
is a waste of EPROM space.
-DGFX - support extensions to the ANSI escape sequences for
displaying graphics (icons or logos); this
requires -DANSIESC
-DASK_BOOT=n - Ask "Boot from Network or from Local? " at startup,
timeout after n seconds (0 = no timeout); this
can be done in a more generic way by using the
IMAGE_MENU, but it requires that the "bootp"
server is accessible, even when booting locally.
-DANS_DEFAULT=ANS_NETWORK
- Assume Network to previous question
(alternative: ANS_LOCAL) on timeout or Return key
See etherboot.h for prompt and answer strings.
-DEMERGENCYDISKBOOT
- if no BOOTP server can be found, then boot from
local disk. The accessibility of the TFTP server
has no effect, though! So configure your BOOTP
server properly.
Basic options only on Etherboot/32:
-DPASSWD - enable password protection for boot images; this
requires -DIMAGE_MENU
-DUSRPARMS - allow the user to interactively edit parameters
that are passed to the booted kernel; you should
probably enable -DPASSWD as well; this feature
requires -DIMAGE_MENU
-DFLOPPY - boot from floppy/hd if bootimage matches the
pattern "/dev/[fh]d*"; if you do not have
enough space in the EPROM, then disable this
feature and use "mknbi-blkdev" for booting
from a local blockdevice.
-DCONFIG_PCI_DIRECT
- define this for PCI BIOSes that do not implement
BIOS32 or not correctly
These options should normally not need to be touched:
-DNOINT19H - Take control as soon as BIOS detects the ROM
Normally hooks onto INT19H
-DMOVEROM - if your motherboard does not cache adapter memory
space, then this option can speed up loading of
compressed BOOT-Prom images. It has no effect on
uncompressed images. Unless you are very tight on
free space, you will usually want to define this
option.
-DDELIMITERLINES - print a line of = characters at the start
and also just before starting an image.
-DSIZEINDICATOR - update a running total of the amount of code
loaded so far, in kilobytes
-DT509HACK - send two bootp packets before waiting for a
reply to the first. Makes a 3c509 do bootp
quicker
-DT503_AUI - Use AUI by default on 3c503 cards.
These options are only for a serial console for Etherboot/32:
-DSERIAL_CONSOLE- use a serial line for input and output
-DCOMPORT - 0x0 for COM1, 0x1 for COM2 etc
-DCOMPARM - configuration for COMPORT, save values:
0xe3 == 9600/8n1, 0xa3 == 2400/8n1
You can test the image with a floppy before burning an EPROM. On Linux just put a blank floppy in fd0 and say make card.fd0 where card is the name of your network card and it will copy a bootable image onto the floppy. If you wish to do this by hand, it's easy, just prepend floppyload.bin to card.rom (or card.lzrom) and write this combined binary to the floppy raw, i.e. starting at the boot block. Like this:
cat floppyload.bin 3c509.lzrom > /dev/fd0
When you boot with this floppy it will load the Etherboot ROM image from floppy and execute it. It should be able to detect your card. To get the bootrom to acquire an IP address and load the intended code, you need to set up bootp, tftp and NFS services, which we will discuss next.
We suggest you continue to use floppy booting until you have completed the setup of the server and are satisfied that diskless booting works.
In this section I assume you want to boot a Linux kernel. Booting a DOS kernel is similar, the main differences being in the way you set up the tagged image.
Etherboot expects to download a tagged image containing the code to be executed. Briefly explained, a tagged image is 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 tagged 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 mknbi-linux and that for DOS is mknbi-dos. These utilities are found in the netboot-<version> directory of the distribution.
You will probably have to compile a custom kernel because the kernel needs to have the "Root file system on NFS" option compiled in. You should also select "BOOTP support". "RARP support" is not needed. In 2.2 kernels you have to enable the "Kernel Autoconfig" option to access the BOOTP support question. And unless you are using an initrd (initial ramdisk) you will probably have to compile in the driver for your network card too. For details, see the file /usr/src/linux/Documentation/nfsroot.txt in a Linux kernel source distribution.
After you have compiled the custom kernel, make the tagged image, typically like this:
mknbi -x -k zImage -o /tftpboot/vmlinuz.xterm
Then put the tagged image in where the tftp daemon expects to find it, typically /tftpboot. Make sure it is world-readable because typically the tftp daemon runs as an unprivileged user.
Now set up a bootp daemon. In RedHat 5.2 this means installing the bootp RPM package, making sure that the bootps service is active in /etc/inetd.conf, and editing /etc/bootptab. The essential pieces of information you need to put in bootptab are:
Here is an example of a /etc/bootptab for the bootpd supplied with RedHat Linux 5.2 and probably many versions of Unix:
.default:\
:ht=ethernet:\
:hd=/tftpboot:bf=null:\
:ds=nameserver:\
:hn:to=36000:
xterm.ken.net.au:tc=.default:ha=08002BB7F380:ip=192.168.26.100:bf=vmlinuz.xterm
The first entry sets up some common defaults which applies to all succeeding entries which can be "included" using the tc=.default attribute. The first field is the domain name of the machine. The ha attribute is the Ethernet address. The ip attribute is self-explanatory. The bf field specifies the tagged image filename. For more details, consult the bootptab man page.
Please note that if you use the ef (extension file) attribute to be able to send more configuration data to the diskless machine, you must run bootpef everytime bootptab is modified.
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).
As an alternative to bootp, you could set up a DHCP server which has the advantage of automating the handing out of IP addresses. However the kernel may still do a bootp request to find the IP address for mounting the NFS filesystem. You may then wish to investigate the option in mknbi-linux which tells the kernel to take the address from the initial DHCP reply.
More information about DHCP can be found at the DHCP FAQ Web Page.
Now set up a tftp daemon. In RedHat 5.2 this means installing the tftp RPM package and making sure that the tftp service is active in /etc/inetd.conf. You probably want to use the secure (-s) option so that files can only be fetched from /tftpboot or people may be able to fetch arbitrary files from your server.
Now when you start up Etherboot, it should obtain an IP address and print out what it received. If you do not get this to work, turn on debugging in bootpd and see if any query was received. If not, check your network hardware (cables, etc). If a query was received, check if bootpd was able to give an answer. If not, then the Ethernet address was not found in /etc/bootptab. If a reply was sent, then only faulty hardware or a bug in Etherboot would prevent it being received by Etherboot.
Assuming an IP address was received, the next thing Etherboot tries to do is load a file using tftp. Check your system logs to see if a tftp daemon was started up and a file requested. Generally if you run tftpd under tcpwrapper security, a log entry will be generated. If not, it could be a path problem or file permission problem (the file needs to be readable by tftpd). Fix the problem.
After the tagged image is loaded, Etherboot will jump to it. If it crashes here, check that the image is a tagged image. If it executes and stops at the point where it's trying to mount the NFS root, then you need to check that you have the "root on NFS" option compiled in and that you have compiled in the network card driver.
Now you need to set up a NFS root filesystem for the diskless computer. Typically this is under /tftpboot/<ip address of computer>. (In 2.1 and presumably future kernels, this should be /tftpboot/<name of computer in bootptab>). This needs to contain a complete root filesystem that will make the kernel boot happily. This means, for most kernels, it should contain /dev, /proc, /etc, /sbin, /bin, /tmp and /var. The details vary from distribution to distribution. Being lazy I just make a copy of the necessary files from an existing RedHat 5.2 filesystem and modify some key files appropriately. You can find a description in my tutorial and some shell scripts to copy the files. Since the amount of disk space needed is relatively small in these days of large disks, I don't bother to throw out things that may not be needed.
Warning: Do not attempt to reuse the root filesystem of your server, whether by exporting it directly or by making hard links (symbolic links will not work). First of all, the configuration files will contain information pertaining to the server, not the client, so your client will get the wrong information. Secondly, this is a security risk. NFS is already not totally safe, but this way you are directly exposing your server root to clients. Even if you make hard links, the clients could (maliciously or accidentally) overwrite key binaries, making the server unusable. Don't try to save a few megabytes of disk space this way. You can however share some directories between clients, typically /sbin, /bin and /lib. The sample scripts in the tutorial show you how.
The root filesystem should be exported rw and no_root_squash because the various processes need to be root and need to write to log files in the root partition. You may wish to export /usr and /home filesystems to the diskless computer also. These do not need no_root_squash permission. Be aware that the RedHat 5.2 distribution has a few "bugs" relating to symlinks and so forth for diskless booting. These are mentioned in the tutorial. Other distributions may have similar problems.
Swap over NFS can be arranged but you have to patch the kernel source. There is a patch for kernels in the contrib/ directory for 2.0.x kernels. Hopefully this will make it into future kernels. Be aware that opinions are divided on NFS swap. Some people think it's a bad thing because it just kills the network if you have lots of diskless computers and that you shouldn't be running into a swap regime on a diskless computer anyway. Some other people like having a bit of insurance.
There are patches in the contrib directory for NFS swap but for up to date patches, try here.
Also have a look at the NBD Network Block Device web page for swapping over that. This requires a 2.1 or 2.2 kernel.
What about DOS? The deal with DOS is that one is loading a virtual floppy called A: into extended memory and then booting from this floppy. So you have to capture an image of a bootable DOS floppy first. Some more details can be found in the mknbi-dos directory.
I have booted DOS (both M$ and DR versions) diskless this way. Note that extended memory is used so that rules out 086/088 computers but 286s are ok. See this document for more details.
If you were thinking of booting a Windows machine via the network, it seems (I'm not masochistic enough to do this) the problem is not the network booting but the mounting of a file system over NetBIOS (Windows does not do remote mounts of root filesystems over NetBIOS on TCP). So that rules out a Samba server. It appears to be possible over a Netware server, for which Linux has workalikes. But then what do you do about the networking stack? This situation may change with with future Samba developments. But you will still have problems with pathnames and the usual Windows hassles. Do you really want to do this? In the Web page for Etherboot, there is a link to someone's Web page explaining how this was done with a commercial TCP/IP boot ROM.
Assuming you have satisfactorily set up your server environment, you may now wish to put the Etherboot onto an EPROM or EEPROM. Naturally this assumes access to hardware to burn (and possibly erase) EPROMs. An alternative is to use an EEPROM card. There is a schematic and PCB artwork for such a card in the distribution. This EEPROM card plugs onto the ISA bus and can be reprogrammed with software.
Most network cards come with a blank (E)EPROM socket even though it is seldom used. When it is used, it is typically filled with a proprietary EPROM from the network card manufacturer. You can put an Etherboot EPROM there instead.
First you must discover how to enable the EPROM socket on your card. Typically the EPROM is not enabled at the factory and a jumper or a soft configuration is used to turn it on.
Secondly, you must discover what size and speed of EPROM is needed. This can be difficult as network card manufacturers often neglect to provide this information.
The smallest EPROM that is accepted by network cards is an 8K EPROM (2764). Some cards will even go up to 64KB EPROMs (27512). You want to use the smallest EPROM you can so that you don't take up more of the upper memory area than needed as other extensions BIOSes may need the space. However you also want to get a good price for the EPROM. Currently the 32KB and 64KB EPROMs (27256 and 27512) seem to be the cheapest per unit. Smaller EPROMs appear to be more expensive because they are out of mainstream production.
If you cannot find out from the documentation what capacity of EPROM your card takes, you could do it by trial and error. Take an ROM with some data on it (say a character generator ROM) and plug it into the socket. Be careful not to use an extension BIOS for this test because it may be detected and activated and prevent you from booting your computer. Using the debug program under DOS, dump various regions of the memory space. Say you discover that you can see the data in a memory window from CC00:0 to CC00:3FFF (= 4000 hex = 16384 decimal locations). This indicates that a 16 KB EPROM is needed. However if you see an alias in parts of the memory space, say the region from CC00:0 to CC00:1FFF is duplicated in CC00:2000 to CC00:3FFF, then you have put an 8 KB EPROM into a 16 KB slot and you need to try a larger EPROM.
Note that because pinouts for 28 pin EPROMs are upward compatible after a fashion, you can probably use a larger capacity EPROM in a slot intended for a smaller one. The higher address lines will probably be held high so you will need to burn the image in the upper half or upper quarter of the larger EPROM, as the case may be. However you should double check the voltages on the pins armed with data sheet and a meter because CMOS EPROMs don't like floating pins.
The speed of the EPROM needed depends on how it is connected to the computer bus. If the EPROM is directly connected to the computer bus, as in the case of many cheap NE2000 clones, then you will probably have to get an EPROM that is at least as fast as the ROMs used for the main BIOS. This is typically 150 ns. Some network cards mediate access to the EPROM via an ASIC and this ASIC may insert wait states so that slower EPROMs can be used. Incidentally the slowness of the EPROM doesn't affect Etherboot execution speed much because Etherboot copies itself to RAM before executing. I'm told Netboot does the same thing.
The following people have contributed substantially to Etherboot. If you feel your name has been left out, just let me know and I will fix it up.
Co-author of Etherboot. He was the person who ported the Netboot suite from FreeBSD. He has enhanced Etherboot with many features, one new driver and has contributed various utilities and addons.
The mknbi utilities used by Etherboot are from Netboot. He has also clarified the original specification by Jamie Honan.
Jamie started Netboot off by writing the first version that used code from a packet driver.
The original authors of Netboot on FreeBSD.
Created bcc compiler used by Etherboot/16.
Current maintainer of bcc and associated tools like as86.
Contributed MASQ for making a boot floppy without DOS.
Contributed comboot for making a boot floppy without DOS.
Contributed patch for serial console and NFS swapping. See the contrib/nfs-swap directory for his Web page.
Contributed display of loading status and a hack for the 3c509 card.
Contributed PCI detection code originally from Linux sources.
Donated NE2100 card so that a driver could be written, and helped test the LancePCI driver. Spotted bug with 4.1 header code.
Created Intel EtherExpressPro 100 driver and binary to hex converter.
Contributed patches to work with DHCP. Also contributed a fix to match the received XID against the transmitted one, important in a network with many requesters.
Patches for eepro to work with 3.2.
Contributed an improved bin2intelhex.
Contributed fixes to 3c503 driver for PIO mode, fix to makerom for presetting EPROM bytes, and various endian fixes.
Contributed patch for making Intel eepro work in 4.0.
Contributed patches to start32.S from FreeBSD version to make it boot Windoze after answering N to Boot from Network question.
Contributed patches for prepended loaders and makerom to make bootrom PnP and PCI compatible.
Contributed vendor and device IDs for the Netvin NE2000/PCI clone.
Contributed RARP code as alternative to BOOTP/DHCP. Activated by RARP_NOT_BOOTP define.
Contributed a SMC9000 driver.
Contributed an Etherpower II (EPIC 100) driver.
Contributed mntnbi for mounting DOS NBIs.
Contributed a bug fix to the bootmenu code and a patch to main.c to remove looping menus on failure. Also code for ARP replies and TFTP retransmit (#ifdefed). Cleanup of tftp and tftpd.
Found bug due to tu_block being declared signed short in arpa/tftp.h on many platforms when it should be unsigned short.
Contributed a FreeBSD driver for Tulip based cards. Ken Yap ported it to Etherboot. Not tested because code needs to be written for all the variants of the Tulip and also because no hardware available to me.
Contributed a 3c905b driver. Be sure to read the release notes in 3c905b.txt before using.
Contributed patches to use BIOS call to size memory otherwise Etherboot was trampling on top of 640kB area, which is used by some extended BIOSes. Also contributed patches to pci.c to implement PCI bus support on BIOSes that do not implement BIOS32, or incorrectly.
Suggested making the ASK_BOOT prompts more generic and clearer. (Why doesn't SGML-Tools accept üaut;?) Also contributed a DOS utility for extracting the identifier string and PCI IDs, if any, out of the boot ROM.
Contributed various cleanup patches to the code especially in the bootmenu area, as well as a completely revamped start32.S. Also introduced Rainer Bawidamann's code, see next paragraph.
Contributed a Realtek 8139 driver.
contributed a Schneider & Koch G16 driver.
sent in a fix for the WD/SMC8013 which I finally verified.
The boot code from FreeBSD is under the BSD license. The netboot code is under the GPL. This is not a problem really: the GPL states that mere aggregation of another work with a GPL'ed work on a storage medium, e.g. an archive file, does not put the other work under the GPL.
Send changes to this document to Ken Yap (ken.yap@acm.org).