Etherboot User Manual Ken Yap Markus Gutschke This User Manual explains how to install, configure and compile the Etherboot package. The instructions here apply to version 5.2 of Etherboot. 1. About this User Manual 1.1. Obtaining the most recent version of this document This document and related documents are also kept online at the Etherboot Home Page (http://www.etherboot.org/). This will in general have the latest source distributions and documentation. 1.2.
Etherboot User Manual 1.4. Acknowledgments and Thanks Thanks to Markus Gutschke who wrote the first version of this document, and to all the people who have contributed information and corrections to this document. For a list of people who have contributed substantially to the code, please see Section 10 section. 2. Introduction to Etherboot 2.1. What is Etherboot? Etherboot is a software package for creating ROM images that can download code over an Ethernet network to be executed on a computer.
Etherboot User Manual No Warranty or Support: Etherboot comes with NO warranties of any kind. It is hoped that it will be useful to you, but NO responsibility is accepted for any outcome of using it. Etherboot also comes with NO support, although you may get helpful advice from the mailing lists listed on the Etherboot home page. 2.3. What hardware is supported? See Appendix A for a list of supported NICs.
Etherboot User Manual 3.2. Unpacking the distribution Unpack the distribution using gunzip and tar, using one of the following commands, where you replace x by the patchlevel number: tar zxvf etherboot-5.2.x.tar.gz tar jxvf etherboot-5.2.x.tar.bz2 gunzip < etherboot-5.2.x.tar.gz | tar xvf bunzip2 < etherboot-5.2.x.tar.bz2 | tar xvf - If the documentation tarball was provided separately, then in addition do this: cd etherboot-5.2.x followed by one of the following: tar zxvf ../etherboot-doc-5.2.x.tar.
Etherboot User Manual When you boot with this floppy it will load the Etherboot image from floppy and execute it. If you chose the correct image, 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 DHCP, tftp and NFS services, which we will discuss in the next section. We suggest you continue to use floppy booting until you have completed the setup of the server and are satisfied that diskless booting works.
Etherboot User Manual 4.1. Making a boot image Etherboot expects to download a boot image in either ELF or tagged (../devman/t1.html) 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.
Etherboot User Manual /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.
Etherboot User Manual 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. 4.3.1.
Etherboot User Manual 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. 5. Testing the network booting 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 DHCPD and see if any query was received.
Etherboot User Manual 5.2. Other filesystem setups This tutorial does not cover all possible ways of setting up a diskless client’s initial filesystem. You could even mount a conventional hard disk. Why would you want to boot "diskless" if you have a hard disk? Reasons might be: you do not wish to administer the local disk; you want the assurance that a system is running a kernel from a central server; or you like the speed of network booting. Network booting is one technique in a toolbox.
Etherboot User Manual 7. Making an Etherboot EPROM or EEPROM 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 program (and possibly erase) EPROMs. Access to a friendly electronics engineer and/or lab is one way to program and erase EPROMs. Otherwise you can look at the commercial links page (http://www.etherboot.org/clinks.html) for places you can buy programmed EPROMs from.
Etherboot User Manual 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 program 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.
Etherboot User Manual • Floppy version works but EPROM version doesn’t work. There is a program called rom-scan (Linux, FreeBSD and DOS versions) in the directory contrib/rom-scan which will help detect problems. Rom-scan will only work on ISA ROMs though. • If the EPROM is not detected at all then the contents of the EPROM are not visible to the BIOS. Check that you have enabled the EPROM with any jumpers or soft configuration settings.
Etherboot User Manual /etc/dhcpd.conf? If you are booting lots of clients, is inetd shutting down tftpd for being spawned too often? If so, you need to get a better inetd or a a dedicated tftpd that runs as an independent daemon. • Etherboot loads file but hangs halfway through the transfer. We have one report that this happens if the Fast A20 Gate option is selected in the BIOS setup. The A20 issue is explained here (http://www.win.tue.nl/~aeb/linux/kbd/A20.html).
Etherboot User Manual You need gcc, gas and binutils, as well as any accompanying libraries and include files. Generally speaking on a package based system using RPM or DEB, you will need the C compiler package, the include file package, the C library package, the assembler package and the binutils package (this may include the assembler). You will also need perl if you modify the file NIC or use a different RELOCADDR value in the Makefile than the default, and m4 if you modify this file userman.xsgml. 2.
Etherboot User Manual filenames are ignored by Etherboot. Remember to restart the server if you have edited the config file and the server does not automatically reread when it discovers an updated config file. Another thing to check is that the BOOTP or DHCP server is allowed to receive the query. You may have some protection mechanism such as tcpwrappers or a firewall in front of it. As the booting computer does not have an IP address, the request will come from 0.0.0.
Etherboot User Manual See the list of supported NICs in the Appendix. 2. I have a machine with the X processor and Y megabytes of memory. What can I expect to run on it? Please note that these estimates are approximate: • • On a 386 with at least 4MB of memory you can boot Linux. With 4MB perhaps only a few telnet sessions are possible. With 8MB you might be able to run a text based web browser like Lynx or W3M. You can also run firewalls such as floppyfw (http://www.zelow.no/floppyfw/).
Etherboot User Manual Remember that the config files used by the X server should pertain to the client’s video adapter and display hardware. If you used a LTSP (http://www.ltsp.org/) package, please review the configuration directions. If you used the copy files from server solution, then you need to customise the X server configuration. Another thing that may cause the server to abort is lack of a mouse device. 2. X -query server runs but all I get is a gray stippled screen.
Etherboot User Manual If you want to run apps locally, well how long is a piece of string? Netscape will need say another 16MB. It all depends. Whatever you do, it’s worth trimming down on the services you run on the client. Don’t run more virtual consoles than you need and don’t run unneeded daemons. As for the server, in the X-terminal case this has all the applications running on it, so it should be adequate for the multiuser aspect.
Etherboot User Manual 9.8. Booting other operating systems (DOS, Windows) 1. I want to boot FreeDOS. The new mknbi utility supports creating boot images from FreeDOS kernels now. See the man page (../mknbi.html) for details. FreeDOS is under development and if the layout of the kernel image changes, please send any corrections to me. 2. I cannot boot DR-DOS 7.03. There is some difference between the DR-DOS 7.03 and 7.02 bootblock that causes it not to boot. But a 7.
Etherboot User Manual Finally some recent motherboard have flash BIOSes which contain space where an extension BIOS such as Etherboot can be inserted. The Phoenix Award BIOSes can be modified using a program called cbrom.exe possibly here (http://www.ping.be/bios). Or do a Web search for it. No success has been reported for AMI BIOSes. Dirk von Suchodoletz maintains a list of successes and failures here (http://goe.net/anleitungen/award_board.html). Here is some text contributed by Dirk von Suchodoletz.
Etherboot User Manual (e.g. using ’make rtl8139.com’) can provide a useful remedy. Those DOS Executables are comparable in their functionality to .rom images and can be used as substitutes. In case an existing DOS-bootsector, stored in BOOTSECT.DOS, cannot be used, creating one has to be done by formatting and installing a harddrive using DOS before installing NT (see Win-NT Multiboot-HOWTO). In addition the DOS system files are needed (IO.SYS, MSDOS.SYS, or KERNEL.
Etherboot User Manual almost certainly a NE2000 clone. For some information, try here (http://www.geocities.com/ken_yap_aus/). If it’s a PCI card, then either the BIOS or the Linux PCI Utilities (http://atrey.karlin.mff.cuni.cz/~mj/pciutils.shtml) should be able to tell you the manufacturer and device IDs, which you can then look up to convert to names. 3. I would like to boot my laptop diskless from a floppy containing Etherboot. The problem is that laptops these days use PCMCIA network adapter cards.
Etherboot User Manual 9.11. Miscellaneous 1. I don’t understand something, or I have a question not covered by this list. Please see Section 2.4 earlier in this document. 10. Acknowledgements 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. Markus Gutschke Co-author of Etherboot. He was the person who ported the Netboot suite from FreeBSD.
Etherboot User Manual Dickon Reed Contributed display of loading status and a hack for the 3c509 card. David Munro Contributed PCI detection code originally from Linux sources. Charlie Brady Donated NE2100 card so that a driver could be written, and helped test the LancePCI driver. Spotted bug with 4.1 header code. Rogier Wolff Created Intel EtherExpressPro 100 driver and binary to hex converter. Vlag Lungu Contributed patches to work with DHCP.
Etherboot User Manual Daniel Engstrom Contributed a SMC9000 driver. Didier Poirot Contributed an Etherpower II (EPIC 100) driver. Martin Atkins Contributed mntnbi for mounting DOS NBIs. Attila Bogar 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 (#ifdef CONGESTED). Cleanup of tftp and tftpd. Nathan R. Neulinger Found bug due to tu_block being declared signed short in arpa/tftp.
Etherboot User Manual Georg Baum contributed a Schneider & Koch G16 driver. jluke AT deakin PERIOD edu PERIOD au sent in a fix for the WD/SMC8013 which I finally verified. Mark Burazin contributed a fix for Compex RL2000 NICs. Matthias Meixner found a receive status bug in the RTL8139 driver. Jim McQuillan provided changes to support the SMC1211 which uses the RTL8139 chip. Steve Smith Extended the 3c905b driver for other members of the 90x family. Be sure to read the release notes in 3c90x.
Etherboot User Manual Adam Fritzler contributed 3c529 (MCA version of 3c509) support in driver. Shusuke Nisiyama contributed a 3c595 (may work for 3c590) driver. Igor V. Kovalenko contributed a Winbind W89C840 driver. Gary Byers of thinguin.org wrote the LILO prefix program liloprefix.S. Donald Christensen converted all the as86/nasm .S files to gas format, thus allowing Etherboot to be built without requiring as86/nasm.
Etherboot User Manual Armin Schindler contributed a patch to allow booting LynxOS KDI images. Christopher Li contributed an Intel E1000 gigabit Ethernet driver. Rohit Jalan contributed a patch for FreeBSD style PXE booting. Andrew Bettison sent in a patch to run the SMC EtherEZ in PIO mode, required for some motherboards. Michael Brown contributed the first wireless NIC drivers for the Prism chipset.
Etherboot User Manual drivers/net/3c90x.c Open Source drivers/net/epic100.c None drivers/net/epic100.h None drivers/net/ns8390.c BSD drivers/net/ns8390.h BSD drivers/net/tulip.c BSD arch/i386/include/bits/string.h None util/lzhuf.c Open Source A. List of supported NICs The following is the current NIC configuration file as of 2003-09-23. .
Etherboot User Manual 3c905b-t4 0x10b7,0x9056 3Com905B-T4 3c905b-9058 0x10b7,0x9058 3Com905B-9058 3c905b-fx 0x10b7,0x905a 3Com905B-FL 3c905c-tpo 0x10b7,0x9200 3Com905C-TXM 3c980 0x10b7,0x9800 3Com980-Cyclone 3c9805 0x10b7,0x9805 3Com9805 3csoho100-tx 0x10b7,0x7646 3CSOHO100-TX 3c450 0x10b7,0x4500 3Com450 HomePNA Tornado family drivers/net/eepro100 id1029 0x8086,0x1029 Intel EtherExpressPro100 ID1029 id1030 0x8086,0x1030 Intel EtherExpressPro100 ID1030 82801cam 0x8086,0x1031 Intel 82801CAM (ICH3) Chipset Eth
Etherboot User Manual e1000-82540ep-lom 0x8086,0x1016 Intel EtherExpressPro1000 82540EP LOM e1000-82540ep 0x8086,0x1017 Intel EtherExpressPro1000 82540EP e1000-82541ep 0x8086,0x1018 Intel EtherExpressPro1000 82541EP e1000-82547ei 0x8086,0x1019 Intel EtherExpressPro1000 82547EI e1000-82546eb-quad-copper 0x8086,0x101d Intel EtherExpressPro1000 82546EB Quad Copper e1000-82540ep-lp 0x8086,0x101e Intel EtherExpressPro1000 82540EP LP family drivers/net/tg3 tg3-5700 0x14e4,0x1644 Broadcom Tigon 3 5700 tg3-5701 0x1
Etherboot User Manual an981 0x1317,0x0981 ADMtek AN981 Comet an983 0x1113,0x1216 ADMTek AN983 Comet an983b 0x1317,0x9511 ADMTek Comet 983b centaur-c 0x1317,0x1985 ADMTek Centaur-C intel21145 0x8086,0x0039 Intel Tulip ax88140 0x125b,0x1400 ASIX AX88140 rl100tx 0x11f6,0x9881 Compex RL100-TX xircomtulip 0x115d,0x0003 Xircom Tulip tulip-0981 0x104a,0x0981 Tulip 0x104a 0x0981 tulip-2774 0x104a,0x2774 Tulip 0x104a 0x2774 tulip-9511 0x1113,0x9511 Tulip 0x1113 0x9511 tulip-1561 0x1186,0x1561 Tulip 0x1186 0x1561 tul
Etherboot User Manual family drivers/net/sis900 sis900 0x1039,0x0900 SIS900 sis7016 0x1039,0x7016 SIS7016 family drivers/net/natsemi dp83815 0x100b,0x0020 DP83815 family drivers/net/fa311 fa311too 0x100b,0x0020 DP83815 family drivers/net/prism2_plx ma301 0x1385,0x4100 Netgear MA301 3c-airconnect 0x10b7,0x7770 3Com AirConnect ss1023 0x111a,0x1023 Siemens SpeedStream SS1023 correga 0x15e8,0x0130 Correga smc2602w 0x1638,0x1100 SMC EZConnect SMC2602W gl24110p 0x16ab,0x1100 Global Sun Tech GL24110P 16ab-1101 0x1
Etherboot User Manual 3c515 - 3c515, Fast EtherLink ISA family drivers/net/eepro eepro - Intel Etherexpress Pro/10 family drivers/net/cs89x0 cs89x0 - Crystal Semiconductor CS89x0 family drivers/net/depca depca - Digital DE100 and DE200 family drivers/net/sk_g16 sk_g16 - Schneider and Koch G16 family drivers/net/smc9000 smc9000 - SMC9000 family drivers/net/sundance sundance 0x13f0,0x0201 ST201 Sundance ’Alta’ based Adaptor dfe530txs 0x1186,0x1002 D-Link DFE530TXS (Sundance ST201 Alta) family drivers/net/tlan
Etherboot User Manual cs89x0.txt sis900.txt tulip.txt B. Build options available User interaction options: -DASK_BOOT=n Ask "Boot from (N)etwork ... or (Q)uit? " at startup, timeout after n seconds (0 = no timeout). If unset, boot immediately using the default. -DBOOT_FIRST -DBOOT_SECOND -DBOOT_THIRD On timeout or Return key from previous question, selects the order to try to boot from various devices. (alternatives: BOOT_NIC, BOOT_DISK, BOOT_FLOPPY, BOOT_NOTHING) See etherboot.
Etherboot User Manual -DNO_DHCP_SUPPORT Use BOOTP instead of DHCP. -DRARP_NOT_BOOTP Use RARP instead of BOOTP/DHCP. -DREQUIRE_VCI_ETHERBOOT Require an encapsulated Vendor Class Identifier of "Etherboot" in the DHCP reply Requires DHCP support. -DALLOW_ONLY_ENCAPSULATED Ignore Etherboot-specific options that are not within the Etherboot encapsulated options field.
Etherboot User Manual and constant (predictable) retry interval for embedded devices. This is to achieve short boot delays if both the DHCP Server and the embedded device will be powered on the same time. Otherwise if the DHCP server is ready the client could sleep the next exponentially timeout, e.g. 70 seconds or more. This is not what you want. n should be a multiple of TICKS_PER_SEC (18). Boot device options: -DCAN_BOOT_DISK Can boot from floppy/hd if bootimage matches the pattern "/dev/fhsd*".
Etherboot User Manual -DMULTICAST_LEVEL1 Support for sending multicast packets -DMULTICAST_LEVEL2 Support for receiving multicast packets -DDOWNLOAD_PROTO_TFTP If defined, boots by TFTP (recommended). -DDOWNLOAD_PROTO_NFS If defined, boots from a NFS mount and disables TFTP loading. Default is DOWNLOAD_PROTO_TFTP if neither is defined. -DDOWNLOAD_PROTO_SLAM If defined, boots via Scalable Local Area Multicast. -DDOWNLOAD_PROTO_TFTM If defined, enables booting via TFTP Multicast mode.
Etherboot User Manual Obscure options you probably don’t need to touch: -DPOWERSAVE Halt the processor when waiting for keyboard input which saves power while waiting for user interaction. Good for compute clusters and VMware emulation. But may not work for all CPUs. -DRELOCATE After starting etherboot relocate to the top of memory. This allows loading fairly arbitrary rom images. This doesn’t work with a couple of drivers, e.g. lance.
Etherboot User Manual hand, it also enables some attacks that are not possible against machines that boot from local mass storage devices (floppy, harddisk, ...). As a general rule, you can assume that it is impossible to protect your system from all conceivable attacks, but you can try to minimize the chance of an attack, try to minimize the seriousness of the damage caused and try to help in detecting attacks at the earliest possible moment.
Etherboot User Manual from a local device, then specify the full device name and either enable the "-DFLOPPY" option or store a boot image (as generated by "mknbi-blkdev") under this name on the TFTP server. It might be a good idea to install non-functional bootcode in the master boot record of your harddisk and install any locally required boot code in the boot sectors of the individual partitions.
Etherboot User Manual techniques involve passing a suitable option on the kernel command line (i.e. "single") or crashing the filesystem by power cycling the machine; this in turn will result in fsck being invoked at the next system start, which will sometimes drop you into single user mode. Some Linux distributions do not require a password when entering single user mode. While this makes system administration somewhat easier, it is a considerable security problem.
Etherboot User Manual C.9. NFS While NFS is very convenient for installing diskless machines, it provides almost no security. Data is transmitted unencrypted and authorization is solely based on the identity of IP addresses. Anybody who can forge ethernet packets, has full access over any data that is available via NFS. While there are protocol extension that try to address these shortcomings, I am not aware of any solution for Linux based machines.
Etherboot User Manual and Gero Kuhlmann . I will happily include any of your extensions, but I would like to avoid the proliferation of different incompatible revisions of this document. If these conditions are a problem to you, then feel free to contact me. RFC1533 allows for vendor-specific extensions to the BOOTP protocol. It defines that all tags in the range 128 thru 254 are set aside for site-specific extensions.
Etherboot User Manual TAGS 161 thru 174 these tags are currently unused, but they should be allocated for purposes that resemble the function of tag 160. TAG 175 the BOOT-Prom uses this tag for telling the DHCP server which NIC driver it is using. The DHCP server can then modify the "filename" field in the DHCPACK packet in order to direct the BOOT-Prom to download an appropriate kernel image.
Etherboot User Manual 5 - 40x25 mono 6 - 80x25 mono (gfx) (gfx) 18 - 80x30 16colors (gfx) 19 - 40x25 256colors(gfx) Cursor control Code [r;cH [r;cf [rA [rB [cC [cD [?7l [?7h [J [K [s [u Effect move cursor to row r and column c move cursor to row r and column c move cursor up r rows move cursor down r rows move cursor right c columns move cursor left c columns turn off line wrap turn on line wrap clear screen and home cursor clear to end of line
Etherboot User Manual your BOOT-Prom or available from the contrib directory of the "etherboot" package. [a;b;c;d- same as above, but pack pixels into three bits. The first pixel is stored in the three most significant bits of the first data byte. Note that you usually have to specify any control characters directly (rather than in hex form) in your /etc/dhcpd.conf file.
Etherboot User Manual passwd MD5 message digest of the password. If this entry is omitted, then no password is required for loading this image. Support for passwords is optional and might not be compiled into the ROM image. For generating the MD5 message digest, you can use freely available tools such as "md5sum". C.f. the flags entry for controlling the behavior of passwords. flags flags are used for controlling some aspects of how the BOOT-Prom code behaves.
Etherboot User Manual not make sense for any operating system other than Linux and is silently ignored for other operating systems. As it is not legal to enter colons as part of an entry, you have to escape them by writing "~c" instead. This also means, that all tilde characters have to be escaped by writing "~~". As some DHCP daemons do not allow for entering a backslash in a character string, the escape sequence "~b" inserts a backslash character. Currently, all other escape sequences are undefined.
Etherboot User Manual # will keep working even when the network topology is changed. Leaving # the server IP address and the gateway IP address empty, should # ensure that booting works even when we go thru "bootpgw" gateways. # # "Technicolor" special effects are achieved by changing the # foreground text color of the individual labels. You could even embed # small icons after switching to graphics mode. C.f. "linux-logo.
Etherboot User Manual # per host setup host 192.168.40.203 { # MAC and IP addresses hardware ethernet 00:60:08:0d:a9:84; fixed-address 192.168.40.203; # default file to boot, common append options, default menu selection and timeout filename "/tftpboot/menu.nb"; option option-128 E4:45:74:68:00:00; option option-129 "ramdisk_size=16000 vga=6"; option option-160 "timeout=10:default=192"; option option-184 "^[[’/tftpboot/thinlinux/1.
