path: root/distrib/notes/pmax/install

Installing OpenBSD is a relatively complex process, but if you have
this document in hand it shouldn't be too much trouble.

Also i wanted to note that the installation procedure via install
script is new for the pmax and i had only the chance of limited
testing for it - so if you run into any problems with it or if this
documentation is somehow unclear - please send me a mail and I'll try
to help you or to fix the problem.

There are several ways to install OpenBSD onto a disk. The easiest way
in terms of preliminary setup is to use the OpenBSD simpleroot that can
be booted off your local disk. Alternatively, if your Decstation is
hooked up in a network you can find a server and arrange for a diskless
setup which is another convenient way to install OpenBSD/pmax.


Installing using the OpenBSD simpleroot.

The simpleroot is a self-contained OpenBSD filesystem holding a complete
OpenBSD/pmax root filesystem plus all utilities necessary to install
OpenBSD on a local disk. It is distributed as a plain file designed to
be transferred to a raw disk from which it can be booted using the
appropriate PROM command.

Loading the simpleroot onto your raw partition is simple. You can do
this on any machine you can hang on the disk which you plan to put
onto the pmax which allows you to write to the raw disk - i.e. on all
UN*X like operating systems it should work using "dd". On OpenBSD
as well as SunOS you use a command like:

	{:-#-:} dd if=simpleroot{:--:}OSrev.fs of=/dev/rsd0c bs=20b

Especially on OpenBSD/pmax you'll have to use /dev/rrz0c or something
like that instead of /dev/rsd0c.

Keep in mind that this will overwrite the contents of that disk!

After transferring the simpleroot to disk, bring the system down by:

	# halt

and hang the disk onto the pmax you want to install OpenBSD/pmax on.
Then boot the simpleroot by typing the appropriate command at the PROM:

	>> boot rz(0,0,0)/bsd		# for Decstation 2100/3100

	>> boot 5/rz0a/bsd		# for Decstation 5000/2xx

	>> boot 3/rz0a/bsd		# for Decstation 5000/1xx

If you've loaded the simpleroot onto some other disk than `rz0' adapt
the boot specifier accordingly.

This will cause the kernel contained in the simpleroot to be booted.
After the initial probe messages you'll asked to choose a shell with
sh as default. Simply type Return here and you are in single user
mode. For further instructions please read on in the "Continuing the
installation from single user mode" below.

If the boot hangs without loading the kernel on a Decstation 5000,
the SCSI controller may be in a strange state.  This can happen if
you interrupt the self-test during boot or after hitting the reset
button.  To fix this, hit ^C to get back to the ROM monitor and
enter "init".  You should now be able to boot as described above.

Note: if booting the kernel in the miniroot should not work - there are
      two kernels part of the distribution - look at the place you got
      the distribution from - the kernels are there also - so you can
      see which kernels there are - usually there should be 3 of them

        * bsd - a generic kernel which should ask for the root device
        * bsd.rz0 - generic kernel with root and swap fixed to rz0
                    don't ask me why - but this should be usable then
                    installing from a simpleroot on a zip disk (which
                    is usually rz5 or rz6 - bsd crashes here :-)
        * bsd.nfs - a generic kernel with root and swap configured
                    to be on nfs (also this kernel is in ecoff and not
                    in a.out format so that it can be netbooted with a
                    pmax)


Installing using a diskless setup.

First, you must setup a diskless client configuration on a server. If
you are using a OpenBSD system as the boot-server, have a look at the
diskless(8) manual page for guidelines on how to proceed with this.
If the server runs another operating system, you'll have to consult
documentation that came with it (on SunOS systems, add_client(8) is a
good start).

One part of the distribution of OpenBSD/pmax is a file called
simpleroot{:--:}OSrev.tgz which is a good start for the root filesystem area on
the NFS server then you want to install via network.

A few configuration files need to be edited:

	<root>/etc/hosts
		Add the IP addresses of both server and client.

	<root>/etc/myname
		This file contains the client's hostname; use the same
		name as in <root>/etc/hosts.

	<root>/etc/fstab
		Enter the entries for the remotely mounted filesystems.
		For example:
			server:/export/root/client       /     nfs  rw 0 0

Now you must populate the the `/dev' directory for your client. If you
have an intelligent tar command on the NFS server the /dev directory
inside the simpleroot{:--:}OSrev.tgz should be usable (i.e. containing
special devices and not only files) - else you'll have to remake the
devices on the server using

	cd /export/root/client/dev
	mv MAKEDEV* ..
	rm -rf *
	mkdir fd
	mv ../MAKEDEV* .
	./MAKEDEV all

This may not not work correctly on some operating systems.

Ok here is in short form what you have to do on the Server to prepare a
diskless installation of OpenBSD/pmax assuming the Server is an
OpenBSD machine (for instance a PC running OpenBSD/i386). As said
above for other systems you'll have to look into the supplied
documentation for that systems. All the following should apply also
without any major changes to an FreeBSD or NetBSD server.

If the following instructions are not enough - you may look at the
man pages for the following commands:

* tftpd
* rarpd
* bootpd
* rpc.bootparamd

Ok - now let's see what to do to set up the server:

* set up a file /etc/ethers containing the ethernet hardware address
  of the pmax you want to boot via net and its hostname (the hardware
  address you should get via PROM commands)

  example:
  --- snip ---
  08:00:2b:1a:4b:41       summer
  --- snip ---

* add an entry to /etc/bootptab which looks like the following:
  --- snip ---
  .ris.dec:hn:vm=rfc1048
  summer:ht=ethernet:ha=08002b1c4d51:ip=10.0.0.5:bf=/bsd
  --- snip ---

* make sure that the following line in /etc/inetd.conf is not
  commented out:
  --- snip ---
  tftp           dgram   udp     wait    root    /usr/libexec/tftpd tftpd -s /tftpboot
  --- snip ---
  if it is commented out (which is the default on OpenBSD for security
  reasons) - uncomment it and send the inetd process and HUP signal

    kill -HUP `cat /var/run/inetd.pid`

  so that it rereads the /etc/inetd.conf file

* untar the simpleroot{:--:}OSrev.tgz on the server in an nfs exported
  directory - for instance /export/root - so /etc/exports should
  contain a line like (OpenBSD syntax !)
  --- snip ---
  /export -alldirs -root=0:0 summer
  --- snip ---
  for the example above - on OpenBSD the tar should be intelligent
  enough to unpack the /dev directory correctly - on other systems you
  may look at the comment about /dev above. So what you have to do in
  this example you have to do:
    
    mkdir /export/root
    cd /export/root
    tar xvpzf /some_path/simpleroot{:--:}OSrev.tgz
    vi /etc/exports (to add the above line)
    kill -HUP `cat /var/run/mountd.pid` (so that mountd rereads exports)

  Note: also make sure that the server is configured as nfs server -
        i.e. for OpenBSD "option NFSSERVER" for the kernel and the
        following set in /etc/netstart:
        --- snip ---
	nfs_server="YES"
        nfs_client="YES"
        --- snip ---

* create an swapfile using (example 16 mbytes):

    cd /exports
    dd if=/dev/zero of=swap bs=1024k count=16

* copy the kernel from the /export/root area to the tftp area:

    mkdir /tftpboot
    cp /export/root/bsd_nfs /tftpboot

* create a /etc/bootparams file - for example:
  --- snip ---
  summer  root=prospero:/export/root \
          swap=prospero:/export/swap
  --- snip ---
  prospero is the hostname of the server in this example

* start the required daemons on the server:

    /usr/sbin/rpc.bootparamd
    /usr/sbin/rarpd -a

  and bootpd - either by uncommenting the entry in /etc/inetd.conf and
  sending inetd an HUP signal like above or by starting it explicitly

    /usr/sbin/bootpd

* now you should be able to boot the pmax using:

    >> boot -f tftp()/bsd_nfs

  for 2100/3100 systems or

    >> boot 6/tftp

  for a 5000/200 - look into the manual of your pmax for details how
  to boot via tftp

If you plan to use OpenBSD/pmax on a diskless system in the future -
keep in mind that the Decstations can only boot ecoff format kernels
via net - so you have to convert them explicitly after the kernel
compilation to ecoff - therefor in the kernel compile dir you can do
the following after the kernel compile has finished

  elf2ecoff bsd.elf bsd.ecoff

then you can use the bsd.ecoff for netbooting - as a starting point for
the kernel config file you may choose GENERIC_NFS.

After you have set up everything correctly you can boot your system
over the network into singleuser mode and continue the installation.


Continuing the installation from single user mode

If you have reached single user mode either via booting the
simpleroot image or via booting over the network you will have to
relabel/label your disk and put filesystems on the partitions.

So here's what you have to do after going into single user mode:

- simpleroot image (assuming you have the simpleroot on rz0 and want
  to install on that disk too - everything behind the ";" is comment)

	# fsck /dev/rrz0a		; check the filesystem
	# mount /dev/rz0a /		; mount / read write
	# mount -t kernfs /kern /kern
	# ./install

- network boot

	# mount -t kernfs /kern /kern
	# ./install

This script should bring you to a completely installed OpenBSD/pmax
system (in theory :-) - if you should run into any problems while
installing - please first look at

  http://www.OpenBSD.org/pmax.html

I'll try to collect there any hints, fixes and so on. If your problem
can't be solved that way just send me a mail to graichen@OpenBSD.org
and I'll try to help you fixing it.

If you should somehow fail using the install script and want to
restart - you may have to umount any filesystems mounted while running
the install script (so all except /) and clean /tmp using:

  rm /tmp/.??* /tmp/??*

then it should be possible to rerun it again.

Now some more notes about labeling the disk - which you will have to
do in the process of running the install script.

Here follows an example of what you'll see while in the disklabel editor.
Do not touch any of the parameters except for the `label: ' entry and
the actual partition size information at the bottom (the lines starting
with `a:', `b:', ...).

If you are using the simpleroot image and want to install onto the
same disk you put the simpleroot on you'll also have to change the
sector, track, cylinder, etc. entries to match the values for your
disk. The Problem is to get those values for your disk :-) - you can
either look into the /etc/disktab file for an matching entry or boot
another verbose system like OpenBSD/i386 with your disk attached an
see what it prints out about the geometry of the disk. Also you can
get the total size of your disk from the bootup output of the
Decstation - look for lines like:

rz0 at sii0 drive 0 slave 0 SEAGATE ST1480 rev 7336, 832527 512 byte blocks

here 832527 is the number of total sectors on that disk.

The size and offset fields are given in sector units. Partitions on
which you intend to have a mountable filesystem, should be given
fstype `4.2BSD'. Remember, the `c' partition should describe the whole
disk. The `(Cyl. x - y)' info that appears after the hash (`#')
character is treated as a comment and need not be filled in when
altering partitions.

Special note: the line containing `8 partitions:' is best left alone,
even if you {:-define-:} less then eight partitions. If this line displays
a different number and the program complains about it (after you leave
the editor), then try setting it to `8 partitions:'.

Ok - now lets see how the default disklabel of the simpleroot image
looks like:

<BEGIN SAMPLE DISKLABEL SCREEN>
OpenBSD# disklabel rz0
 # /dev/rrz0c:
type: SCSI
disk: simpleroot
label: 
flags:
bytes/sector: 512
sectors/track: 32
tracks/cylinder: 64
sectors/cylinder: 2048
cylinders: 96
total sectors: 196608
rpm: 3600
interleave: 1
trackskew: 0
cylinderskew: 0
headswitch: 0           # milliseconds
track-to-track seek: 0  # milliseconds
drivedata: 0 

8 partitions:
#        size   offset    fstype   [fsize bsize   cpg]
  a:    65536        0    4.2BSD     1024  8192    16   # (Cyl.   0 - 32*)
  b:   131072    65536      swap                        # (Cyl.  32*- 96*)
  c:   196608        0    unused     1024  8192         # (Cyl.   0 - 96*)
<END SAMPLE DISKLABEL SCREEN>

ok - and now let's see how it looks like if it is adapted for the rz0
disk above (SEAGATE ST1480).

<BEGIN SAMPLE DISKLABEL SCREEN>
OpenBSD# disklabel rz0
 # /dev/rrz0c:
type: SCSI
disk: SEAGATE ST1480 r
label: 
flags:
bytes/sector: 512
sectors/track: 63
tracks/cylinder: 11
sectors/cylinder: 693
cylinders: 832527
total sectors: 832527
rpm: 3600
interleave: 1
trackskew: 0
cylinderskew: 0
headswitch: 0           # milliseconds
track-to-track seek: 0  # milliseconds
drivedata: 0 

8 partitions:
#        size   offset    fstype   [fsize bsize   cpg]
  a:    65536        0    4.2BSD     1024  8192    16   # (Cyl.   0 - 94*)
  b:   131072    65536      swap                        # (Cyl.  94*- 283*)
  c:   832527        0    unused     1024  8192         # (Cyl.   0 - 1201*)
  d:   635919   196608    4.2BSD     1024  8192    16   # (Cyl. 283*- 1201*)
<END SAMPLE DISKLABEL SCREEN>

I hope you got the idea now - maybe it'll take some experiments until
you get it right :-). One thing to note here is that you can't change
the a and b partitions if you are relabeling the disk you are running
the simpleroot on - you'll have to accept the simpleroot values here
for those 2 partitions.

