

                          Netboot v1.3

                (C) Copyright Gero Kuhlmann 1995



0  -  Copyright Notice, Acknowledgements

  The code for the boot rom was written by Jamie Honan, based on NCSA
  Telnet. See the README in the bootrom directory of this package for
  more information. Everything else, including the Linux kernel patches,
  is copyrighted by me. You are allowed to modify and redistribute
  this code under the terms of the GNU General License, which you can
  find in the file COPYING.
  My special thanks go to Jamie Honan for writing the boot rom code, and
  to Jens-Uwe Mager for explaining to me the basics of the NFS networking
  system.


1 -  Overview

  Booting a computer without a hard disk usually requires a floppy disk
  drive or a network connection in order to get the operating system into
  the RAM and up running. This package allows a diskless PC to boot the
  Linux operating system using a TCP/IP based ethernet network. This
  is implemented in several steps:

	- There must be some sort of ROM in the system which allows
	  loading the kernel image into the memory over the network.
	  A common way of implementing this is with the bootp protocol
	  as defined in RFC 951 and RFC 1048 to get the necessary boot
	  information, and then loading the actual image using the tftp
	  protocol. Instead of a ROM, the loading program can alterna-
	  tively be found on a diskette.

	- When the kernel starts running, it has to determine it's own
	  IP address, which can be accomplished using RARP, according to
	  RFC 903. Also enclosed in the RARP answer is the IP address of
	  the boot server. Alternatively the kernel can get the IP addresses
          on it's command line, which is derived from the information which
	  was previously gathered by asking a bootp server.

	- With the known IP addresses the root filesystem can be mounted
	  over the network using NFS as defined in RFC 1094. This file-
          system has to reside on that server which answered the RARP
          request, or which was given on the command line. The name of
          this directory on the server can either be /tftpboot/<IP-number>
          or the same as the directory from which the kernel image was
          loaded. If the server can understand bootp records with the
          RFC 1497 extension, then it's also possible to define a com-
          pletely different root directory in /etc/bootptab of the server.

        - Besides the actual booting process, a diskless system with only
          limited amount of memory usually needs a way to swap it's memory
          out onto a filesystem. This package supports swap files which
          are located on a NFS filesystem.


2 -  Requirements

  In order for this package to be useful you need a Linux kernel version
  1.2.2. The patches may or may not work with earlier versions. To compile the
  mknbi utility program you need an assembler which is capable of producing
  real mode 80x86 code. One such assembler, which is also used for building
  the kernel, is as86 with it's linker ld86. The boot rom code requires
  either a WD80*3 or a 3com network card. However, I only used the WD driver,
  and don't have any experience with the 3com driver. Since there are no
  Binaries included in this package which support 3com cards, you will have
  to have a computer running DOS with GNU make, Turbo-C and either Turbo-
  Assembler or MASM to recompile the boot rom code. Binaries for WD cards
  are included, so you don't have to recompile them. If you want to boot
  your diskless computer using a ROM, you also obviously need an EPROM
  burner. Furthermore, you also need a server to boot from, which has to
  run a bootp-Daemon, be able to answer RARP requests, and be able to export
  filesystems via NFS. Users of sun servers can find a bootpd in the contrib
  directory. If you use Linux on that server be sure to use version 1.2.4 or
  later and to compile the kernel on it with RARP and NFS enabled (or use the
  NFS module). RARP support is not required if your diskless client has only
  one ethernet card installed. You should also use the nfsd-package version
  2.1 or later on the server, since earlier versions are quite buggy. You
  can find the nfsd sources in the contrib directory. Also a RPC portmapper
  is needed on the server.


