I N S T A L L A T I O N
Overview of the installation process
====================================
Due to it's nature this package requires at least two computer systems. One
acts as a server, and at least one other will be setup as a diskless client.
Therefore this installation guide is divided into four sections:
1.) Compilation and installation of utility programs on the server
2.) Create a netbootable image of the target operating system
3.) Setup of the server
4.) Setup of the client including building the bootrom
The server has to support TCP/IP and certain protocols based on this network
standard. Most likely this will be a Unix-type server. Though it's probably
possible to also use servers running OS/2 or Windows-NT, for example, all
server related programs in this package can currently only be compiled on
a Unix-type host. This requirement is independed of the operating system
which is later booted on the diskless client. Therefore even if you want
to boot MS-DOS on your client(s) you need at least one Unix-type computer
for program compilation and generation of all boot files. Lateron when all
necessary files are built you can use any server you want.
This package contains two main parts:
1.) The bootrom source and binaries. This part gets installed on
the diskless client. All binaries except for utility programs
are already precompiled. There are no further user changeable
or adjustable options in the sources so you don't have to have
access to the 16 bit development tools in order to use the boot-
rom. You can just use the binaries provided.
In order for the bootrom to access the network card in your
diskless client you need a driver. Currently the bootrom only
supports so called packet drivers, which are normally used on
MS-DOS systems to interface a network stack with the hardware.
With this package only the packet driver binaries are required,
so you don't need to recompile anything here as well. You can
find precompiled packet drivers for many popular network cards
on any SimTel FTP mirror (it's called Crynwr packet driver col-
lection), and for those of you without internet access some of
those packet driver binaries are included with this package.
Another good source for a packet driver for your network card
might be it's manufacturer. At least the well known manufacturers
(3Com and SMC for example) provide packet drivers for their
complete product line. Those manufacturer provided packet drivers
are usually faster and easier to install than those from the
Crynwr collection, and can sometimes determine the hardware
configuration at runtime, which the Crynwr drivers can't. However,
there is a limitation in that you can only use packet drivers
which are COM-type executables. EXE-type programs are not
supported yet.
2.) A set of programs to generate netbootable images on the server.
These programs are called mknbi-<os>, where <os> identifies the
operating system which is lateron running on the diskless client.
Currently only Linux and MS-DOS are supported.
There is another requirement which should not leave unnoted. Although you
can build a bootrom with slightly limited functionality which is less than
16kB in size, the usual size for a bootrom will be between 16kB and 32kB.
Therefore when you go shopping for a network card you should try to get
one which is able to support 32kB EPROM's. This is standard on almost all
cards from major manufacturers, but most cheap NE2000 are known to allow
only a maximum of 16kB. Also note that some network cards from 3Com and SMC
allow you to select ROM sizes of 32kB and more with their configuration
programs, but can physically support only 16kB!
Compilation and installation of utility programs on the server
==============================================================
This package uses GNU's autoconf to configure the compilation process
of the utility programs. You shouldn't have any problems to compile
these programs on any Unix-type system.
1.) Cd into the netboot directory and run ./configure. It's
a configuration script generated by autoconf and checks
for header files and system specific details. The mknbi
utility programs contain some Intel assembler modules which
lateron run on the diskless client. If you want to assemble
these modules you need as86 and ld86, which you can get for
free for Unix systems. However, there are preassembled files
available so you actually don't need these two programs.
configure checks for their existence and creates the Makefiles
accordingly.
For an explanation of the switches available to configure
just run it with the --help option. Some additional switches
are available:
--disable-mknbi-linux
--disable-mknbi-dos
Choose these options if you don't want to create any of the
corresponding mknbi utility programs. There is also another
configure option:
--enable-bootrom
Use this option only if you want to recompile the bootrom
itself. If you want to use the precompiled binaries, you don't
need to specify this switch. See the file INSTALL.bootrom
about how to recompile the bootrom.
2.) Check that all generated Makefiles and the config.h are correct
for your system.
3.) Compile all programs with
make clean
make
This will compile all programs without those which you disabled
during the configuration stage. IMPORTANT NOTE: Some Makefiles
use ifdef, which not every make program understands. If you
get an error from make (usually in the form: "missing delimiter")
then get and install GNU make on your system! Especially System V
systems are known to have this deficiency.
4.) If you want to permanently install the utility programs on
your server you can run
make install
This will also install the corresponding man pages for later
reference. However, it's perfectly ok to skip this step and
run the mknbi program from their source directories. But please
note that they are just called "mknbi" within their source
directories. Therefore if you read further down to run mknbi-dos,
you have to use "./mknbi-dos/mknbi" instead if you didn't install
the programs using 'make install'.
Create a netbootable image of the target operating system
=========================================================
This step of the installation process depends on which operating you
want to boot on your diskless clients. Everything described in this
chapter does not depend on working on a Linux system. You can use any
UNIX type system to create the netbootable images.
Linux: With Linux you have far too many options to list them all in
this text. Please refer to the mknbi-linux man page for all
details. I will only describe the most common ways to setup a
diskless Linux client here.
First you have to decide where the Linux client is going to
mount it's root filesystem from. This can either be a directory
on an NFS server or a ram disk. Setup your Linux kernel accordingly.
To use a root filesystem on an NFS server you should include TCP/IP
network support into the kernel together with support for NFS file-
systems. You cannot load this NFS support using a module as it has
to be available at bootup. Additionally you also have to select
NFSROOT support during kernel configuration. However, you don't
need BOOTP or RARP support. Accordingly if you want to use ramdisk
support the filesystem type you are going to use on the ramdisk has
to be permanently compiled into the kernel. Also initrd has to be
included in that case.
1.) Configuring for NFS root filesystem.
Next copy your Linux kernel into the current directory and run
mknbi-linux:
mknbi-linux -d rom -i rom -k zImage -o bootImage
This supposes that your kernel image is called zImage, and gives
you a netbootable image named bootImage.
2.) Configuring for root filesystem on ramdisk
If you want to use a ramdisk as a root device you have to create
a ramdisk image first. Probably the easiest way to setup such an
image is to use a floppy, though you can also use the loopback
device if you are working on a Linux host. First format the floppy
and make a filesystem on it. Next copy all programs and files onto
it which you want to have on the root filesystem of the diskless
client lateron. You should then test your root floppy. To do this
copy your kernel onto another floppy with dd and set it's root device
to floppy using rdev:
dd if=zImage of=/dev/fd0
rdev /dev/fd0 /dev/fd0
Now boot your diskless client using this boot disk. After the kernel
started up, it will ask you to insert the root floppy and to press
enter. Your root floppy will be mounted.
If everything works as you intended, you can now create a netbootable
image. Re-insert the root floppy into your server system (or whereever
this netboot directory is located), and type:
dd if=/dev/fd0 of=ramImage
gzip -9 ramImage
mknbi-linux -d ram -i rom -r ramImage.gz -k zImage -o bootImage
Like above this will now give you a file bootImage with the netbootable
Linux kernel image in it.
MS-DOS: To boot DOS on your diskless client you have to have MS-DOS Version
5.0 or higher. Windows-95 has an internal DOS called version 7.0, so
it should be no problem to use it as well. Older MS-DOS versions
will definitely not work. I haven't had a chance to test any other
DOS like Novell-DOS or DR-DOS. Give them a try, and tell me.
First you have to create a directory which contains all the files
the client will see on it's boot drive (either A: or C:). This
can either be the root directory on a DOS floppy or any directory
on the system on which you installed mknbi-dos. In the first case
it has to be a floppy which contains a bootable DOS system, i.e.
which has been created with
format a: /s
on a DOS system. If the directory resides on a UNIX system, you
have to copy the two system files msdos.sys and io.sys, which are
part of MS-DOS, into it by yourself. To do this I recommend using
mread of the MTools, which are freely available for almost every
UNIX system.
After you created the directory or floppy which lateron becomes
the clients boot drive, you should copy all other necessary files
into it. This will probably include programs to setup a network
environment on the client. When editing text files for the client
please note that they usually have to be in MS-DOS format with
lines ending in Carriage-Return/Linefeed instead of just Linefeed
as it is common on UNIX systems. When you are finished setting up
the clients boot directory, first get a copy of the floppy disk
image, and then run mknbi-dos to create a netbootable image:
dd if=/dev/fd0 of=fdImage
mknbi-dos -r fdImage -o bootImage
This assumes that you inserted the boot floppy into the fd0 drive
of your UNIX system, and will create a file named bootImage. If you
used a UNIX directory, substitute fdImage with it's name. mknbi-dos
will automatically detect wether it is a directory, an ordinary
file or a block device.
By default mknbi-dos creates a netbootable image, which lateron
mounts the ram disk as the A: drive on your client. If you want
to mount the ram disk as C: instead, you should include the '-c'
switch to the call of mknbi-dos.
The difference between mounting the ram disk as a floppy (A:) or
hard disk (C:) is, that with the floppy option the ram disk can
be removed lateron, maybe after a network redirector has been
loaded, which makes the ram disk obsolete. This is not possible
with a virtual hard disk drive. On the other hand side, when using
the ram disk as C: you can specify a different ramdisk size with
the '-s' option. Please refer to the man page for mknbi-dos for
further information.
Setup of the server
===================
Setup of the server depends on the kind of server you are using. There-
fore all further explanations in this chapter can only serve as a general
guide. You should consult your server's documentation as the final autho-
rity.
When the bootrom starts on the client it first tries to query a bootp
server for information like IP numbers and the name of the boot image
file. Such a bootp server program is usually called bootpd. Most sun
servers use a program called bootparamd instead. Note that you _cannot_
use bootparamd as a substitute for bootpd as both programs use different
protocols. Install a publicly available bootpd instead on your sun.
Next you should copy the bootImage file, which you have created in the
previous step above, into a publicly accessible directory (called /boot
for example). If you want to boot more than one diskless client you can
use the same bootImage file for every client. However, if you configured
for a ramdisk (with Linux or DOS) and the ramdisk image contains different
files or information for every client, you will obviously also need a
different bootImage file for each client.
Then you need to setup a boot description file for bootpd, which is
usually called /etc/bootptab. Consult your server's documentation for
further information. However, the entries in this file will usually
look something like this for every diskless client:
client1:hd=/boot:vm=auto:ip=192.109.225.66:\
:ht=ethernet:ha=004001417173:\
:bf=bootImage-client1:rp=/boot/client1/root
'hd' specifies the home directory and 'bf' is the name of the bootImage file,
which you created in the previous step. Therefore the full pathname for
the bootImage file for the diskless system called "client1" will be
/boot/bootImage-client1
with this sample entry. The 'ip' tag specifies the IP address of the client,
'ht' the type of the network the client is attached to, and 'ha' it's hard-
ware address. The 'vm=auto' tag tells bootpd to use the same vendor encoding
as the bootrom. If your diskless client is going to use it's root filesystem
via NFS you should also specify the directory on the server which gets mounted
lateron with the 'rp' tag. However, if your diskless client uses a ramdisk,
you can omit 'rp'. When you choose to use the standard bootrom with ANSI
display driver (see below for further information) you could also setup
a menu for letting the user select different boot image files. See the
additional file INSTALL.menu about how to use this feature. But I recommend
to first use the standard way of setting up the bootptab file as described
above. You can always add a user menu lateron.
Of course you should also remember to get bootpd running on the server,
either on bootup from /etc/rc or some similar mechanism, or from inetd.
Again, see your server's documentation about how to do this.
The next step preformed by the bootrom after querying the bootp server is
to load in the boot image file specified by the 'hd' and 'bf' tags in
/etc/bootptab. To do this a protocol named tftp is used. Therefore you
will next have to setup a daemon process for this protocol on your server.
Such a daemon is usually called tftpd, and you should again remember to
get tftpd running, usually via inetd. Since the TFTP protocol is very
insecure access to the tftpd server is usually restricted, either within
tftpd itself, or with a TCP/IP wrapper like tcpd. tcpd for example uses
host access control tables which are stored in /etc/hosts.allow and
/etc/hosts.deny. See tftpd(8), tcpd(8) and hosts_access(5) as well as
your server's documentation for further information.
If you selected a ramdisk for the diskless client's root directory you are
now finished with the server setup. But if your client is going to use NFS
(either directly like with booting Linux, or by using programs included on
the ram disk) you should now setup everything which is necessary for moun-
ting an NFS directory on the server. This usually involves running several
programs: portmap, mountd, nfsd and optionally ugidd. portmap usually doesn't
require editing any configuration files. But for mountd and nfsd you need
to specify the permissions which allow the client to access the required
directories on the server. These permissions are usually set with a file
called /etc/exports. Typically it looks like this for our sample client:
#
# Export directories for client1 (diskless workstation)
#
/boot/client1/root client1(rw,link_absolute)
/boot/client1/usr client1(rw,link_absolute)
If you use 'map-daemon' to map UID and GID numbers on the server you
should remember to also configure and run ugidd on the server. Please
consult your server's documentation for further information regarding
setup of NFS exports. You might also want to check out the portmap(8),
nfsd(8), mountd(8) and ugidd(8) man pages. Also remember that access
to any of these services might be restricted with tcpd on your server.
Another important step is to fill up the root directory for the disk-
less client. It has to contain all files necessary for the client to
startup and mount further directories via NFS (like a /usr filesystem
as specified in the /etc/exports example above). How to setup this
root directory is far beyond the scope of this documentation. Just one
hint: if your server is _not_ running Linux, you should be aware of
major/minor number assignments in the /boot/client1/root/dev directory.
For example, simply using mknod on an AIX server will eventually give
you wrong major/minor number when the directory is later exported to
a Linux diskless client. With some configurations AIX will add a certain
offset to all major numbers which makes them unusable for Linux. Refer
to your server's manuals for further information. You might also find
some useful hints in the file Documentation/nfsroot.txt in the Linux
source tree, if your diskless client is booting Linux.
Setup of the client including building the bootrom
==================================================
Until now you only had to work on the server (with the exception of maybe
booting your diskless client from a diskette to check the correctness of
the root filesystem). As the last step we can now go on and setup the
diskless client itself.
The first step is to configure the network card in the diskless client. For
this refer to the manual which came with the network card. Some cards require
setting of jumpers. Others have setup programs which have to be run. After
configuring the network interface write down all necessary hardware parameters
like I/O addresses, memory addresses, interrupt line number or DMA channel
numbers, as you might need this information lateron in the configuration
process.
Next change into the netboot directory on your UNIX system (where this
documentation file is in) and type
make bootrom
This will compile all necessary utility programs and then run the
configuration program. It will first ask you which bootrom kernel you
want to use. The minimal kernel is necessary for network cards which
only allow up to 16 kB ROM size, and kernel86 can be used to boot on
16-bit systems (older than 386), for example for booting MS-DOS. Unless
you have any special requirements you should choose the standard kernel.
Then you have to specify the packet driver to use for your network card.
You can either choose one of the supplied drivers, or provide your own.
If you want to provide your own driver you have to give the full path
name of the packet driver binary on your server, and also specify all
necessary options to run it. Don't specify any options here which switch
the packet driver into windows mode or which allow it to work for disk-
less systems. Those options are for Novell network bootroms only, and
are not necessary for this bootrom.
If you use one of the drivers in the list shown, the configuration
program will ask you about all necessary hardware information to run
the packet driver which you selected. This usually includes the I/O
address of the network card, it's interrupt number and a DMA channel
number. Note that only that information is requested which is really
necessary. You should have your network card information handy when
entering this information. Some packet drivers are able to determine
hardware related information at runtime and therefore don't require
any further information.
If you did not select the minimal kernel, the configuration program
is next going to ask you wether you want to include some additional
drivers. First it lets you select the ANSI display driver. This will
allow you to draw nice menus on the screen with the standard bootrom
kernel. You can then select the packet driver debugging program. It's
an additional module to trace network problems and is usually not re-
quired. It shows you the first couple bytes of all packets (where
the UDP/IP headers are encoded) going through the packet driver
during boot time of the diskless client. Only select this debugging
module if you run into problems during the initial network boot process
of the bootrom _and_ you know how to decode the UDP/IP header infor-
mation. The configuration program will also ask you about any additional
modules you want to install into the bootrom. These modules have to
be standard DOS COM-type programs, and can, for example, preset
the network card to a special state before the packet driver starts,
or setup a serial line to support booting over a PPP or SLIP connec-
tion (the Crynwr packet driver collection also contains a SLIP packet
driver which is not provided in this package). However note that the
total size of the resulting bootrom image can't be larger than 64kB.
After you answered all questions the configuration program is creating
the bootrom according to your specifications. It first combines the
bootrom kernel with all selected modules, then compresses the resulting
file and adds the bootrom startup code. When the configuration program
has finished you will find two new files in the current directory:
image.flo - this file can be written onto a floppy using dd
image.rom - image to be burned into an EPROM
You should now copy image.flo onto a floppy using
dd if=image.flo of=/dev/fd0
and then boot your diskless client using this floppy. If you have setup
everything (including your network card) you will see the bootrom code
starting, querying the bootp server and loading the boot image file. When
everything works as required you can then go on and burn the file image.rom
into an EPROM. Please consult the manual of your EPROM burner how to do
this. It usually requires converting the image file into a special format
(Intel or Motorola hex format for example). Insert the EPROM into the
socket on your network card and turn on the diskless system. You should
now see the bootrom coming up.
Another way of getting the bootrom code into your client is using the
Flash-EPROM card (called FlashCard), for which you can find a schematic
and PCB layout in this package. You can use image.rom directly to burn
it into FlashCard - there is no hex conversion necessary. About how to
use and program the FlashCard see the documentation in the FlashCard
directory.
In case you want to create new bootroms without always having the sources
around, you can now install the binaries created during the configuration
step with the command
make bootrom_install
This will copy all necessary binaries for creating new bootroms into the
directory $prefix/lib/netboot where $prefix is either /usr/local or the
prefix you specified with running GNU configure. The typical path would
be /usr/local/lib/netboot. It will also install the makerom script into
$prefix/bin, so you just have to type makerom to create a new bootrom.
Appendix: Recompiling the bootrom
========
If you want to recompile the bootrom for some reason, checkout the file
INSTALL.bootrom for further information. However, you don't need to re-
compile the bootrom in order to just use it!