Restore from backup — the procedure, the verification, and the rollback plan · OPNsense

A backup is only useful if it can be restored. The restore procedure looks simple from the GUI: select the snapshot, click Restore, reboot. The interesting parts are everything that happens after the firewall comes back up — the verification, the partial-restore techniques for fixing one section without overwriting the rest, and the rollback plan when the restore itself causes the next incident.

This lesson covers the three restore methods, the post-restore verification checklist, the partial-restore discipline, and the rollback plan that makes the restore itself safe.

The three restore methods

OPNsense supports three ways to apply a configuration backup. They are not interchangeable.

Method	When to use	Pre-conditions
GUI: System → Configuration → Backups → Restore	The GUI is reachable, the operator is hands-on, the backup file is on the workstation	GUI access, valid credentials
API: POST /api/core/backup/restore	The restore is automated (configuration management), or the GUI is reachable but the operator prefers the API	API access, valid API key
Single-user shell: cp backup /conf/config.xml && reboot	The GUI is unreachable, the console is the only path, or the operator needs to restore before reboot	Console access (physical or virtual)

The GUI method is the most common. The operator uploads the file, confirms the warning dialog, and the firewall reboots with the restored configuration. The API method does the same thing programmatically. The shell method is the last resort: when the GUI is unreachable but the operator has console access, the operator copies the file into place from the console and reboots.

The post-restore verification checklist

A firewall that has just booted from a restore is in an unknown state. The boot succeeded; the services may not all be running; the rules may have been regenerated; the interfaces may have re-assigned; the certificates may have moved. The operator runs the verification checklist before declaring the restore successful.

Check	Command	Expected
Interfaces up	`ifconfig`	All configured interfaces present and up
Routing table	`netstat -rn`	Default route present, expected routes present
Firewall rules	`pfctl -s rules`	Expected count of rules, expected anchor blocks
NAT rules	`pfctl -s nat`	Expected outbound NAT, port-forwards present
DNS resolver	`drill @127.0.0.1 example.net`	Resolves (or returns NXDOMAIN for non-existent)
DHCP server	`service dhcpd status`	Running on expected interfaces
IPsec tunnels	`ipsec statusall`	Tunnels either established or in expected state
WireGuard tunnels	`wg show`	Interfaces present, peers configured
GUI reachable	Browser	Login page loads, cert is the expected one
SSH reachable	`ssh root@<fw>`	Banner matches expected
NTP synchronised	`ntpq -p`	Reachability 377 on at least one source
Logs flowing	`tail /var/log/system/latest.log`	Recent entries, no error spam

Read-only / SafePost-restore sanity check— Three counts: number of loaded PF rules, number of NAT entries, number of UP interfaces. The expected values come from the change ticket baseline. A count of zero or a count that has changed unexpectedly is the first signal that the restore did not produce the configuration the operator intended.

$ pfctl -s rules | wc -l && pfctl -s nat | wc -l && ifconfig | grep -c "UP"

142
28
6

Illustrative output

The checklist is not optional. The operator who skips the verification and announces “the firewall is restored” without confirming each item is the operator whose next page is the next incident. The verification is the proof that the restore produced the configuration the operator intended, not just a configuration.

Partial restore: fixing one section without overwriting the rest

Sometimes the operator does not want a full restore. The change that broke things was a single rule, a single alias, a single certificate — and the rest of the configuration is correct. A full restore loses every change made since the backup. A partial restore replaces the broken section with the version from the backup and leaves the rest alone.

The technique:

Download the backup. Copy the XML to a workstation.
Identify the section to restore. Open the live XML (download a current snapshot) and the backup XML. Diff them with xmllint --c14n and diff.
Extract the section from the backup. For example, the \<filter\> section, the \<aliases\> section, or a single \<alias\> element.
Replace the section in the live XML. Use xmllint to validate the merged XML before applying.
Apply via API or paste into the GUI. The API allows a single \<section\> patch; the GUI does not, so the operator must use the API for partial patches.

The partial restore is harder than the full restore. The operator must understand the XML structure, must validate the merge, and must know which sections can be patched independently. The XML sections that are safe to patch in isolation: \<aliases\>, \<filter\> (with caveats — NAT rules live elsewhere), \<staticroutes\>, \<cron\>, \<ntpd\>. The sections that must be patched together: \<IPsec\> and \<IPsec\>\<phase1\> together, \<wireguard\> and \<wireguard\>\<peer\> together.

The rollback plan when the restore itself breaks things

The restore can fail. The backup file can be from a different firmware version, the XML can reference a plugin that has been removed, or the restored configuration can conflict with the running services in ways that did not exist when the backup was taken. The operator needs a rollback plan that is exercised before the restore, not after.

The rollback plan:

Pre-restore snapshot of the current configuration. Even if the current configuration is broken. The broken configuration is the rollback target if the restored configuration is also broken.
Document the baseline. Record the count of rules, NAT entries, interfaces, and the version of the firmware. The baseline is the comparison for the verification checklist.
Test the restore on isolated hardware. If the production restore is high-risk, restore the same backup to a test appliance first. Confirm the boot, the verification checklist, and the next-boot behaviour.
Plan the next restore. If this restore is wrong, what is the next backup to try? The previous one? The one before that? The names of the candidate backups must be in the change ticket before the restore begins.

Summary

Three restore methods: GUI, API, single-user shell. Pick by access path.
The verification checklist runs after every restore. No exceptions.
Partial restores are possible but require XML fluency and validation.
A pre-restore snapshot is the rollback path if the restore fails.
Test the restore on isolated hardware before applying to production.