There's also an Appendix,
which may be useful if you're new to Unix installation.

Choosing a helper machine

Installing NetBSD on a pmax cannot be done standalone.
The very first thing you need to do is to choose a helper
machine to perform some of the initial installation steps.
You also need a disk on which to install NetBSD. Any information
on this disk will be lost.

Why do you need a helper machine? The simple answer is, you need
a helper to write a bootable NetBSD system onto a hard drive, because
that's the only guaranteed way to boot NetBSD on a DECstation.

Pmaxes don't have floppy disk drives for
the most part. Even those that do, don't support booting from them.
Booting from tape, and making tape distributions, is too painful.
And since NetBSD
does not yet boot diskless
on all DECstations, you may have no option but to construct a bootable disk
using a miniroot and a helper machine.

Clearly, for installation on your first NetBSD/pmax machine, you can't
use a NetBSD/pmax system to build that boot disk. You need to use some
other system. Let's call this other system the "helper". You also need a
disk drive onto which you'll end up installing NetBSD: the target
disk.

There are three slightly different paths. Using another NetBSD system
as a helper; or using Ultrix on a second machine as a helper; and
using Ultrix on the target machine as a helper. Which path you choose
depends on which is most convenient in your environment. However,
keep in mind the fact that you're going to have to move the target
disk from the helper to the target machine at some point -- and possibly
several times, if you have trouble during the installation.

The bad news is, even when you get a miniroot filesystem installed,
labelled, and booted, it's still far too small to hold a real root
filesystem. You will almost certainly want to label
a second target disk whilst running the NetBSD miniroot, use “tar”
to copy the miniroot environment to the a partition of the
second disk. This is a pain, but currently
unavoidable.

Where to get installation files

Once you've chosen a helper platform, the next thing you need to do
is to get the installation images for NetBSD/pmax. You need bootblocks
that can boot a NetBSD kernel from disk, and a bootable, cut-down NetBSD root
filesystem image -- a miniroot. These should be
available from the NetBSD FTP site.
Visit ftp.NetBSD.org
to see the latest stable versions.

If you can't find a helper machine, or more correctly you
can't find a suitable disklabel program for it, there's still
a dirty hack you can use.

Labelling a disk for NetBSD

Labelling a disk does two things. It tells NetBSD how to divide the
disk into partitions. It also puts a boot
block on the disk. Unlike Ultrix, the NetBSD disk label lives
inside the bootblock, so you cannot label the disk without updating
the bootblocks.

It's worth stressing the following point: Since
the disklabel tells NetBSD how the disk is divided into partition, it
obviously is going to tell NetBSD where to look for the
miniroot,
and a real root, when you eventually get around to booting it. But you need
to put at least a miniroot onto a disk and boot, before you can use
NetBSD to read the disklabel. So you need to access the NetBSD
partitions, somehow, from whatever your helper system is. But you
need to use the helper's disk drivers (and some kind of disk label) to
do this.

Disklabels and NetBSD/pmax SCSI unit numbers

Before you label a disk, you need to choose which disk you're
going to install NetBSD on!

The pmax kernel distributed on miniroots hardwires SCSI ids
0, 1, 2, 3, and 4 to be disk devices. You need to make sure
that the SCSI ID of your target disks are in that range, or that
you can them to be in that range before you boot them on a DECstation.
The miniroot kernel also hardwires units 5 and 6 to be tapes; the
CPU's SCSI adapter is SCSI 7. This very likely will not
be the same numbering convention your helper machine uses.

Numbering will get much more flexible when we move to using
the "standard" NetBSD SCSI drivers.

Running disklabel

The best way is to get a version of the NetBSD disklabel program
for your "helper" machine. The previous section
explains how to do this.

Once you have disklabel for your helper get bootrz and rzboot
and put them in /usr/mdec. Then, decide how big you want
your partitions to be and write a disk label to the target disk.
This automagically put NetBSD/pmax bootblocks on the target disk.

To label a disk, on Ultrix, at unit number 3, using the NetBSD disklabel
program compiled under Ultrix:

