Runbook: Restore Firewall Configuration
1 · Prerequisites
Confirm every item is in place before any state change.
- Backup XML file available on the firewall or on a trusted host
- Maintenance window scheduled for the affected environment
- Console or GUI access to the firewall
- Operator familiar with the difference between full and partial restore
2 · Pre-checks
Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.
- · Confirm the backup file is the right one for the appliance (hostname, firmware version, date)
- · Capture the current configuration under System > Configuration > Backups as a rollback safety net
- · Capture the current routing, CARP, and pfsync state on the appliance
- · If the appliance is in an HA pair, decide which appliance will be restored first and which will be promoted
3 · Procedure
Execute each step in order. Verify the expected output of a step before moving to the next.
- 1Open System > Configuration > Backups and click Restore configuration
- 2Select the backup file from the firewall filesystem or upload from the local machine
- 3Confirm the backup details — sections included, hostname, firmware version — match the appliance
- 4Click Restore and wait for the configuration to apply and the appliance to reboot if necessary
- 5After the appliance returns, confirm the management interface is reachable and the GUI is responsive
- 6Validate the routing and the firewall rules by sending a small amount of test traffic through the appliance
- 7If the appliance is in an HA pair, force a failover and confirm the peer assumes the master role cleanly
- 8Repeat the restore on the peer appliance if both appliances are being restored to a known-good configuration
- 9Update the change record with the backup file metadata, the restore timestamp, and the operator name
4 · Verification
Confirm the procedure actually fixed the problem.
- ✓The GUI is responsive from the trusted management subnet
- ✓A test flow from the inside to the outside traverses the firewall and returns
- ✓The CARP and pfsync state is healthy on the peer appliance in an HA pair
- ✓The change record contains the backup file metadata and the restore timestamp
5 · Rollback
If verification fails, undo the procedure in reverse order.
- ↶If the restore produces an unusable configuration, restore from the safety-net backup captured before the procedure
- ↶If the appliance is unreachable, restore from the console by uploading the XML file via the shell
- ↶If the HA pair is broken, isolate the broken appliance and let the surviving appliance continue as master
6 · Escalation
When the runbook isn't enough, contact:
- · Engage the platform team if the restore fails and the appliance is on the wrong firmware version
- · Engage the network team if the restore causes asymmetric routing or a split-brain
- · Engage the security team if the restored configuration contains unexpected rules or credentials
Purpose
Restore a previously backed-up OPNsense configuration to an appliance after a misconfiguration, a hardware swap, or a confirmed software regression.
When to use this runbook
Use this runbook when a configuration change has caused a regression that cannot be reversed by editing the rule, when a hardware swap requires the configuration to be reconstructed, or when a peer appliance in an HA pair must be rebuilt to match the master.
Pre-checks
Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.
Procedure
Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.
Verification
After the procedure, the structured verification items from the frontmatter are rendered as a checklist.
Rollback
If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.
Escalation
The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.