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 the operational recovery sequence.

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:

# 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.

The boot log is available at /var/run/rc.log. Enabled daemons that are not running can be listed with rcctl(8) :

# 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. A successful alternate-kernel boot is a diagnostic step; the normal kernel, boot files, and upgrade state still require reconciliation.

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:

# shutdown -p now
  # Stop services and power off when the platform supports it
# 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.