The OpenBSD Boot Process

Synopsis #

The OpenBSD boot path moves through firmware, architecture-specific bootstrap code, the boot(8) loader where the platform provides it, the kernel, init(8) , and rc(8) . The exact bootstrap files, firmware interface, disk syntax, and recovery methods vary by architecture.

This chapter explains the responsibilities of each stage. Recover an OpenBSD System That Does Not Boot provides step-by-step recovery instructions.

Boot Stages #

The general sequence is:

1. Firmware initializes the platform and selects a boot device.
2. Platform bootstrap code loads the OpenBSD boot loader or kernel.
3. The boot loader reads /etc/boot.conf, accepts console commands, and loads a kernel where that loader is used.
4. The kernel discovers hardware, selects the root filesystem, and starts process 1.
5. init enters single-user mode when requested or starts /etc/rc for multi-user initialization.
6. /etc/rc checks filesystems, applies persistent system and network configuration, and starts enabled daemons.

A failure should be diagnosed at the first stage that did not complete. Rewriting boot blocks does not repair an invalid /etc/fstab, a damaged filesystem, or a failing daemon.

Firmware and Bootstrap Code #

Firmware can be BIOS, UEFI, Open Firmware, or another platform interface. It selects a device and transfers control to architecture-specific bootstrap code.

On amd64 with UEFI and a GPT disk, firmware normally loads the OpenBSD EFI program from the EFI System Partition. On legacy amd64 and i386 BIOS systems, primary bootstrap code loads the second-stage /boot program. Other architectures use different files and firmware commands.

installboot(8) installs the appropriate bootstrap for the running architecture. Its -n option performs a dry run, and -r selects an installed root mounted elsewhere. It should be used only after the boot disk and failing stage have been established.

The Boot Loader #

Where the platform uses the OpenBSD boot program, it normally loads /bsd after a timeout. The boot> prompt accepts an alternate image and supported kernel flags.

Boot the default kernel:

boot> boot

Boot the standalone installation and recovery kernel:

boot> boot /bsd.rd

Boot the default kernel in single-user mode:

boot> boot /bsd -s

Common supported flags include:

The available commands and device syntax are architecture-specific. For example, amd64 boot loaders can name a disk and partition as hd1d:/bsd.rd. Consult the matching platform boot(8) page before using such syntax.

/etc/boot.conf #

boot.conf(8) supplies commands to the boot loader. Keep it minimal because an invalid or unavailable console setting can complicate recovery.

One amd64 or i386 example sets a five-second timeout:

set timeout 5

Serial-console commands, device selection, and other machine commands depend on the platform. Test console access before making a persistent console change.

Kernel Initialization #

The kernel loaded from /bsd discovers devices, attaches drivers, configures kernel subsystems, identifies the root filesystem, and starts /sbin/init. The boot messages later remain available through dmesg(8) .

The root filesystem is mounted read-only initially. Failures at this stage commonly involve an unavailable disk, unassembled softraid volume, wrong root selection, unsupported hardware, or filesystem damage.

/bsd.rd is a standalone kernel with an installer and recovery environment. It can boot from the installed filesystem on supported loaders or from verified installation media.

Single-User Mode #

Single-user mode starts a root shell on the console with minimal services. Networking and ordinary daemons are not started automatically. Use it for authorized maintenance that requires local filesystems to be checked, repaired, or mounted deliberately.

After the required repairs, mount the filesystems described by a verified /etc/fstab and leave the shell to continue multi-user startup:

Run in the root shell:

mount -a
  # Mount filesystems from the verified fstab
exit
  # Continue to multi-user mode

If mount -a fails, correct the reported filesystem or fstab problem before continuing.

Multi-User Initialization #

For a normal multi-user boot, init runs /etc/rc. The startup sequence includes filesystem checks and mounts, entropy and system settings, interface configuration, PF, and enabled base and package daemons. Persistent settings come from files documented by rc.conf(8) , hostname.if(5) , sysctl.conf(5) , and related manuals.

Startup messages are displayed on the console. Kernel boot messages are saved in /var/run/dmesg.boot; that file does not contain daemon startup output. Enabled daemons that are not running can be listed with rcctl(8) :

doas rcctl ls failed

Scheduled daily, weekly, and monthly maintenance runs later through root’s cron configuration; it is not part of /etc/rc startup.

Alternate Kernels and Recovery #

Do not assume that /bsd.old, /bsd.sp, or another alternate image exists or is suitable. List the filesystem from the boot prompt or inspect it from recovery media first. /bsd.rd is the standard installed recovery image when present.

If a known alternate kernel exists, it can be named explicitly at the boot prompt. Booting an alternate kernel helps identify the problem. Repair the normal kernel or boot files and complete any interrupted upgrade before returning to regular use.

For a complete recovery procedure, including offline filesystem checks and dry-run boot-block installation, see Recover an OpenBSD System That Does Not Boot .

Key Files #

Platform manual pages and INSTALL.<arch> remain authoritative for bootstrap files and firmware commands.

Shutdown #

Use shutdown(8) for an orderly transition from multi-user mode:

doas shutdown -p now
  # Stop services and power off when the platform supports it
doas shutdown -r now
  # Stop services and reboot

The shutdown path gives services an opportunity to stop, runs the configured shutdown processing, flushes buffered data, and unmounts filesystems. Avoid power removal or reset while filesystems are writable.