BOOT(8) (x86)

BOOT(8) | System Manager's Manual (x86) | 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 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 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 partition 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 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[`,`speed]
  [Not available for x86/dosboot(8)] 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).

  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 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 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 Randomizaton.
`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 kernel 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) 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.
`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 (composited 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, therefore `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 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.

  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 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).
/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 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 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>

July 15, 2020 | NetBSD 9.4