Note: if you have finished the disklabeling and exited the editor for
editing the label in the process of the installation and if you then
get a message like: "no disklabel on disk - use the -r option to write
one" you should ignore it and answer no to the question if you want to
re-edit the disklabel - this is due to a problem with the pmax
disklabel code and it should be worked around by the install script.

So what does the install script explicitly do ?

These script will do most of the work of transferring the system from the
tar files onto your disk. You will frequently be asked for confirmation
before the script proceeds with each phase of the installation process.
Occasionally, you'll have to provide a piece of information such as the
name of the disk you want to install on or IP addresses and domain names
you want to assign.

The installation script goes through the following phases:

	- determination of the disk to install OpenBSD on
	- checking of the partition information on the disk
	- creating and mounting the OpenBSD filesystems
	- setup of IP configuration
	- extraction of the distribution tar files
	- installation of boot programs

If the installation worked fine we can go on.

Now try a reboot.  (If needed, swap your scsi id's first).  Initially
I'd suggest you "boot" (Decstation 2100/3100) or "boot/rz0a/bsd", then
try multiuser after that. if you boot single-user the OpenBSD
incarnation to make the root filesystem writable is

    OpenBSD# fsck -p
    OpenBSD# mount -u /dev/rz0a /

assuming your rootdisk is rz0.

OpenBSDCongratulations