Physical console recovery — the hard path that always works

The physical console is the recovery path that always works. Unlike the GUI or SSH, the console does not depend on the firewall’s network interfaces, routing, firewall rules, or authentication. The console is a direct connection to the FreeBSD kernel’s text terminal. When every other path is broken, the console still works.

This lesson covers the physical console path — serial console, BMC/KVM over IP, IPMI — how to connect to the OPNsense console, the boot menu options, single-user mode, and the operator actions that recover from a hard lockout.

The three console paths

OPNsense supports three console paths:

1. Serial console. A physical serial port (DB9 or USB) on the appliance, connected to the operator’s workstation via a serial cable (USB-to-RJ45 or USB-to-DB9). The operator opens a terminal session with cu, minicom, or screen.
2. BMC / KVM over IP. A dedicated management controller on the appliance (iDRAC, iLO, iBMC) that exposes a virtual console over the network. The operator connects via a web browser or Java applet to the BMC’s IP address.
3. IPMI SOL. Serial-over-LAN, a virtual serial console that tunnels the host’s serial console over the BMC network. The operator connects with ipmitool -I lanplus -H <bmc> sol activate.

The three paths converge on the same FreeBSD console. The choice depends on the appliance hardware and the operator’s access. A rack-mounted server with iDRAC has all three. A small appliance may have only serial. A virtual OPNsense on Proxmox has only KVM over IP.

Connecting via serial console

The serial console is the most common physical console path. The operator connects a serial cable from the appliance’s serial port to the operator’s workstation and opens a terminal session.

The default OPNsense serial settings are 115200 baud, 8N1 (8 data bits, no parity, 1 stop bit). The FreeBSD serial device is typically /dev/cuau0 (USB serial) or /dev/cuau1.

$ cu -l /dev/cuau0 -s 115200

Connected.
FreeBSD/x86 bootstrap loader, Revision 1.1
(root@opnsense-build, Tue Aug 14 14:22:11 UTC 2026)

Consoles: internal video/keyboard  serial port
Boot environment: default
Boot loader password: 
Press any key to boot in 5 seconds...

OPNsense 25.7.3 ...
...

If the operator sees the OPNsense boot menu, the serial console is working. If they see nothing, the baud rate is wrong (try 9600, 38400, 115200), the cable is wrong (null modem vs straight-through), or the port is wrong.

The console gives the operator a root shell after the boot menu. From the shell, the operator can run any command — pfctl, pfctl -f, edit /conf/config.xml, reset state, restart services.

Connecting via BMC / KVM over IP

Most rack-mounted servers have a BMC (Baseboard Management Controller) — iDRAC (Dell), iLO (HPE), iBMC (Lenovo), or Supermicro’s BMC. The BMC has its own IP address, separate from the host’s network interfaces, and exposes a web UI for power control, virtual console, and SOL.

The operator connects to the BMC’s web UI, navigates to the virtual console (HTML5 or Java applet), and sees the same console as the physical serial port. The operator types into the virtual console as if they were at a physical keyboard attached to the appliance.

The BMC is independent of the host’s network, so the BMC works even when the host is unreachable. The BMC also allows power control (power on, power off, reset, cycle) and remote media (mount an ISO for reinstall).

The BMC has its own authentication. The default credentials are well-known (admin/admin, root/calvin, etc.); the operator should change them during provisioning. The BMC should be on a separate management network, with source-restricted access and ideally MFA.

Connecting via IPMI SOL

IPMI SOL (Serial-over-LAN) is a virtual serial console that tunnels the host’s serial console over the BMC network. The operator connects with ipmitool:

# Substitute your own values before running:
BMC_HOST=192.0.2.50
BMC_USER=admin
BMC_PASSWORD=the-bmc-password-set-at-provisioning

ipmitool -I lanplus -H "$BMC_HOST" -U "$BMC_USER" -P "$BMC_PASSWORD" sol activate