3 -  Installation

  The following is just a basic way of installing everything. There are
  many possible ways of specifying where to get the boot image from and
  what directory to mount as root. First of all you should patch your
  kernel sources. Then configure them as necessary for your diskless client
  and recompile everything. Then compile and install the mknbi program.
  Just cd into the mknbi directory and type make. There is nothing to
  configure here. Especially do *not* define ASM_DEBUG, as this will make
  the boot loader to die (intentionally!). You can then create a network
  bootable image of your kernel by using:

	mknbi -d rom -i rom -k /usr/src/linux/arch/i386/boot/zImage \
		-o bootImage

  Copy the created file "bootImage" onto your boot server. It should be
  copied into the same directory which is later being used as the root
  filesystem of your diskless system. Next configure /etc/bootptab on
  your server (consult your server's documentation on how to do this)
  and make sure the server will answer RARP requests correctly. There
  is no standard implementation for this. Some systems require /etc/ethers
  to be edited, others (namely Linux) have a RARP table in the kernel,
  which has to be loaded using an rarp program. To setup RARP is only
  necessary if your diskless client has more than one network interface.
  You also have to setup /etc/exports, which specifies what directories
  get exported to what systems via NFS.
  Next you have to setup your diskless computer. If you have a WD80*3
  or compatible network card installed, you can just use the provided
  binaries in the bootrom directory. For burning an EPROM you can use
  rom.hex, which is in Intel Hex Format. If you can't use this format,
  take rom.bin and convert it to a format your EPROM burner understands.
  The bootrom driver now understands how to find out various parameters
  of the network card at runtime, so you don't have to recompile the
  binaries in case you use a different setup on your WD card. Also note
  that the boot rom does not proceed with network booting anymore if
  there is a diskette in the A: drive. You can use this to boot MSDOS
  and setup the network card.
  You can also boot your computer using a diskette instead of an EPROM.
  Just copy fimage.bin onto a diskette using dd (under Linux) or rawrite
  (under DOS). Alternatively you can create a DOS boot disk, copy
  booter.com onto it, and let this program run from autoexec.bat or
  using the shell command in config.sys.
  When using a 3com network card you will have to recompile the bootrom
  code. Edit the MAKEFILE in the bootrom directory so that GNU make will
  find all necessary programs, change CONFIG.H to reflect your setup
  (remember to remove the comments around the #define commands!), and
  then type 'make net3com' and 'make rom.hex' or 'make fimage.bin' depen-
  ding on what target you want to create. If you don't use any one of
  the above mentioned cards, you are pretty much on your own. Check the
  supplied README's on how to create a new device driver for the boot rom.
  You probably want to get the NCSA Telnet source, which contains source
  for a couple of network devices.


4 -  Trouble shooting

  After turning on or resetting the diskless system, the boot rom should
  display a short message (regardless wether it's started out of a rom or
  from diskette) and then it will send out the bootp request. If the start-
  up message doesn't appear make sure that you configured your network card
  correctly. The space for the shared memory has not to overlap the rom
  space. The rom size should be set to 32kB, even if you use 64kB EPROMS
  (but the jumpers on the card have to be correct!). If the boot rom gets
  an answer from a bootp server, it will display the name of the kernel
  image file to load. It then displays a block count while this image is
  being loaded using tftp. If the boot rom does not get an answer from the
  bootp server, make sure that /etc/bootptab is correctly configured.
  Especially the hardware address of the diskless station and it's name
  have to be set, together with the name of the image file. A minimal
  entry therefore should look like this:

	demo:ht=ethernet:ha=00abcdef1234:ip=123.234.111.22:\
				bf=/usr/spool/boot/demo/bootImage

  Verify that bootpd really gets started on the server. If possible turn
  debugging on when starting bootpd, and verify that the server sends out
  the correct data.
  If the boot rom cannot load the image file, check that the tftp service
  is available, and that tftpd is getting called by inetd. Furthermore tftpd
  has to have read access to the image file. Also check out a possible TCP/IP
  wrapper running on your server which might prohibit access to the tftp
  service.
  After the image file has been loaded, control is transfered to a short
  boot loader which will display it's startup message, initialize the kernel
  command line and then call the kernel setup module. This boot loader also
  analyzes the bootp reply in order to determine the correct root directory
  name and IP addresses. It should run cleanly and not issue an error mes-
  sage. However, if an error message appears please report it to me.
  The kernel then gets uncompressed and started. When all kernel modules
  are initialized, a RARP request will be sent out over the network, if you
  did not use the rom argument with the -i option of mknbi as shown above,
  or if your diskless client has more than one network interface installed.
  If that's the case and no answer can be received from the RARP server,
  check out that RARP is properly configured on the server. If the server
  runs Linux, you can inspect the RARP table by looking at /proc/net/rarp.
  It should contain the same IP and hardware addresses which you have
  defined in /etc/bootptab.
  As soon as the kernel knows it's own IP address and that of the server,
  it asks the portmapper on the server for the port number of the mountd
  and nfsd daemons. If the portmapper doesn't answer, check that it's
  running at all, and that the mount and nfs services are registered
  properly. You can usually use "rpcinfo -p" for this. Services will only
  be listed here if they are actually running. After asking the portmapper,
  the kernel asks for a file handle for the root directory. It will print
  out the name of that directory, and it should be the same as the one from
  which the boot image is loaded. If it's not, try specifying the full path
  with the -d switch of the mknbi program, and recreate the boot image. If
  the kernel doesn't get a valid answer from the server, it will show an
  error number, which is defined according to the NFS protocol:

	 1  -  permission denied to access directory
	 2  -  directory doesn't exist
	 5  -  I/O error on server filesystem
	20  -  path name is not a directory
	63  -  path name is too long

  Also note, that the Linux mountd and nfsd programs only read /etc/exports
  once at startup. If you changed this file afterwards, you will have to
  restart both daemons. Additionally, with nfsd versions for Linux earlier
  than 2.1 you will have problems with special files like UNIX-Domain-Sockets
  or block/character files on your NFS partitions. Therefore I urgently re-
  commend to update your nfsd/mountd programs if you are using older versions
  than 2.1.
  After the kernel got a file handle for it's root directory from the server
  it internally mounts it, and then starts /etc/init. Unless this init is
  statically linked you need ld.so and libc in /lib.
  If you run into any serious problems, or find a bug or have ideas for further
  improvement, please don't hesitate to write me via eMail:

		gero@gkminix.han.de


5 -  Disclaimer

  The software in this package heavily interacts with hardware and software
  not only on the local system, but also on the boot server. Use it at your
  own risk. I cannot be held responsible for any damage done by this software.

