.\"	$NetBSD: boot.8,v 1.10 2017/07/03 21:31:00 wiz Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software written and contributed
.\" to Berkeley by William Jolitz.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)boot_i386.8	8.2 (Berkeley) 4/19/94
.\"
.Dd August 16, 2014
.Dt BOOT 8 cobalt
.Os
.Sh NAME
.Nm boot
.Nd system bootstrapping procedures
.Sh DESCRIPTION
.Tn Cobalt
Networks' MIPS-based Microservers
.Po
now known as
.Tn Sun
Server Appliances
.Pc
that can run
.Nx Ns /cobalt
can use any of the following boot procedures:
.Pp
.Bl -bullet
.It
bootstrap
.Nx
from disk using the standard
.Tn Cobalt
.Tn Firmware
boot sequence
.It
bootstrap
.Nx
from disk using the
.Nx
boot loader
.It
network bootstrap
.Nx
using the standard
.Tn Cobalt
.Tn Firmware
means from a
.Tn TCP/IP
.Tn LAN
with
.Tn DHCP
and
.Tn NFS .
.It
network bootstrap
.Nx
using the
.Nx
boot loader which can be loaded by the standard Cobalt Firmware
with DHCP and NFS.
.El
.Ss Power fail and crash recovery
Normally, the system will reboot itself at power-up or after crashes.
An automatic consistency check of the file systems will be performed,
and unless this fails, the system will resume multi-user operations.
.Ss Cobalt Boot Sequence
The first program to take a control after reboot or at power-on is the
.Tn Cobalt
.Tn Firmware .
The
.Tn Firmware
can load a compressed kernel from disk, subject to a few limitations.
The
.Tn Firmware
expects the disk to contain DOS-style partition information with
the first partition being a boot one which is special in that it
should reside close to the beginning of the disk and must contain
an
.Tn ext2
file system with a
.Pa boot
directory which is treated specially by the
.Tn Firmware .
The default sequence is pretty straightforward, the
.Tn Firmware
finds the boot partition, mounts the Ext2 file system from it and
tries to load a compressed kernel image from the
.Pa boot
directory.
The name of the kernel image differs from machine to machine and
this is the reason for having multiple copies of
.Nx
kernel installed under different names.
The following kernel image names are known to be in use by certain
.Tn Cobalt
flavors:
.Bd -unfilled -offset indent
.Pa /boot/vmlinuz.gz
.Pa /boot/vmlinux.gz
.Pa /boot/vmlinux-nfsroot.gz
.Pa /boot/vmlinux_RAQ.gz
.Pa /boot/vmlinux_raq-2800.gz
.Ed
.Pp
where
.Pa /boot
is the directory on the boot partition.
.Pp
The
.Tn Firmware
console provides the means to alter the default boot sequence and/or
to specify boot parameters.
Pressing
.Sq Aq space
right after the
.Tn Firmware
printed its greeting brings the
.Tn Firmware
console prompt and pressing
.Sq \&?
at the prompt prints a help screen with all commands supported by
the
.Tn Firmware .
For example, the
.Sq bfd
command can be used to boot a kernel image:
.Bd -unfilled -offset indent
Cobalt: bfd /boot/<kernel image> [options]
.Ed
.Pp
where
.Dq options
are the kernel options.
.Ss Bootstrap from disk using the standard Firmware sequence
The
.Tn Firmware
enters the standard boot sequence after reboot or at power-on when
no front-panel buttons are pressed and the
.Tn Firmware
console is not used to change the boot procedure.
At boot time, the
.Tn Firmware
checks the hardware, prints the banner and performs the standard
.Tn Cobalt
boot sequence.
There are a few culprits tightly connected to this boot method.
First of all, the kernel must be compressed.
Second, the
.Tn Firmware
enforces a hard restriction on the kernel size
.Po
it cannot exceed approximately 900,000/2,500,000 bytes
compressed/uncompressed
.Pc
resulting in a lock-up should this requirement not be fulfilled.
For
.Nx ,
another pitfall is that the uncompressed kernel should be copied to
the root directory to make certain system binaries
.Po
such as e.g. netstat
.Pc
work, and the kernel images in the
.Pa boot
directory should always be in sync with the ones installed in the
root directory.
.Ss Bootstrap from disk using the NetBSD boot loader
The
.Nx
boot loader is an attempt to break through the limitations enforced
by the
.Tn Firmware
loader.
The main idea is to make the
.Tn Firmware
load the
.Nx
boot loader and let the latter take care of loading the kernel.
To achieve this goal, multiple copies of the boot loader are
installed in the
.Pa boot
directory on the boot partition, one copy per each kernel image
name the
.Tn Cobalt
.Tn Firmware
might look for.
The
.Nx
kernel is located in the root directory
.Po
usually
.Pa /dev/wd0a
.Pc
like it is on other platforms.
Once running, the boot loader prints a banner to the serial console
similar to the following:
.Bd -unfilled -offset indent
>> NetBSD/cobalt 5.0 Bootloader, Revision 0.9 [@0x80f00000]
>> (user@buildhost, builddate)
>> Model:               Cobalt Qube 2
>> Memory:              32768 k
>> PROM boot string:    root=/dev/hda1 ro
Boot [wd0a:netbsd]: 
Loading: wd0a:netbsd
3763776+312244 [216944+209676]=0x44b97c
Starting at 0x80001000
.Ed
.Pp
The boot loader also prints a banner to the LCD panels as the following:
.Bd -unfilled -offset indent
.Nx Ns /cobalt
Bootloader
.Pp
Loading:
wd0a:netbsd
.Ed
.Ss Boot loader Options
It is possible to specify some options and boot devices on the boot loader
prompt:
.Pp
.Xo No boot [wd0a:netbsd]:
.Op Va device : Ns
.Op Va filename
.Op Fl acdmqsvxz
.Xc
.Pp
The default
.Va device 
will be set to the disk that the boot loader was loaded from.
To boot from an alternate disk or partition, the full name of the device should
be given at the prompt.
.Va device
is of the form
.Va xdNx
where
.Va xd
is the device from which to boot,
.Va N
is the unit number, and
.Va x
is the partition letter of the NetBSD
.Xr disklabel 5
in the NetBSD partition of the MBR partitions.
The
.Nx
boot loader recognizes FFS (both UFS1 and UFS2) and Linux Ext2fs.
.Pp
The following list of supported devices may vary from installation to
installation:
.Pp
.Bl -hang -compact
.It wd
IDE hard disks recognized by the
.Tn Firmware .
.El
.Pp
The default
.Va filename
is
.Pa netbsd ;
if the boot loader fails to successfully
open that image, it then tries
.Pa netbsd.gz
(expected to be a kernel image compressed by
.Xr gzip 1 ) ,
followed by
.Pa netbsd ,
.Pa netbsd.gz ,
.Pa onetbsd ,
.Pa onetbsd.gz ,
.Pa netbsd.bak ,
.Pa netbsd.bak.gz ,
.Pa netbsd.old ,
.Pa netbsd.old.gz ,
.Pa netbsd.cobalt ,
.Pa netbsd.cobalt.gz ,
.Pa netbsd.elf ,
and finally
.Pa netbsd.elf.gz .
Alternate system images can be loaded by just specifying the name
of the image, so it is always a good idea to have a copy of working kernel
in the
.Nx
root partition before trying a new kernel.
.Pp
Options are:
.Bl -tag -width xxx
.It Fl a
Prompt for the root file system device, the system crash dump
device, and the path to
.Xr init 8 .
.It Fl c
Bring the system up into the device configuration manager.
From here the device locators can be tuned to the hardware; see
.Xr userconf 4 .
.It Fl d
Bring the system up in debug mode.
Here it waits for a kernel debugger connect; see
.Xr ddb 4 .
.It Fl q
Boot the system in quiet mode.
.It Fl s
Bring the system up in single-user mode.
.It Fl v
Boot the system in verbose mode.
.El
.Pp
As the older version of the boot loader, it is also possible to specify
options to the boot loader by breaking into the
.Tn Firmware
and using the
.Dq bfd
command:
.Bd -unfilled -offset indent
Cobalt: bfd /boot/boot.gz [options]
.Ed
.Pp
The boot loader allows the following options:
.Bl -tag -width 04n -offset 04n
.It Ic nbsd= Oo Va device : Oc Ns Oo Va filename Oc Oo Fl acdqsv Oc
.Pp
The device, filename and options on the bfd prompt are same with the boot
loader.
.El
.Pp
It is also a good idea to have a small rescue kernel in the
.Pa boot
directory in the Ext2 partition for the Firmware boot.
In an emergency case, this will allow you to use the
.Tn Firmware
.Sq bfd
command to boot the rescue image:
.Bd -unfilled -offset indent
Cobalt: bfd /boot/netbsd.gz
.Ed
.Ss Network bootstrap using the standard Firmware sequence
The
.Tn Cobalt
.Tn Firmware
allows to boot a kernel over the network, with all the limitations
of the
.Tn Firmware
loader described above.
The simplest method is to break into the
.Tn Firmware
prompt and use
.Dq bfd
command to specify where to boot from:
.Bd -unfilled -offset indent
Cobalt: bfd /netbsd.gz nfsroot=/home/raq/root
.Ed
.Pp
The
.Tn Firmware
is picky about syntax and in general, so if things fail mysteriously,
try to conform to the conventions described above.
For netbooting, you need to NFS-export the directory given to
.Dq nfsroot= ,
and the named kernel
.Pq Pa netbsd.gz
needs to be executable and in that directory.
You will also need to setup
.Xr dhcpd 8 .
Once the kernel is loaded with the command line values, the data
given via DHCP is used to mount the root file system.
Here is a known working DHCP entry:
.Bd -unfilled -offset indent
host raq {
        hardware ethernet 0:10:e0:0:52:62;      # raq MAC
        fixed-address 10.0.0.15;                # raq address
        filename "/netbsd.gz";                  # kernel name in root-path
        option root-path "/home/raq/root";      # absolute dir on NFS server
        server-name="10.0.0.3";                 # IP of NFS server
}
.Ed
.Pp
Another option is to hold down the left and right cursor buttons
during power-on which executes the command
.Bd -unfilled -offset indent
bfd /boot/vmlinux.gz root=/dev/nfs nfsroot=/nfsroot,
.Ed
.Pp
resulting in a netboot.
On RaQ 1's, the default kernel name is
.Pa vmlinux_RAQ.gz
and on RaQ 2's, it is
.Pa vmlinux_raq-2800.gz .
.Ss Network bootstrap using the NetBSD boot loader
The idea here is the same with the bootstrap from disk using the NetBSD
boot loader.
Make the firmware load the NetBSD boot loader via network and
let the latter take care of loading the kernel even via network.
A simple method to load the NetBSD boot loader is to use  the
.Dq bfd
command as well as booting the NetBSD kernel via network as described above:
.Bd -unfilled -offset indent
Cobalt: bfd /boot/boot.gz nfsroot=/home/raq/root
.Ed
.Pp
Note the boot loader binary needs to be
.Xr gzip 1 Ns -compressed .
Once the boot loader is successfully loaded it prints a banner as well as
booting from disk:
.Bd -unfilled -offset indent
>> NetBSD/cobalt 5.0 Bootloader, Revision 0.9 [@0x80f00000]
>> (user@buildhost, builddate)
>> Model:               Cobalt Qube 2
>> Memory:              32768 k
>> PROM boot string:    root=/dev/nfs nfsroot=/nfsroot nfsaddrs=bootp
Boot [nfs:netbsd]: 
Loading: nfs:netbsd
3763776+312244 [216944+209676]=0x44b97c
Starting at 0x80001000
.Ed
.Pp
The boot loader load the NetBSD kernel via NFS which should be specified
by the DHCP configuration on the server.
Note the nfsroot option specified on the
.Dq bfd
prompt will be ignored by the
.Nx
boot loader so it's recommended to use the same directory on the
.Dq bfd
prompt and in the DHCP configuration.
.Sh FILES
.Bl -tag -width /usr/mdec/bootxx_fstype -compact
.It Pa /boot/boot.gz
boot program code loaded by the
.Tn Firmware
loader
.It Pa /boot/netbsd.gz
.Xr gzip 1 Ns -compressed
rescue system code
.It Pa /netbsd
system code
.It Pa /netbsd.gz
.Xr gzip 1 Ns -compressed
system code
.It Pa /usr/mdec/boot
master copy of the boot program (to be compressed and copied to /boot/boot.gz)
.El
.Sh SEE ALSO
.Xr ddb 4 ,
.Xr userconf 4 ,
.Xr dhcpd.conf 5 ,
.Xr dhcpd 8 ,
.Xr fdisk 8 ,
.Xr halt 8 ,
.Xr reboot 8 ,
.Xr shutdown 8 ,
.Xr printf 9
.Pp
.Lk http://www.NetBSD.org/docs/network/netboot/