The output is the same as a physical serial console: the boot loader, the kernel boot, the OPNsense menu, and the root shell. The advantage of SOL over the BMC’s HTML5 console is that it works in any terminal, can be scripted, and is bandwidth-light (text only).

IPMI SOL requires the host BIOS to be configured to redirect the serial console to the BMC. Most modern servers support this; the BIOS setting is typically under “Serial Port Configuration” or “Console Redirection”.

The boot menu

When OPNsense boots, the boot menu appears with several options:

FreeBSD/x86 bootstrap loader
Consoles: internal video/keyboard  serial port
Boot environment: default
1. Boot default
2. Boot previous
3. Boot single user
4. Boot verbose
5. Boot with kernel modules loadable
6. Escape to loader prompt
7. Reboot

The relevant options for recovery:

• Option 1 (Boot default). Normal boot. Use when the configuration is correct and the operator wants to recover from a service failure, not a configuration failure.
• Option 2 (Boot previous). Boot from the previous boot environment. Use when a firmware or kernel upgrade broke the current environment.
• Option 3 (Boot single user). Boot with a minimal environment and a root shell. Use for password recovery and configuration file editing.
• Option 7 (Reboot). Restart the firewall. Use when the operator has made a change from the shell and wants to test it in the running configuration.

Single-user mode for password recovery

Single-user mode is the most common recovery path. The operator boots into single-user mode and gets a root shell. From the shell:

1. Mount the configuration partition read-write:

   mount -a

2. Reset the local root password:

   opnsense-password

3. Or edit the configuration directly to reset a user password, disable 2FA, or change source restrictions.

4. Reboot into the normal boot environment:

   reboot

The opnsense-password script writes the new password hash to /conf/config.xml. After the reboot, the operator can log in with the new password via the GUI, SSH, or the console.

For 2FA lockout, the operator can disable 2FA on the account by editing /conf/config.xml and removing the otp_seed field for the affected user. After the reboot, the user can log in without 2FA.

Recovering from a misapplied rule change via console

If the operator cannot reach the GUI or SSH because of a misapplied rule, the recovery path is:

1. Connect to the console (serial, BMC SOL, or IPMI SOL).

2. Reboot the firewall and select option 3 (single user).

3. Mount the configuration partition: mount -a.

4. Edit the configuration to remove the misapplied rule. The configuration file is /conf/config.xml. Use vi or ee:

   ee /conf/config.xml

5. Find the rule element and remove it.

6. Reboot: reboot.

7. Verify the GUI is reachable.

If the operator prefers a full rollback to the previous configuration, the boot menu’s option 2 (Boot previous) may revert the configuration to the previous boot environment’s configuration. The previous boot environment is created by the firmware update mechanism; if the operator has not updated, there is no previous environment.

$ mount -a && ls /conf/

/dev/gpt/OPNsense-boot on / (ufs, local)
devfs on /dev (devfs)
/dev/gpt/OPNsense-conf on /conf (ufs, local, synchronous)
base.xml          backups/          config.xml        mountpoint        use_ufs

Verification

After any console-based recovery, verify:

1. The GUI is reachable from a known-good source IP.
2. SSH works with the new password or key.
3. The firewall rules are correct (pfctl -s rules).
4. The configuration matches the expected state.
5. The break-glass path still works (local account with a known password, SSH key).

A recovery that passes 1-2 but fails 3-5 is a partial recovery. The operator must complete the verification before declaring the incident closed.

Summary

• The physical console is the recovery path that always works. Three paths: serial, BMC/KVM over IP, IPMI SOL.
• The console path is verified during provisioning, not during the incident. Wrong baud rate, wrong cable, BMC not configured are common failures.
• Single-user mode gives a root shell on the console. Use opnsense-password to reset passwords or edit /conf/config.xml to fix configuration.
• The boot menu has options for default boot, previous boot environment, single user, verbose boot, and reboot.
• After any console recovery, verify GUI, SSH, rules, configuration, and break-glass path.