Factory reset and configuration restore — the last-resort recovery paths

Factory reset and configuration restore are the last-resort recovery paths. They are used when the operator has exhausted all other options — the GUI is unreachable, SSH is unreachable, the rules are wrong, and the configuration file is corrupted. Factory reset erases the configuration and returns the firewall to defaults. Configuration restore replaces the running configuration with a previously-saved backup. Boot-environment rollback reverts to a previous firmware or kernel version.

This lesson covers each path, what each loses, and the discipline of choosing between them.

When to use which

The decision tree:

1. GUI/SSH reachable, configuration correct, only rules wrong. Edit the rules. No factory reset or restore needed.
2. GUI/SSH unreachable, configuration file accessible from console. Edit /conf/config.xml from the console. No factory reset or restore needed.
3. GUI/SSH unreachable, configuration file corrupted. Restore from a backup. The backup replaces the corrupted configuration.
4. GUI/SSH unreachable, configuration file corrupted, no backup. Factory reset. The firewall returns to defaults and must be reconfigured from scratch.
5. Firmware or kernel upgrade broke the system. Boot-environment rollback. The previous boot environment is restored.

The factory reset is the last resort. It loses all configuration — interfaces, rules, NAT, aliases, certificates, user accounts, VPN tunnels, monitoring, everything. The configuration restore loses only the changes made since the backup was taken.

Factory reset via the boot menu

The OPNsense boot menu includes an option to factory-reset the firewall:

FreeBSD/x86 bootstrap loader
...

OPNsense menu:
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
8. Factory reset

The factory reset option deletes the configuration file (/conf/config.xml) and reboots. The firewall returns to its default state — WAN interface on the first NIC, LAN interface on the second, all other interfaces unassigned, default firewall rules, default credentials (root with no password — must be set on first login), default DNS, default NTP.

Factory reset via the shell

The operator can also factory-reset from a shell session:

rm /conf/config.xml
reboot

Deleting /conf/config.xml and rebooting causes the firewall to return to its default state. This is the same as the boot-menu factory reset, but performed from a shell instead of the boot menu.

A less destructive variant deletes only the firewall rules and NAT, preserving the interface assignments, aliases, and user accounts:

configctl filter reset
reboot

configctl filter reset clears the filter ruleset and regenerates it with the defaults. The configuration is preserved; only the ruleset is reset. This is useful when the ruleset is broken but the rest of the configuration is correct.

Configuration restore from backup

A configuration backup replaces the running configuration with a previously-saved configuration. The restore procedure:

1. Locate the backup. The backup should be on a workstation, a configuration management system, or another off-firewall storage. If the backup is only on the firewall (/conf/backup/), the operator must retrieve it from the console first.

2. Apply the backup. Three methods:

   • GUI: System → Configuration → Backups → Restore. Upload the backup file.
   • API: POST /api/core/backup/restore with the backup file as the body.
   • Shell (single-user): Copy the backup to /conf/config.xml and reboot.

3. Reboot. The firewall reboots with the restored configuration.

4. Verify. Confirm GUI, SSH, interfaces, rules, NAT, and user accounts are correct.

$ cp /conf/backups/config-2026-08-13-1422.xml /conf/config.xml && reboot

Writing configuration to /conf/config.xml...
Rebooting...

Boot-environment rollback

OPNsense uses ZFS boot environments (BEs) to allow rollback after firmware or kernel upgrades. Each firmware upgrade creates a new BE; the previous BE remains available for rollback.

The BE rollback is performed from the boot menu:

OPNsense menu:
1. Boot default
2. Boot previous
3. Boot single user
...

Option 2 (Boot previous) boots into the previous BE. The previous BE has the previous firmware, kernel, and configuration. If the operator upgraded from 25.1 to 25.7 and the upgrade broke something, booting into the previous BE returns to 25.1 with the configuration from before the upgrade.

The BE rollback is non-destructive — the current BE is preserved. The operator can boot back into the current BE by selecting option 1 (Boot default) after the rollback investigation.

Choosing the right recovery path

A decision tree for the operator at the console:

1. Is the firmware broken (kernel panic, boot loop)? Use the BE rollback. The previous BE has a known-good firmware and configuration.
2. Is the configuration corrupted (parse error, missing sections)? Restore from a backup. The backup has a known-good configuration.
3. Are only the rules wrong, but the rest of the configuration is correct? Edit /conf/config.xml from the console, or use configctl filter reset. No restore or factory reset needed.
4. Is the entire configuration unrecoverable and no backup exists? Factory reset. The firewall returns to defaults; reconfigure from scratch.

The decision is driven by what is broken and what is recoverable. The factory reset is the path of last resort, used only when nothing else works.

Verification

After any recovery path, verify:

1. The GUI is reachable from a known-good source IP.
2. SSH works with the expected credentials.
3. The interfaces are up (ifconfig).
4. The routing table is correct (netstat -rn).
5. The firewall rules are correct (pfctl -s rules).
6. The NAT rules are correct (pfctl -s nat).
7. The configuration matches the expected state.
8. The console path still works (close and reopen the console).
9. The break-glass path still works.
10. The backup is updated to reflect the current configuration.

A recovery that passes 1-7 but fails 8-10 leaves the operator without a tested recovery path for the next incident. The disciplined move is to complete all ten verifications before declaring the incident closed.

The discipline of tested recovery

The recovery paths are useless if they are not tested. The operator who has never performed a factory reset, a configuration restore, or a BE rollback will discover their gaps during the incident. The disciplined approach is to test the recovery paths during provisioning, not during the incident.

A quarterly drill:

1. Take a backup of the current configuration.
2. Make a small, non-disruptive change (e.g. add an alias).
3. Restore the backup. Confirm the change is reverted.
4. Verify GUI, SSH, rules, NAT, configuration.
5. Document the drill in the change log.

The drill confirms the recovery procedure works and gives the operator muscle memory. The drill takes 30 minutes; the recovery during a real incident takes minutes instead of hours.

Summary

• Factory reset, configuration restore, and BE rollback are the three last-resort recovery paths.
• Factory reset loses everything. Configuration restore loses only the changes since the backup. BE rollback reverts to the previous firmware.
• Choose based on what is broken and what is recoverable. Factory reset is the last resort.
• Verify the recovery paths during provisioning, not during the incident. Quarterly drills build muscle memory.
• Update the backup after every recovery to capture the current configuration.