NetBSD/sys/arch/i386/netboot/README

$NetBSD: README,v 1.2 1994/10/27 04:21:00 cgd Exp $

Ethernet boot prom code.

This is code that can be burned into an eprom and installed in an
ethernet card. It uses the extension facilities of the bios to to boot
a kernel via the network.

Netboot uses bootp or rarp to determine its ip address and tftps a
designated kernel from a server. You should be running a daemon for
either bootp or rarp to service requests from this client. If you are
using bootp, the boot file name and the gateway (if necessary) will
also be transmitted to the client. If you use rarpd, the boot file
name is synthesized by this boot code from the eight hexadecimal
digits that comprise the IP address of the client and an extension of
"386bsd". If you use rarp, the rarp server must also be the tftp
server.

If you have configured both bootp and rarpd into the boot prom, the
response from the first host to respond via either protocol will be
used.

This code was developed using GNU as 2.1 and GNU cc version 2.3.3,
running under 386bsd.  Pre 2.0 versions of GNU as might have trouble
with some syntax.  Testing was done with a SMC Elite16 and 16k eproms.


Installation instructions:

Check the configurable parameters in Makefile.

Check the configurable parameters in the ethernet driver source for
the card you are using:
- in wd80x3.c: WD_BASEREG, WD_BASEMEM (irqs not used)

Make.

If you wish, you can test the binary (boot.bin) by copying it to a
floppy with the dosload.exe program and execute the boot code from the
floppy.

Burn the resultant binary (boot.bin) into an eprom and install it in
the ethernet card.

Decide which protocol (bootp or rarp) to use on a server; set up that
server.

Setting up a bootp server entails creating a bootpd client
configuration file. The format is similar to that of printcap. An
entry looks something like:

sams-1:\
	:bf=diskless_kernel.386bsd:\
	:gw=139.88.30.4:\
	:ht=ethernet:\
	:ha=0000c025e35b:\
	:ip=139.88.30.39:\
	:sm=255.255.255.0:\
	:to=18000:

Setting up a rarpd server entails creating an ethernet/ip address
resolution file '/etc/ethers' with a line for each netboot client in
the form:

00:00:c0:25:e3:5b       sams-1.lerc.nasa.gov

If you don't know the ethernet address, boot the client with the eprom
installed; the ethernet address of the card will be displayed.

Set up tftpd on a server. Check '/etc/inetd.conf'; there should be a
line that starts something like:

tftp    dgram   udp     wait    root    ...

perhaps commented out.

Build a kernel that is capable of operating via NFS.  Martin Renters
released some patches and a kernel configuration program that work
nicely (comp.os.386bsd.development around March 22, 1993); they should
be around somewhere. If you can't find them, I can email you a copy.

Make the kernel available via tftp under one of the names which this
code will use to look for the kernel.  If you are using bootp, you can
specify the name as a bootp client configuration parameter. If you
don't specify the name, or if you are using rarp the this code will
synthesize the name using its client's IP address.  The hexadecimal
version of the client's IP address with the extension '.386bsd' is the
default choice.

Create the exportable nfs mount points for which this kernel will use
and load them with necessary files (the base distribution, ...).
Export them so they can be mounted by this kernel when it boots from
the client IP address.


Usage instructions:

At any time the escape key can be struck to gain entrance to the
interactive monitor. There is a menu of monitor commands that can be
invoked to customize a boot operation.


Notes:

When Martin Renter's patches are applied to netbsd 0.8, there will be
one failure (pmap.c). Ignore it, the relevant code has already been
fixed.

I had some small problems with getfh(2) as used in the nfs configuring
program - I suspect the problem is a bug in SunOS 4.1.1 - if you have
similar problems, I can email you my gross hack workaround.

As noted by Mr. Renters, advisory flock()ing is not supported - this
breaks some programs. The first broken utility you will likely
encounter is vipw(1). The others: passwd, dump, ar, mail, tip, lpr,
sendmail.

You should examine your rc script and make appropriate changes to the
boot up sequence.

Here are the steps I took to bring netbsd 0.8 up for the client sams-1
using the host dinah in the domain lerc.nasa.gov.

- Create the /dev/vga device.

- Create some ptys.

- Create /etc/fstab to contain:
	dinah:/home/386bsd-root / nfs rw
	dinah:/home/386bsd-swap none swap rw
in it for the root and swap.

- Edit /etc/rc; the line 'mount -a -t nonfs' is changed to:
	mount -a -t nonfs,swap

- Edit /etc/myname to contain
	sams-1

- Edit /etc/hosts to contain:
	127.0.0.1       localhost loghost
	139.88.30.39    sams-1
and delete the other stuff in it.

- Create /etc/resolv.conf to contain:
	domain lerc.nasa.gov
	nameserver 128.156.1.43
	nameserver 139.88.76.3
where the two addresses are those of some name servers in my domain.
There are, of course, the two alternatives of using just the /etc/hosts
file, or using named.

- Create /etc/mygate to contain:
	139.88.30.4
which is the IP address of my gateway.

- Re-symlink /etc/localtime to the correct zone.


TBD:
-linux
-ne2100
-handle small memory configuration
-USE_BIOS version
-return to bios correctly
-remove old Phys... stuff; relics of real mode prom version
-accept bootd extension items & pass as args, modify kernel to
 init nfs_diskless from args. Need:
	myif			[local]	[bootp]
	mygateway			[bootp]
	swap_args		[local]
	swap_fh				[bootp]
	swap_saddr		[local]	[bootp]
	swap_hostname			[bootp]
	root_args		[local]
	root_fh				[bootp]
	root_saddr		[local]	[bootp]
	root_hostnam			[bootp]
 A tight squeeze, passing all necessary info in one bootp packet.

Please send me any improvements you make to this code. It will be
appreciated.

Jim McKim (mckim@lerc.nasa.gov)