NAME
boot —
system bootstrapping
procedures
DESCRIPTION
IA-32 computers (the IBM PC and its clones) that can run
NetBSD/i386 or
NetBSD/amd64
can use any of the following boot procedures, depending on what the hardware
and BIOS support:
-
-
- boot
- bootstrap NetBSD from the system
BIOS
-
-
- x86/dosboot(8)
- bootstrap NetBSD from MS-DOS
-
-
- x86/pxeboot(8)
- network bootstrap NetBSD from a
TCP/IP LAN with DHCP, TFTP, and NFS.
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.
Cold starts
The 386 PC AT clones attempt to boot the floppy disk drive A (otherwise known as
drive 0) first, and failing that, attempt to boot the hard disk C (otherwise
known as hard disk controller 1, drive 0). The
NetBSD
bootblocks are loaded and started either by the BIOS, or by a boot selector
program (such as OS-BS, BOOTEASY, the OS/2 Boot Menu or
NetBSD's
boot-selecting master
boot record - see
x86/mbr(8)).
Normal Operation
Once running, a banner similar to the following will appear:
>> NetBSD BIOS Boot, revision 3.0
>> (user@buildhost, builddate)
>> Memory: 637/15360 k
Press return to boot now, any other key for boot menu
booting hd0a:netbsd - starting in 5
After a countdown, the system image listed will be loaded. In the example above,
it will be “
hd0a:netbsd
” which is the file
/netbsd on partition “a” of the
NetBSD MBR partition of the first hard disk known to
the BIOS (which is an IDE or similar device - see the
BUGS section).
Pressing a key within the time limit, or before the boot program starts, will
enter interactive mode. When using a short or 0 timeout, it is often useful to
interrupt the boot by holding down a shift key, as some BIOSes and BIOS
extensions will drain the keystroke buffer at various points during POST.
If present, the file
/boot.cfg will be used to configure the
behaviour of the boot loader including setting the timeout, choosing a console
device, altering the banner text and displaying a menu allowing boot commands
to be easily chosen. See
boot.cfg(5).
Boot Protocol
The
NetBSD/x86 boot loader can boot a kernel using
either the native
NetBSD boot protocol, or the
“multiboot” protocol (which is compatible with some other
operating systems). In the native
NetBSD boot
protocol, options are passed from the boot loader to the kernel via flag bits
in the
boothowto variable (see
boothowto(9)). In the
multiboot protocol, options are passed from the boot loader to the kernel as
strings.
Diagnostic Output
If the first stage boot fails to load the boot, it will print a terse message
indicating the reason for the failure. The possible error messages and their
cause are listed in
x86/mbr(8).
If the first stage boot succeeds, the banner will be shown and the error
messages should be self-explanatory.
Interactive mode
In interactive mode, the boot loader will present a prompt, allowing input of
these commands:
-
-
- boot
[device:][filename]
[-1234abcdmqsvxz]
- The default device will be set to the
disk that the boot loader was loaded from. To boot from an alternate disk,
the full name of the device should be given at the prompt.
device is of the form xd
[N[x]]
where xd is the device from which to boot,
N is the unit number, and x is
the partition letter.
The following list of supported devices may vary from installation to
installation:
- hd
- Hard disks as numbered by the BIOS. This includes
ST506, IDE, ESDI, RLL disks on a WD100[2367] or lookalike
controller(s), and SCSI disks on SCSI controllers recognized by the
BIOS.
- fd
- Floppy drives as numbered by the BIOS.
The default filename is netbsd; if
the boot loader fails to successfully open that image, it then tries
netbsd.gz (expected to be a kernel image compressed by
gzip), followed by netbsd.old,
netbsd.old.gz, onetbsd, and finally
onetbsd.gz. Alternate system images can be loaded by
just specifying the name of the image.
Options are:
-
-
- -1
- Sets the machine-dependent flag
RB_MD1 in boothowto. In
NetBSD/x86, this disables multiprocessor boot;
the kernel will boot in uniprocessor mode.
-
-
- -2
- Sets the machine-dependent flag
RB_MD2 in boothowto. In
NetBSD/x86, this disables ACPI.
-
-
- -3
- Sets the machine-dependent flag
RB_MD3 in boothowto. In
NetBSD/x86, this has no effect.
-
-
- -4
- Sets the machine-dependent flag
RB_MD4 in boothowto. In
NetBSD/x86, this has no effect.
-
-
- -a
- Sets the RB_ASKNAME flag in
boothowto. This causes the kernel to prompt for
the root file system device, the system crash dump device, and the
path to init(8).
-
-
- -b
- Sets the RB_HALT flag in
boothowto. This causes subsequent reboot
attempts to halt instead of rebooting.
-
-
- -c
- Sets the RB_USERCONF flag in
boothowto. This causes the kernel to enter the
userconf(4) device
configuration manager as soon as possible during the boot.
userconf(4) allows
devices to be enabled or disabled, and allows device locators (such as
hardware addresses or bus numbers) to be modified before the kernel
attempts to attach the devices.
-
-
- -d
- Sets the RB_KDB flag in
boothowto. Requests the kernel to enter debug
mode, in which it waits for a connection from a kernel debugger; see
ddb(4).
-
-
- -m
- Sets the RB_MINIROOT flag in
boothowto. Informs the kernel that a mini-root
file system is present in memory.
-
-
- -q
- Sets the AB_QUIET flag in
boothowto. Boot the system in quiet mode.
-
-
- -s
- Sets the RB_SINGLE flag in
boothowto. Boot the system in single-user
mode.
-
-
- -v
- Sets the AB_VERBOSE flag in
boothowto. Boot the system in verbose mode.
-
-
- -x
- Sets the AB_DEBUG flag in
boothowto. Boot the system with debug messages
enabled.
-
-
- -z
- Sets the AB_SILENT flag in
boothowto. Boot the system in silent mode.
-
-
- consdev
dev
- Immediately switch the console to the specified device
dev and reprint the banner.
dev must be one of pc,
com0, com1,
com2, com3,
com0kbd, com1kbd,
com2kbd, com3kbd, or
auto. See
Console Selection
Policy in
x86/boot_console(8).
-
-
- dev
[device]
- Set the default drive and partition for subsequent file
system operations. Without an argument, print the current setting.
device is of the form specified in
boot.
-
-
- fs
file
- Load a file system image from the specified
file, and request the kernel to use it as the root
file system. The
makefs(8) utility may be
used to create suitable file system images.
-
-
- help
- Print an overview about commands and arguments.
-
-
- load
module
[arguments]
- Load the specified kernel module, and
pass it the specified arguments. If the module name
is not an absolute path,
/stand/⟨arch⟩/⟨osversion⟩/modules/⟨module⟩/⟨module⟩.kmod
is used. Possible uses of the load command include
loading a memory disk image before booting a kernel, or loading a Xen DOM0
kernel before booting the Xen hypervisor. See
boot.cfg(5) for
examples.
In addition to the boot options specified above, the Xen
DOM0 kernel accepts (arguments being separated with
spaces):
-
-
- bootdev=dev
(or root=dev)
- Override the default boot device.
dev can be a unit name (“wd0”), or
an interface name (“bge0”, “wm0”, ...) for
cases where the root file system has to be loaded from network (see
the BUGS section in
x86/pxeboot(8)).
-
-
- console=dev
- Console used by DOM0 kernel during boot.
dev accepts the same values as the ones given
for the consdev command. See
Console Selection
Policy in
x86/boot_console(8).
-
-
- ip=my_ip:serv_ip:gw_ip:mask:host:iface
- Specify various parameters for a network boot (IPs are
in dot notation), each one separated by a colon:
-
-
- my_ip
- address of the host
-
-
- serv_ip
- address of the NFS server
-
-
- gw_ip
- address of the gateway
-
-
- mask
- network mask
-
-
- host
- address of the host
-
-
- iface
- interface (e.g., “xennet0” or
“eth0”)
-
-
- nfsroot=address:rootpath
- Boot the system with root on NFS.
address is the address of the NFS server, and
rootpath is the remote mount point for the root
file system.
-
-
- pciback.hide=pcidevs
- Pass a list of PCI IDs for use with the PCI backend
driver, pciback(4).
pcidevs is formed of multiple IDs (in
bus:device.function notation), each ID being surrounded with brackets.
PCI domain IDs are currently ignored. See
pciback(4).
-
-
- ls
[path]
- Print a directory listing of path,
containing inode number, filename, and file type. path
can contain a device specification.
-
-
- menu
- Display the boot menu and initiate a countdown, similarly
to what would have happened if interactive mode had not been entered.
-
-
- modules
{on | off |
enabled | disabled}
- The values enabled,
on will enable module loading for
boot and multiboot, whereas
disabled, off will turn off
the feature.
-
-
- multiboot
kernel
[arguments]
- Boot the specified kernel, using the
“multiboot” protocol instead of the native
NetBSD boot protocol. The
kernel is specified in the same way as with the
boot command.
The multiboot protocol may be used in the following cases:
-
-
- NetBSD/Xen
kernels
- The Xen DOM0 kernel must be loaded as a module using
the load command, and the Xen hypervisor must be
booted using the multiboot command. Options for the
DOM0 kernel (such as “-s” for single user mode) must be
passed as options to the load command. Options for
the hypervisor (such as “dom0_mem=256M” to reserve 256 MB
of memory for DOM0) must be passed as options to the
multiboot command. See
boot.cfg(5) for
examples on how to boot NetBSD/Xen.
-
-
- NetBSD
multiboot kernels
- A NetBSD kernel that was built
with options MULTIBOOT (see
x86/multiboot(8))
may be booted with either the boot or
multiboot command, passing the same
arguments in either case.
-
-
- Non-NetBSD
kernels
- A kernel for a
non-NetBSD operating
system that expects to be booted using the multiboot protocol (such as
by the GNU “GRUB” boot loader) may be booted using the
multiboot command. See the foreign operating
system's documentation for the available
arguments.
-
-
- quit
- Reboot the system.
-
-
- rndseed
file
- Load the specified file and request
the kernel to use it as a seed for the
rnd(4) random number
generator. The file should be in the private format
used by rndctl(8), and
should have been saved by ‘
rndctl -S
’
shortly before the previous shutdown. See the
random_seed and random_file
variables in rc.conf(5),
and the /etc/rc.d/random_seed script, for a way to
manage the seed file. Using the same seed file on more then one host, or
for more than one boot on the same host, will reduce the quality of random
numbers and may impact system security.
-
-
- userconf
command
- Pass command command to
userconf(4) at boot
time. These commands are processed before the interactive
userconf(4) shell is
executed, if requested.
-
-
- splash
file
- Load a graphical image from the specified
file and request the kernel to use it as a splash
screen. The file should contain an image in one of
these formats: JPEG (baseline only, not progressive), PNG (8-bit only),
TGA, BMP (non-1bpp, non-RLE), GIF, PSD (composited view only), or
PIC.
-
-
- vesa
{modenum | on |
off | enabled |
disabled | list}
- Initialise the video card to the specified resolution and
bit depth. The modenum should be in the form of
0x100, 800x600,
800x600x32. The values
enabled, on put the display
into the default mode, and disabled,
off returns the display into standard vga mode. The
value list lists all supported modes.
In an emergency, the bootstrap methods described in the
NetBSD installation notes for the x86 architectures
can be used to boot from floppy or other media, or over the network.
Locating the root file
system
The kernel uses information from the bootloader to locate the file system to
mount as root. There are three methods:
-
-
- BTINFO_ROOTDEVICE
from
- boot.cfg(5)
or multiboot. The bootloader passes the root device name as driver, unit,
and partition (like sd0a). This will be automatically substituted by a
dk(4) wedge if one is
discovered.
The bootloader passes a wedge name as "wedge:" followed by the
name. The kernel will search for a
dk(4) device with that
name.
-
-
- BTINFO_BOOTWEDGE
determined by bootblock
- The bootloader passes start offset and length of a hard
disk partition and a offset, size and hash of a "boot area".
Then kernel searches all disks and wedges for a block sequence at that
offset with a matching hash. If one is found, the kernel will look for a
wedge on that device at the same offset.
An additional partition number is provided if the bootloader also passed a
BTINFO_BOOTDISK record. This (or partition 'a') will be used by the kernel
as a fallback if there is no matching wedge.
-
-
- BTINFO_BOOTDISK
determined by bootblock
- This uses the device number passed by the BIOS that
distinguishes between floppy, hard drive and CD-ROM boot.
-
-
- Floppy
- The kernel searches for the
fd(4) device with the
correct unit, the partition number is used to select a specific disk
format. See fd(4) for
details.
-
-
- Hard
drive
- The bootloader passed a partition number and disklabel
data (offset, type, checksum, packname). The kernel searches all disks
for a matching disklabel. If one is found, the kernel will use that
device and partition number.
-
-
- CDROM
- The BIOS does not distinguish between multiple CD
devices. The kernel searches for the first
cd(4) device. So you can
only boot from unit 0.
FILES
- /boot
- boot program code loaded by the primary bootstrap
- /boot.cfg
- optional configuration file
- /netbsd
- system code
- /netbsd.gz
- gzip-compressed system code
- /usr/mdec/boot
- master copy of the boot program (copy to /boot)
- /usr/mdec/bootxx_fstype
- primary bootstrap for file system type fstype, copied to
the start of the NetBSD partition by
installboot(8).
SEE ALSO
ddb(4),
fd(4),
pciback(4),
userconf(4),
boot.cfg(5),
halt(8),
installboot(8),
reboot(8),
rescue(8),
shutdown(8),
x86/boot_console(8),
x86/dosboot(8),
x86/mbr(8),
x86/multiboot(8),
x86/pxeboot(8),
boothowto(9)
BUGS
The kernel file name must be specified before, not after, the boot options. Any
filename specified after the boot options, e.g.:
is ignored, and the default kernel is booted.
Hard disks are always accessed by BIOS functions. Unit numbers are BIOS device
numbers which might differ from numbering in the
NetBSD kernel or physical parameters (e.g., SCSI slave
numbers). There isn't any distinction between “sd” and
“wd” devices at the bootloader level. This is less a bug of the
bootloader code than a shortcoming of the PC architecture. The default disk
device's name printed in the starting message is derived from the
“type” field of the
NetBSD disklabel (if
it is a hard disk).