.\"	$NetBSD: boot.8,v 1.15 2009/09/05 11:37:52 wiz Exp $
.\"
.\" Copyright (c) 1990, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Systems Programming Group of the University of Utah Computer
.\" Science Department.
.\"
.\" 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.
.\"
.Dd April 8, 2003
.Dt BOOT 8 pmax
.Os
.Sh NAME
.Nm boot
.Nd system bootstrapping procedures
.Sh DESCRIPTION
The
.Nx
kernel is started by placing it near the beginning of physical
memory and transferring to the entry point.
Since the system is not reenterable,
it is necessary to read it in from disk or tape
each time it is to be bootstrapped.
.Ss Power fail and crash recovery
Normally, the system will boot 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 Cold starts
At power up, all DECstation ROMs consult the
.Nm haltaction
environment
variable in EEPROM to determine whether or not to attempt to boot
automatically.
If this variable is set to
.Sq h ,
the ROM prints a prompt on the console and
waits for user commands.
If set to
.Sq b ,
the ROM attempts to autoboot.
.Sh DECSTATION 2100 and 3100
On the DECstation 2100 and 3100, the path used for automatic booting is
stored in the
.Nm bootpath
environment variable.
 The path is made up of a
device type specifier (e.g., rz, tz, mop or tftp) followed by
a triplet in the form (x,y,z), followed by a filename to load.
.Pp
Within the triplet, x is the controller (always 0), y is the SCSI id of
the drive to
boot from or 0 for net boots, and z is the partition to boot from
(usually 0 for SCSI devices, always zero for network booting).
For both disk and network boots, () may be specified instead of
(0,0,0).
.Pp
The filename is optional for bootp/tftp and mop booting, since in
these cases the network protocol can be used to determine which
file to boot.
When booting off the tape, no filename should be specified.
When booting off of disk, the filename is optional but is usually specified.
If no filename is specified when booting off disk, the following
filenames are tried in order:
.Nm netbsd.pmax ,
.Nm netbsd ,
.Nm netbsd.gz ,
.Nm netbsd.bak ,
.Nm netbsd.old ,
.Nm onetbsd ,
.Nm gennetbsd .
Generally, the kernel is named
.Nm netbsd .
.Pp
An example bootpath setting would be:
.Dl Ic setenv bootpath rz(0,1,0)netbsd
.Pp
At the PROM prompt, the user may boot
.Nx
with either the
.Nm auto
or the
.Nm boot
command.
If the
.Nm auto
command is used, the
.Fl a
argument is passed to the kernel, requesting a multi-user boot; otherwise
the
.Fl s
argument is passed, requesting that
.Nx
boot to single user mode.
.Pp
When either the
.Nm boot
or the
.Nm auto
command is issued with no arguments, the kernel specified in the bootpath
environment variable is booted.
With the
.Nm boot
command, an alternative kernel may be specified
with the
.Fl f
flag, followed by the path of the kernel to boot, as described above.
For example:
.Dl Ic boot -f rz(0,4,0)netbsd.new
.Sh TURBOCHANNEL DECstations
On TurboChannel machines (all DECstation 5000 models), the boot path
is specified in the boot environment variable, along with any arguments
to be passed to the kernel.
Note that to specify boot arguments (e.g.,
.Fl a )
when setting the
.Nm boot
environment variable, the filename and arguments
must be enclosed in quotes.
For example:
.Dl Ic setenv boot Dq Ic "3/rz4/netbsd -a"
.Pp
The device from which to boot is specified as the TurboChannel slot
number, a TurboChannel-option-specific device name, and a path to the
file to load, all separated by slashes.
You can get a list of the
devices installed in your TurboChannel slots (as well as any built-in
devices which appear as TurboChannel slots) by typing the
.Nm cnfg
command
at the boot prompt.
You can get more detailed information about a specific
TurboChannel option by typing
.Nm cnfg
followed by the slot number of that
option.
.Pp
For SCSI devices, the option-specific device identifier is either rz# for
disks or tz# for tapes, where # is the SCSI id of the device.
For network
devices, the option-specific protocol identifier is either mop or tftp.
Filename requirements are as for the DECstation 2100 and 3100.
.Pp
To start
.Nx
from the boot prompt, the
.Nm boot
command must be used.
With no arguments, this simply boots the default
kernel with the default arguments as set with
.Nm setenv
.Nm boot .
If no boot environment variable is set or if an alternative kernel is to be
booted, the path of that kernel may be specified after the boot command as
described above, and any arguments may be passed similarly.
For example:
.Dl Ic boot 3/rz4/netbsd.new -a
.Sh KERNEL ARGUMENTS
The kernel supports the following arguments:
.Bl -tag -width xxx -offset indent
.It Li a
Autoboot -- try and boot to multi-user mode without
further input.
.It Li m
Use a miniroot already present in memory.
.It Li n
Prompt for the root file system device, the system crash dump
device, and the path to
.Xr init 8 .
.It Li N
Do not prompt for the root file system device, the system crash dump
device, and the path to
.Xr init 8 .
If the configured-in devices are present, use them.
.It Li s
Boot only to single-user mode.
.El
.Pp
Since DECstation PROMs also parse any arguments with a leading
"-", and reject unrecognized options, arguments other than "a" or "s"
should be specified after the kernel name with no leading "-".
For example:
.Dl Ic boot 3/rz4/netbsd \&ns
.Sh SEE ALSO
.Xr ddb 4 ,
.Xr halt 8 ,
.Xr init 8 ,
.Xr installboot 8 ,
.Xr rc 8 ,
.Xr reboot 8 ,
.Xr savecore 8 ,
.Xr shutdown 8
.Sh HISTORY
The
.Nm
command is
.Ud