Recover an OpenBSD System That Does Not Boot

Synopsis #

Boot recovery starts by identifying the failing stage. Firmware must select a device, primary boot code must load the OpenBSD boot loader, the boot loader must read a kernel, the kernel must select and check filesystems, and the service configuration must reach multi-user mode.

This guide provides a conservative recovery sequence. It does not assume that disk numbers remain the same, and it does not rewrite partition tables or boot blocks until the target and failure have been established.

Maintain verified installation media and authorized console access before a failure occurs.

Identify the Failure Stage #

Use the last successful output to choose the first diagnostic:

Photograph or record the exact message before changing anything.

Use the Boot Prompt #

On platforms with the OpenBSD boot(8) prompt, stop automatic boot and list the root directory:

boot> ls

Try the default kernel explicitly:

boot> boot /bsd

When the default kernel fails but the standalone recovery kernel exists, boot it:

boot> boot /bsd.rd

On amd64 and i386, a different disk or partition can be named explicitly, for example:

boot> boot hd1d:/bsd.rd

Device syntax is architecture-specific. Consult the platform’s boot(8) and INSTALL.<arch> documentation before adapting this example.

To diagnose a multi-user configuration problem, boot the normal kernel in single-user mode:

boot> boot /bsd -s

Do not make single-user mode remotely accessible. It is a console recovery environment.

Recover from Installation Media #

If the disk boot loader or recovery kernel is unavailable, boot verified installation media and select (S)hell. Re-identify all disks:

# sysctl hw.disknames
  # Record current disk names and DUIDs
# dmesg | grep '^sd'
  # Match each disk to hardware and size
# disklabel sd0
  # Inspect the proposed system disk
# fdisk sd0
  # Inspect its outer partitioning

The installed system may not be sd0. Softraid volumes can assemble under a different number. Stop if the root partition is not certain.

Check Filesystems Offline #

Do not repair a writable mounted filesystem. From installation media or an appropriate single-user environment, check the identified raw root partition with fsck(8) :

# fsck -p /dev/rsd0a

Replace sd0a with the actual root partition. -p performs safe preen repairs. If serious inconsistencies require manual decisions, stop, preserve available data, and review each proposed repair. Do not substitute a generic fsck -y command.

Check other FFS filesystems separately, using their actual raw devices. A failed data filesystem can prevent multi-user boot through /etc/fstab even when root is sound.

Mount and Inspect the Installed System #

Mount the root filesystem read-only first:

# mount -o ro /dev/sd0a /mnt

Inspect /mnt/etc/fstab, /mnt/etc/boot.conf, recent configuration changes, and available kernels. Confirm DUIDs against current disklabel output.

When a repair requires writes, unmount and remount root read-write only after the filesystem check succeeds:

# umount /mnt
  # Remove the read-only mount
# mount /dev/sd0a /mnt
  # Remount the checked root filesystem read-write

Mount any separate /usr filesystem before using programs or boot files stored there.

Repair Configuration Failures #

For an invalid /etc/fstab, comment only the failing nonessential entry or correct its DUID, filesystem type, mount point, and options. Preserve a copy of the original file.

For a daemon or network change that blocks multi-user boot, disable only the implicated service or restore the last known-good configuration. Avoid broad deletion of /etc/rc.conf.local, PF rules, or interface files.

From single-user mode, mount local filesystems and continue the boot after correcting the cause:

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

Reinstall Boot Blocks Only When Required #

installboot(8) writes architecture-dependent bootstrap data. It does not repair a missing kernel, damaged filesystem, wrong firmware boot order, or incorrect /etc/fstab.

When diagnostics establish that boot blocks are the problem, use the mounted installed root with -r. Dry-run the exact target first:

# installboot -n -v -r /mnt sd0
  # Preview the architecture-specific operation without writing

Review the reported disk, boot files, firmware mode, and partitions. Write only when the preview matches the recovery plan:

# installboot -v -r /mnt sd0

Replace sd0 with the positively identified boot disk. A supported softraid boot volume and its chunks require the procedure documented by softraid(4) and the platform manual.

Verify Before Returning to Service #

After repairing the system:

1. unmount recovery filesystems cleanly;
2. remove installation media;
3. boot through the normal firmware path;
4. confirm root and all expected filesystems with mount;
5. inspect dmesg, /var/log/messages, and rcctl ls failed;
6. verify local administration before testing remote access;
7. confirm backups before restoring production traffic.

Document the failure, evidence, changed files, commands, and final device identities. Replace failing storage rather than treating a successful boot as proof of healthy hardware.

See Recover Access and Reset the Root Password for an authentication-only failure and Back Up and Restore an OpenBSD System for bare-metal recovery preparation.