boot
—
system bootstrapping procedures
Intel Architecture, 32-bit (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
- efiboot
- bootstrap NetBSD from the system UEFI
- x86/dosboot(8)
- bootstrap NetBSD from MS-DOS
- x86/pxeboot(8)
- network bootstrap NetBSD from a TCP/IP LAN with
DHCP, TFTP, and NFS.
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.
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)).
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).
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.
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.
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 from
which the boot loader was loaded. The partition is set to the first match
in this list:
- The first gpt(8)
partition with the bootme attribute set.
- The partition from which the boot loader was loaded from, if that can
be detected.
- The first partition with a file system that could be bootable.
- The first partition.
To boot from an alternate disk, the full name of the device should be given
at the prompt. device is of the form
NAME=partition_label when booting from a
gpt(8) partitioned disk.
Otherwise, the syntax is xd
[N[x]] where
xd is the device from which to boot,
N is the unit number, and x is
the partition letter.
In the later case, 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.
- cd
- CD-ROM drives as numbered by the BIOS.
- raid
- RAIDframe configured from hard disks recognized by the BIOS. Only RAID
level 1 sets are supported by bootstrap code. If the RAID is
partitioned, the first partition is used, or the first
gpt(8) partition that
has the bootme attribute set. Inner RAIDframe
partitions can also be given to the
dev
command using he NAME=partition_label
syntax.
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
onetbsd, onetbsd.gz,
netbsd.old, and finally
netbsd.old.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/amd64, this disables SVS.
-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 is of the
form NAME=partition_label for
gpt(8) partitionned
disks. It can also 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.
- 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.
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.
- /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).
- /usr/mdec/bootia32.efi
-
- /usr/mdec/bootx64.efi
- UEFI bootstraps for NetBSD/i386 and
NetBSD/amd64, which should be copied to the
/efi/boot directory in a FAT formatted partition
of type EFI (Either mbr(8)
and gpt(8), see the
BUGS section).
NetBSD UEFI bootstrap reads its configuration from
the /efi/netBSD/boot.cfg file in the EFI
partition.
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)
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).
UEFI implementation are supposed to support either
mbr(8) or
gpt(8) partitionning, but some
do not handle the later. UEFI Booting from a
gpt(8) partitioned disk is
still possible in this case, by adding an overlapping EFI partition in the
protective mbr(8) block. This
can be achieved using the following commands (you must adapt the hard disk
and EFI partition start end size to fit your setup):
dd if=/dev/rwd0d
bs=512 count=1 of=mbr
fdisk -FIfaui1s
4/34/32768 -c /usr/mdec/mbr mbr
dd if=mbr bs=512
count=1 of=/dev/rwd0d conv=notrunc
The resulting mbr(8) partition
table will look like this:
0: GPT Protective MBR (sysid 238)
start 1, size 2097151 (1024 MB, Cyls 0-130/138/8)
PBR is not bootable: Bad magic number (0x0000)
1: Primary DOS with 16 bit FAT <32M (sysid 4)
start 34, size 32768 (16 MB, Cyls 0/0/35-2/10/42), Active
2: <UNUSED>
3: <UNUSED>