# disklabel /dev/rz3c -b rzboot -s bootrz

NOTE: if you use a non-PMAX NetBSD machine it will
assume you want to write the native bootblocks. You'll need
to specify -b rzboot -s bootrz. It's not known
that this really works. You may need to cross-compile a disklabel
specially configured for pmaxes.

Note: The precompiled binary is an ECOFF version 3.0
binary. It should run on Ultrix systems from 4.2a through 4.4. If
you have problems with core-dumps, read the README file that comes
with the cross-disklabel tools. Also note that the /etc/disktab format
the cross-disklabel needs is the NetBSD format, not the Ultrix format.

Notes on sizing partitions

It's worth noting that you want at least 16 Mbytes for a root partition.
That's big enough to comfortably hold two or three different kernels,
assuming /var (and /var/tmp) are not on the root partition.
You want about 200 Mbytes for a full /usr partition.

Writing the miniroot to the target disk

Once the target disk is labelled, the next step is to write the miniroot into the A partition. (You
have to use the A partition, because
some Decstation boot PROMs can only boot from an A partition,
and because miniroots on b partitions don't work anymore).

Some nomenclature

Different operating system uses different names for disk drives.
Ultrix and NetBSD/pmax use rz#P, where "rz" means "scsi disk",
# is a disk drive number, and P is a letter from a to h,
indicating one of 8 partitions on the drive. One partition is
used to map the entire drive. That's usually the 'c' partition,
except on NetBSD/i386 systems, where it's the 'd' partition.

Most other systems use sd instead of rz.

Writing miniroots with dd

The simplest and safest way is to get a miniroot and
dd it onto the "c" partition of the target disk, using
seek to skip past the NetBSD/pmax bootblocks and disk label.
This may seem roundabout, since we're trying to put the miniroot
onto the "a" partition. But since an "a" partition
starts at different block numbers on NetBSD and Ultrix, this really
is the safest way. The other catch is that a BSD filesystem image
starts with a reserved 8-Kbyte (16 sector) area, where the bootblocks
and disklabel are written. A miniroot is usually intended to be
installed in the "b" partition, well away from the "real" bootblock
and disklabel area. But we're going to install the miniroot on an
'a' partition, as that's the only partition that is bootable on all
DECstations. So you need to carefully avoid copying the bootblock and
disklabel from the miniroot onto the disk, or the bootblock/label region
in the miniroot will overwrite the disklabel we just went to such
effort to write onto the target disk.

To do this, use a command like

dd if=miniroot of=/dev/rD#P seek=16 skip=16

where D is a disk name, # is a unit number,
and P is the partition for the whole disk.
For example, with the target disk on an Ultrix system, at unit 1,
that would be

dd if=miniroot of=/dev/rrz1c seek=16 skip=16

and on a Sun, with the target disk at unit 2, the corresponding
command would be

dd if=miniroot of=/dev/rsd2c seek=16 skip=16

Note that earlier versions of these instructions omitted the
skip=16 step. A workaround for that bug was to use
an offset of 16 in the disklabel of the "A" partition. This should not
be necessary if the skip=16 is specified.

Booting the miniroot

Once you have labelled the target disk, and dd'ed the miniroot onto it,
you are ready to boot NetBSD. Move the target disk to the target machine
and boot it. If you're familiar with your DECstation PROM,
you can skip the rest of this section.

The boot command you need to give the boot PROM depends on what
model of DECstation your target is, the unit number of your SCSI disk,
and which SCSI bus it's connected to.

In the examples below, # indicates the SCSI ID of your
target disk, when it's on your target machine.

On a 3100, type:

setenv bootpath rz(0,#,0)netbsd
boot

On a 5000/200, type:

boot 5/rz#a/netbsd

On a 5000/2x, 5000/1xx, or 5000/240, type:

boot 3/rz#a/netbsd

(If your target disk is attached to a TURBOchannel PMAZ-AA
optional SCSI adapter, you should replace the
3 or 5 with the slot number of your SCSI adapter.)

This will boot the miniroot. You should then see output something like:

The miniroot is now prompting you for a disk to use as the root filesystem.
It's impossible to tell, when compiling a miniroot, what disk drives
any given installer will choose to put NetBSD on. So the miniroot kernel
asks which disk drive it should use as its root filesystem.
You need to answer with the disk drive on which you put the miniroot
(e.g., rz0 for drive 0, rz1 for drive 1, and so on).
If you have more than one disk drive, the list of disk drives and
unit numbers the kernel printed out should help you figure out the
right response.

Making /dev

The miniroot is too small for most users to use as a full
partition. The first thing Many NetBSD/pmax installers do after
booting a miniroot (or NFS kernel) is to label another disk,
and install the distribution sets there. If you do so,
then you must run the MAKEDEV script, by hand,
in the /dev directory of the new local disk.

If you install the full distribution on a root disk and do not
run MAKEDEV, you will not be able to boot from that disk --
not even in single-user mode.

Unpacking a full system

You now have NetBSD up and running on a pmax. Congratulations!

The next thing to do is to unpack a full set of binaries and
configuration files. Newfs the partitions you want to use for NetBSD.
Then mount a disk that has a copy of base.tar.gz, and
unpack it. (You can either mount an Ultrix disk read-only,
or configure the network and NFS-mount from another machine).
After that, unpack base.tar.gz with the obvious commands.
And then you're done!

Of course, you'll want a full-size root partition first. If you have
a disk with an empty 'A' partition, you newfs it, mount it, and can
copy the contents of the miniroot to it with a command like:

( cd / ; tar cpf - . ) | (cd /newroot ; tar xpf - )

What Next?

(This section is just a skeleton of examples that aren't done yet.
Doing them properly could take a whole book.)

Appendix

What are bootblocks?

A bootblock is a small piece of machine code that lives on the
start of a disk. At boot time, the boot PROM reads the bootblock
into disk and executes it. The bootblock then continues bootstrapping
by reading an operating system into memory and jumping into it.

In the DOS world, a bootblock is something like the Master Boot
Record, or MBR.

Why do I need to write bootblocks?

Ultrix bootblocks read Ultrix kernels; they cannot read NetBSD
kernels. So to install a NetBSD kernel, you need to install
NetBSD bootblocks. (The alternative is to cross-compile a NetBSD
kernel in ECOFF, the binary format that Ultrix uses. This is no fun.)

Why do I need to label my disk?

As well as updating the bootblocks on a disk, labelling a disk
give you an opportunity to decide how big you want your disk
partitions to be. If you have small disks (which many old DECstations
are likely to have), this can be a vital step. Deciding
exactly how much space to allocate for swap and a /usr partition
may mean the difference between NetBSD fitting on your system, or not.

What is a miniroot?

A miniroot is a minimal, bootable Unix root filesystem. It contains
a kernel, and just enough user-level programs to label a disk, mount
a filesystem, and then unpack a dump of a full system.

The traditional way to install 4.3BSD UNIX on a VAX-11 was to enter a
small bootstrap program, in hex, from the console, and start the
machine. The boot program would load a standalone monitor from a
half-inch tape drive. Then, one used the standalone copy program to
copy a miniroot -- the first file on the tape after the standalone
utilities -- to what was going to be the swap partition of the 4.3BSD
system. The miniroot has a special kernel that asks the device name
to use as a root filesystem. If the root filesystem ends in *,
then the miniroot knew it was running out of a swap partition,
and didn't swap on itself. This leaves the a partition of the target
drive free. You then use the miniroot to newfs and unpack a root
filesystem onto that a partition.

For example, one would use “dd” to write a miniroot
onto NetBSD's b partition, booting it via
“boot 3/rz1b/netbsd”, the miniroot to run
on “rz1*”. Then use the miniroot shell to
newfs “/dev/rz1a” and a “/usr” partition,
and unpack a distribution onto the full root and “/usr”

It may help if you think of a miniroot as simply being an binary
image of a boot floppy. Since 5 Mbyte floppies are hard to come by,
we just write it to a hard disk instead. The easiest place
to put it the miniroot is in the front of what will become
the swap partition of the target disk, being careful not to swap there
in the meantime.

NetBSD/pmax installation is much more complicated than this,
because for a, variety of reasons,
booting miniroots from swap partitions
just doesn't work.

When you can't find a helper machine

If you're a real wizard who's installed BSD on Vaxes and is used
to building their own miniroots, or you're using some strange helper
machine, you can try this dirty hack:

cat miniroot | dd of=/dev/r#c

but that's strongly dis-recommended, because it doesn't
let you customize the disk label. In fact, you end up with
no diskabel, so the kernel defaults to a compiled-in
disk label that was suitable for a particular machine at Stanford.
In addition, newer miniroots are prepared using the vnd
driver instead of a real disk. vnd doesn't support writing
disklabels, so newer miniroots may contain zeros instead of a pre-installed
bootblock and disklabel. Attempt this at your own risk!

If you try this, you'll probably need two target disks: one for this
dirty hack, and a second which you label after booting the miniroot
set up with that dirty hack. It's also probably safer to
use boot.dd instead of bootrz and rzboot.

boot.dd is the first 8 Kbytes -- the boot blocks and disk label
-- dd'ed off a 'C' partition of a machine at Stanford, so the bootblocks
and disk label can be dd'ed into the first 8 Kbytes of a disk,
if there is absolutely no other way to construct a disklabel.

What about netbooting?

Eventually we would like to support installation of NetBSD/pmax
by booting NetBSD on a target machine across the network. This defers
all the problems with bootblocks and labelling disks until you
actually have NetBSD up and running on the target machine. The target
machine boots as if it were diskless, and can then
install NetBSD onto its local target disk.

However, NetBSD/pmax doesn't yet boot diskless on all machines,
so this isn't a generally-available option. If you wish to pursue it,
see the NetBSD diskless 8 manual page and the
pmax diskless boot configuration instructions.

Booting from Ultrix

There's a tool called elf2ecoff which you can use to make a bootable
ECOFF NetBSD kernel. This kernel can be booted by the Ultrix
bootblocks. If you get really stuck with the miniroot, you may
wish to try building an ECOFF kernel.

Diskless boot configuration

Note: These diskless-boot instructions may be incomplete.

Many DECstations will boot diskless using bootp and tftp.
Whether or not yours will depends on the specific PROM revision you have.
On those systems that can boot diskless, setting up a diskless-boot
configuration may be the simplest way to label a local disk and install
install NetBSD on it. (In effect, you use a diskless-booted NetBSD
setup on the target machine as your helper machine.)
Alternatively, you may wish to configure a NetBSD/pmax machine for
production use as a diskless client. This section is an overview
of how to set up a Decstation to boot NetBSD diskless, for either
installation or permanent diskless boot.

PROM commands for diskless boot

On a 5000/2x, 5000/1xx, or 500/240, the PROM command

boot 3/tftp

will attempt to netboot an ECOFF-format binary using
the builtin Ethernet interface.
On a 5000/200,

boot 6/tftp

does the same thing. On a 2100 or 3100, (boot -f tftp() is
reported to work, but I am unable to verify it. If that fails on a 2100
or 3100, you need to do

setenv bootpath tftp()kernelname
boot

Note that on the 3100, this clobbers any previous PROM bootpath.
Write down the previous value of bootpath and keep it safe!

NetBSD/pmax kernels are compiled as ELF, and then converted to a.out
so that the standard NetBSD tools (e.g., libkvm and (nlist)
can read them. To build a net-bootable kernel, first configure and
compile a kernel, say nfsnetbsd. Then convert the elf image
(netbsd.elf) to ECOFF using the elf2ecoff tool.

Luckily, the kernel Makefiles already do something very similar, to
convert the ELF-format kernel produced by the linker to a.out. You can
almost cut-and-paste the commands. Just remember to change elf2aout
to elf2ecoff. Be careful not overwrite the a.out kernel, if you'll
want it later for a diskful boot!

Bootp configuration

Once you have an ECOFF-format kernel, the next step is to get it into
the diskless machine. For the diskless-boot tftp commands to work, you'll
need to configure bootpd on some machine on your network to listen for
bootp requests. You will also need to run tftpd to send a NetBSD
kernel to the diskless-booting DECstation. A sample /etc/bootptab
entry that provides an IP address and the name of a kernel to boot,
or a machine called "Newbie", with hardware address 08:00:2b:1e:39:cc,
and IP address 10.0.0.84, is:

The 'ha' field is the hardware address of the machine requesting the
diskless boot, and the 'bf' is a path that should be accessible for tftp.
You can find the hardware address by examining the PROM startup message on a
3100, or using the PROM cnfg command on a TURBOchannel machine.

A suitable kernel to use for diskless booting is the
nfsnetbsd file from the NetBSD/pmax distribution. If you
obtained nfsnetbsd.gz, remember to gunzip it before booting!

Setting up an NFS server for the diskless client

Now, obtain and read the diskless(8) man page from a current NetBSD
distribution. Note that NetBSD/pmax has no second-stage
bootloader; the PROMs support tftp, and we attempt to use tftp to load
the NetBSD kernel directly, rather than using a secondary boot loader.
Otherwise, follow the diskless CONFIGURATION directions as if you were
booting a Sun, but skipping section 4. Instead, install the NetBSD/pmax
kernel into the tftp boot directory (usually /tftpboot/.)

In section 8, make sure that you add the '-alldirs'
flag to /etc/exports, if you're using a NetBSD system as the server. Also,
if you get the client's root partition from the binary distribution,
don't forget to populate its /dev directory.

Assuming all this works, you'll be running NetBSD with a root shell
on the console. You can proceed to label your disk,
newfs root and /usr partitions, and install the full binary distribution.
There is no need to install a miniroot: if you can netboot NetBSD, you have
all the tools necessary to label a disk and install a full-sized root and
/usr partition.

Using Ultrix as a diskless server

These instructions worked for a NetBSD/pmax kernel built from
the alpha release of NetBSD 1.2. They assume that the server for the
diskless-boot machine is another NetBSD system. They have not been
tested using an Ultrix system as the boot server. One missing piece
for diskless boot from an Ultrix system is an rpc.bootparamd server.

The pmax boot PROMs use (dhcp-compliant) bootp requests to obtain an
IP address and TFTP server from which to load a kernel; but once the
NetBSD kernel itself is booted, it uses the rpc.bootparam protocol to
find the IP address and other information. Ultrix does not include an
rpc.bootparamd server.

Andrew Gallatin
(gallatin@cs.Duke.EDU) has an rpc.bootparamd server that works under
Ultrix, and will supply it on request. We are interested in hearing
from anyone who tries this. We are also interested in building a list
of which PROM versions and systems can boot successfully using tftp
and/or MOP.

If things still don't work

Kernel seems to load, but crashes during boot

If you have problems booting a kernel, try building a stripped-down
kernel (e.g., without COMPAT_ULTRIX, NFS_SERVER, UNION, SCSI support,
etc.). From trial and error, the critical variable seems to be the
kernel text size. (Changing elf2aout to emit separate a.out text and
data segments may also help; that has not been tried).
Even machines with `problem' PROMs seem to boot successfully if
the kernel text is stripped down far enough. We don't yet have a good
estimate of what is `small enough'; reports of success are definitely
encouraged.

Digital UNIX as an NFS server

If you are using a Digital UNIX system as an NFS server, beware
of the inode translation done by Digital UNIX. The recommended solution
is

Untar /dev/console and /dev/MAKEDEV into the diskless machine's
root directory on the server (e.g., /diskless/MACHINE_NAME/root/dev,
not the server's own /dev directory).

Acknowledgements

The network-boot instructions are largely based on Andrew Gallatin's
experimentation with diskles pmax kernels, and Andrew's early notes.
The diskless boot documentation wouldn't exist without Andrew's efforts.