Boot menu and console — single-user, reset, factory recovery

A production firewall that will not boot to a usable state is a high-stress incident. The operator who knows the boot menu, single-user mode, password reset and factory reset paths can recover in minutes; one who does not is on the phone with support. This lesson walks through the boot menu, the FreeBSD boot loader, single-user mode, root-password reset, factory reset, and the recovery flow when none of the standard paths work.

The OPNsense boot menu

When OPNsense boots on a serial console or in a VM with the console attached, the boot menu appears with a 5-second countdown. The operator presses a key to interrupt.

>> FreeBSD/x86 boot block
   Start @ 0x...
   Boot loader: /boot/loader

Console: serial port
BIOS drive: 0
Booting from disk...

OPNsense boot menu
  1. Boot with [S]ingle user mode
  2. Boot with [V]erBOSE messages
  3. Boot with [C]onsole on serial port
  4. Boot with [A]CF disabled
  5. Boot [D]efault
  6. Boot from [U]SB
  7. Boot from [N]et
  8. Escape to loader prompt

Default: 5

The operator presses the corresponding key to select. The default is “Boot default” — the running release.

loader> ? ls

 ls
disk devices:
 disk0: BIOS drive C
 disk0p1: FreeBSD boot
 disk0p2: FreeBSD swap
 disk0p3: FreeBSD ZFS

zfs pools:
 zroot: zroot

boot environments:
 25.7.4 (default)
 25.7.3 (previous)

The FreeBSD boot loader prompt

Pressing 8 from the OPNsense menu (or pressing Escape when the loader offers the prompt) drops to the loader prompt. The loader is a small interactive shell that runs before the kernel loads. Useful commands:

• boot — boot the kernel with the current settings.
• boot -s — boot into single-user mode.
• boot -v — boot with verbose messages.
• set currdev=... — change the boot device (typically to switch boot environments on ZFS).
• ls — list available boot environments, disks, partitions.
• ? or help — list all commands.

The operator uses the loader prompt when:

• The default boot fails (e.g. corrupted /boot/loader.conf).
• A specific boot environment needs to be selected (rollback after a failed upgrade).
• The kernel needs to be booted with a flag (e.g. -d for the kernel debugger).

Single-user mode

Single-user mode boots the kernel, mounts the root filesystem read-write, and drops to a root shell without starting any services. Networking is not configured. The operator uses single-user mode to repair the system without services running.

Typical uses:

• Root password reset. When the operator is locked out, single-user mode gives a root shell without needing the password (the secure mode in FreeBSD historically allowed this; modern FreeBSD requires entering the root password unless the operator has the physical console).
• Filesystem repair. Boot single-user, run fsck (UFS) or zpool scrub (ZFS) to repair filesystem corruption.
• Config edit. Boot single-user, mount /conf and /var read-write, edit a config file that cannot be edited while the system runs.

Enter full pathname of shell or RETURN for /bin/sh: /bin/sh

# mount -a
# zfs mount -a
# /usr/local/sbin/opnsense-password
Changing password for root.
New password:
Retype new password:
passwd: password updated successfully
# reboot

Root password reset

Three paths depending on the situation.

Path 1: GUI reset (the easy case)

The operator who still has GUI access resets the password through System → Access → Users → root → Change password. The new password is written to /conf/config.xml. The change is applied immediately.

Path 2: opnsense-password from single-user mode

The operator who has console access but no GUI access (e.g. the management interface is misconfigured) boots single-user, runs opnsense-password, and reboots.

Path 3: XML edit from the shell

The operator who has shell access via SSH (perhaps to a different account or via the management interface) reads /conf/config.xml, finds the <password> element under the <user> entry for root, and replaces it with a known hash. The hash format OPNsense uses is PHP’s crypt() with $1$ (MD5) or $6$ (SHA-512). The course’s API and automation lessons cover the password-hash format in detail.

$ php -r 'echo crypt("newpassword", "$1$salt") . "
";'

$1$saltsalt$Abc123Xyz...hash...

Factory reset

A factory reset returns the firewall to the state it was in the moment the install completed. The operator triggers it from the boot menu, from a fresh install, or by deleting the config XML.

Three approaches:

1. Fresh install. Re-run the installer, select “Install”, and confirm. The installer formats the disk and lays down a fresh configuration. The course’s install lesson walks through this; the same approach on an already-installed firewall is destructive — every config the operator built is gone.
2. Boot menu option. Some OPNsense builds expose a factory reset option in the boot menu. The operator selects it, confirms, and the firewall resets to defaults.
3. Manual reset. From the shell, the operator runs /usr/local/sbin/opnsense-reset (an OPNsense-provided helper that backs up the current config and writes a default), or deletes /conf/config.xml and reboots.

What survives a factory reset:

• The firmware version (the reset does not roll back the release).
• Installed packages (Suricata, WireGuard, etc.).
• Boot environments.

What does not survive:

• Interface assignments.
• Firewall rules.
• NAT rules.
• DNS, DHCP, VPN configuration.
• Local user accounts (except the default root).
• Certificates and keys.

Recovery flows

The operator’s decision tree when the firewall will not boot to a usable state.

Flow 1: Kernel panic on boot

1. Connect to the console (physical or BMC SOL).
2. Press the key to interrupt the boot menu.
3. Select option 8 to drop to the loader prompt.
4. Run ls to confirm the disk and ZFS pool are visible.
5. Run boot -s to boot single-user.
6. If the panic repeats, run boot -v to capture verbose output. Note the failing module.
7. Boot the previous boot environment: at the loader prompt, set currdev=zroot/ROOT/<previous> and boot.

Flow 2: Boot completes but services fail

1. Wait for the boot menu to time out and the kernel to finish loading.
2. When the OPNsense menu appears, drop to single-user.
3. Run zfs mount -a, then read the logs (/var/log/system.log).
4. Edit the configuration that caused the failure (typically a ruleset or service config).
5. Reboot.

Flow 3: GUI is unreachable but the firewall forwards

1. The firewall boots, services start, but the GUI does not respond. The data plane is fine.
2. SSH into the firewall and run service nginx status. If nginx is down, restart it. If PHP-FPM is down, restart it.
3. If the GUI does not come back, read /var/log/nginx/error.log and the system log for clues.
4. Last resort: drop to single-user and remove the GUI configuration that is failing (e.g. a misconfigured HTTPS listener) so the service starts in a known-good state.

Flow 4: Locked out of GUI and SSH

1. Connect to the console.
2. Boot single-user.
3. Reset the root password with opnsense-password.
4. Reboot. Log in to the GUI with the new password.

Summary

• The OPNsense boot menu offers single-user, verbose, default and alternate-environment boot. The FreeBSD loader prompt gives finer control.
• Single-user mode gives a root shell without services running. It requires console (physical, serial or BMC SOL) — not SSH.
• The password can be reset through the GUI, the opnsense-password script in single-user mode, or by editing the XML hash with a known password.
• Factory reset wipes config but preserves firmware and packages. The previous backups remain in /conf/backup/.
• Recovery flows: panic → previous BE; services fail → log diagnosis; GUI unreachable → service restart; lockout → console reset.