boot(8)
- NetBSD Manual Pages
BOOT(8) NetBSD/x86 System Manager's Manual BOOT(8)
NAME
boot -- system bootstrapping procedures
DESCRIPTION
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.
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 boot-
blocks 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 exam-
ple above, it will be ``hd0a:netbsd'' which is the file /netbsd on parti-
tion ``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 mes-
sages 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 from which the boot
loader was loaded. The partition is set to the first match in
this list:
1. The first gpt(8) partition with the bootme attribute set.
2. The partition from which the boot loader was loaded from,
if that can be detected.
3. The first partition with a file system that could be
bootable.
4. 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 parti-
tion letter.
In the latter 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 looka-
like 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 boot-
strap code. If the RAID is partitioned, the first par-
tition 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 sys-
tem crash dump device, and the path to init(8).
-b Sets the RB_HALT flag in boothowto. This causes subse-
quent 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 man-
ager 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 num-
bers) 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 ker-
nel 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[,speed]
[Not available for x86/dosboot(8)] Immediately switch the con-
sole 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).
A speed for the serial port is optional and defaults to 9600.
If a value of zero is specified, then the current baud rate
(set by the BIOS) will be used. Setting the speed with the pc
device is not possible.
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.
devpath
[Only available for UEFI boot] Dump UEFI device paths.
efivar
[Only available for UEFI boot] Dump UEFI environment variables
from NVRAM.
fs file
[Only available for BIOS and UEFI boot] 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.
gop [mode_index]
[Only available for UEFI boot] Without argument, list the
available video modes. If an argument is given, select a video
mode.
help Print an overview about commands and arguments.
load module [arguments]
[Not available for x86/dosboot(8)] 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) partitioned 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]
[Not available for x86/pxeboot(8)] Print a directory listing of
path, containing inode number, filename, and file type. path
can contain a device specification.
memmap
[Only available for UEFI boot] Dump UEFI memory map.
menu [Only available for BIOS and UEFI boot] 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}
[Not available for x86/dosboot(8)] The values `enabled', `on'
will enable module loading for boot and multiboot, whereas
`disabled', `off' will turn off the feature.
mode fstype
[Only available for x86/dosboot(8)] Switch file system type;
fstype should be one of dos or ufs.
multiboot kernel [arguments]
[Not available for x86/dosboot(8)] 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 ker-
nel (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 256MB
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.
pkboot
[Only available for BIOS and UEFI boot] Boot a kernel that has
the KASLR option set, for Kernel Address Space Layout Random-
izaton.
quit Reboot the system.
reloc [default | none | address]
[Only UEFI boot] Sets where the kernel is copied by bootstrap
before it is started. Values other than default require a ker-
nel built with the SELFRELOC option, so that can relocate
itself at the right address, otherwise a crash occurs at boot
time.
default Copy the kernel at ELF header load address, this is
the historical behavior.
none Leave the kernel where it was loaded and start it as
is.
address Copy the kernel at given address.
rndseed file
[Only available for BIOS and UEFI boot] Load the specified file
and request the kernel to use it as a seed for the rnd(4) ran-
dom 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.
root spec
[Only available for BIOS and UEFI boot] Pass an explicit root
specification to the kernel. See BTINFO_ROOTDEVICE for
details.
splash file
[Only available for BIOS and UEFI boot] 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 (compos-
ited view only), or PIC.
text [mode_index]
[Only available UEFI boot] Without argument, list the available
text modes (displayed as column x line in hexadecimal, there-
fore 50x19 means 80 columns and 25 lines). With an argument,
select a text mode.
userconf command
[Not available for x86/dosboot(8)] Pass command command to
userconf(4) at boot time. These commands are processed before
the interactive userconf(4) shell is executed, if requested.
version [full]
[Only available UEFI boot] Display UEFI bootstrap version. With
the [full] argumznt, also display information about UEFI
itself.
vesa {modenum | on | off | enabled | disabled | list}
[Only available for BIOS and x86/pxeboot(8)] 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 installa-
tion 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.
If the bootloader passes a wedge name as ``wedge:'' or
``NAME='' 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 match-
ing wedge.
BTINFO_BOOTDISK determined by bootblock
This uses the device number passed by the BIOS that distin-
guishes 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 num-
ber.
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 boot-
strap
/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 x86/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.
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.:
boot -d netbsd.test
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 distinc-
tion between ``sd'' and ``wd'' devices at the bootloader level. This is
less a bug of the bootloader code than a shortcoming of the PC architec-
ture. 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 implementations are supposed to support either x86/mbr(8) or gpt(8)
partitioning, but some do not handle the latter. UEFI booting from a
gpt(8) partitioned disk is still possible in this case, by adding an
overlapping EFI partition in the protective x86/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 x86/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>
NetBSD 10.99 July 15, 2020 NetBSD 10.99
Powered by man-cgi (2021-06-01).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.