An OPNsense configuration backup is a single XML file that you download from System > Configuration > Backups, and restoring it is how you recover from a bad change, a failed disk, or a move to new hardware. The live configuration itself is stored on the firewall as /conf/config.xml, and OPNsense also keeps previous versions locally, which console menu option 13 can restore. This guide covers downloading a backup properly (including password protection), the restore paths and when each one applies, and how to make sure the file you saved can actually save you.
What the backup file is, and what is in it
The backup is one XML document describing the machine's configuration: interfaces and their addresses, firewall rules, NAT, DHCP and DNS settings, users, certificates, VPN configuration, and the settings of your services. Because it is plain XML, it is human readable in a text editor, which is occasionally useful when you want to check what an old configuration contained without restoring it.
Two properties of the file shape how you should treat it. First, it is sensitive: it contains password hashes, private keys, and shared secrets for VPNs and services. Anyone holding your backup holds the keys to your network, which is why the backup page offers password protection for the download and why you should store backups the way you store passwords. Second, it is configuration only: it is not a disk image, and it does not contain the operating system or your log history. Restoring it onto a working OPNsense installation reproduces your setup; it does not resurrect a dead installation by itself. Optionally, the download can include RRD statistics data in the same XML file, which preserves your traffic graphs; that is a nice-to-have, not a requirement for recovery.
Downloading a backup
- Log in to the web interface and open System > Configuration > Backups.
- Decide on password protection. Protecting the backup encrypts it with a password you supply. This is recommended whenever the file will leave the firewall, which is always. Choose a password you store in your password manager; an encrypted backup whose password is lost is worthless.
- Decide whether to include the RRD statistics. Include them if you care about keeping historical graphs; skip them if you want the smallest, cleanest configuration file.
- Click the download button and save the file. The name identifies the firewall and the date, which makes a folder of backups self-explanatory.
- Store at least one copy somewhere that is not the firewall itself: your computer, a NAS, or cloud storage you control. A backup that lives only on the machine it protects is not a backup.
Take backups at the moments that matter: before a firmware update, before an address or assignment change, after any significant reconfiguration, and after you finish a setup you are happy with. A rhythm of "backup before, backup after" around every change means you always have both a retreat point and a current recovery point. The safe update guide builds this into its routine for exactly that reason.
The local safety net: configuration history
Separately from downloaded files, OPNsense keeps previous versions of the configuration on the machine itself. The Backups area includes a History view that tracks the changes between configuration versions and lets you download older versions, and you can configure how many backups are retained. This local history is what powers the quickest undo in the system: at the console, option 13, Restore a configuration, lists the locally kept versions and restores the one you pick.
Understand the limit of this safety net: it lives on the same disk as the running system. It protects you against bad changes, which are the most common accident, but not against disk failure or a lost machine. That is why the downloaded, off-machine file remains the real backup, and the local history is a convenience layered on top of it. The console menu itself, including option 13, is explained in our first boot and console menu guide.
For completeness, the on-disk layout is simple: the live configuration is the file /conf/config.xml, and the automatic previous versions are kept alongside it in the same directory. You never need to edit these files by hand, and you should not; the web interface and the console menu exist precisely so that configuration changes are validated and recorded. Knowing where the file lives is still useful for one job: if a machine's disk is readable but the system will not boot, the configuration can be recovered from /conf on that disk and imported into a fresh installation, which turns a hardware failure into a restore exercise instead of a rebuild.
Restoring a backup
There are four restore paths. They differ in scope and in the situation they suit.
Full restore in the web interface
On the same Backups page, the restore function accepts a backup file (entering its password if you protected it) and restores the complete configuration. The firewall reboots afterwards, because interface addresses, services, and core settings may all have changed at once. When it comes back, it should be the machine described by the file: same addresses, same rules, same accounts. Log in with the credentials from the restored configuration, which may not be the ones you used a minute ago.
Partial restore
The restore function also allows restoring only selected areas of a backup rather than the whole file. This is genuinely useful for surgical jobs, such as bringing back just the firewall rules from last week. Treat it with respect: the official documentation cautions that partial restores can behave unexpectedly, because sections of the configuration refer to each other. Use partial restores for narrow, understood changes, and prefer a full restore for disaster recovery.
Console restore of a local version
If a change has broken your access but the machine itself is fine, the console is faster than any upload: log in as root, choose option 13, and pick the version from before the change. The system restores it and reboots. This is the right tool for "I broke something five minutes ago", including a LAN address change that locked you out, as covered in the LAN IP guide.
Importing during installation
The full installation images provide a configuration importer that can run before boot. Point it at a stored backup and the new installation starts life with your configuration, including its root password, which replaces the installer's default. This is the recovery path for a dead disk or a new machine: install OPNsense fresh, import the backup, and you are back. One detail from the official documentation: console settings are excluded from imports by default, so check console related settings after an import rather than assuming they came across.
The four paths compared
| Path | Where | Best for | Source of the configuration |
|---|---|---|---|
| Full restore | Web interface, Backups page | Disaster recovery, rolling back a whole change set | A backup file you upload |
| Partial restore | Web interface, Backups page | Recovering one area, such as rules, from an older file | Selected sections of an uploaded file |
| Console restore | Console menu option 13 | Undoing a recent bad change when the GUI is unreachable | A previous version kept on the machine |
| Importer | Installation media, before boot | New disk or new hardware | A backup file on removable media |
One more thing to verify after restoring onto a fresh installation: plugins. Your plugin settings live in the configuration, but the plugin packages are software installed on top of the base system. After a restore onto a newly installed machine, check the firmware plugins area and reinstall any missing plugins so the services those settings describe actually exist again.
Restoring onto different hardware
A backup does not care what hardware it lands on, with one predictable exception: interface names. If the new machine's network cards produce different interface names than the old one, the restored configuration refers to interfaces that do not exist. OPNsense handles this gracefully: instead of rebooting into a broken state, it prompts you to fix the interface assignments, matching each role to a port on the new hardware. Work through that prompt using MAC addresses to identify ports, as described in our interface assignment guide, and the rest of the configuration applies unchanged.
A backup routine that runs itself
Backups taken "when I remember" are usually missing exactly when needed, so anchor them to events instead of memory:
| Trigger | Action |
|---|---|
| Before any firmware update | Download a backup, label it "pre-update" with the date |
| Before changing addresses, assignments, or rules in bulk | Download a backup, even if the change looks small |
| After a change you are keeping | Download a fresh backup so the recovery point includes it |
| After finishing initial setup | Download the "baseline" backup and keep it permanently |
| Monthly, if the system changes often | Download a dated backup and prune generations older than your retention comfort |
However you schedule it, keep the storage rule absolute: at least one current backup exists somewhere that is not the firewall, and at least one older generation exists beside it. Some administrators automate the off-machine copy; if you do, apply the same encryption and access care as for manual downloads, because an automated copy of an unencrypted backup is an automated copy of your keys.
Making sure your backup can actually save you
An untested backup is a hope, not a plan. You cannot fully prove a backup without restoring it, but you can get close with cheap checks:
- Open the file. An unencrypted backup opens in a text editor as structured XML beginning with the configuration root element. A file that is empty, truncated, or binary garbage failed at download time; take it again.
- Check the date and the hostname in the file name before you rely on it, so you do not restore last year's network by accident.
- Keep more than one generation. Retain the last few backups rather than overwriting a single file. If the most recent backup captured an already broken configuration, the previous one is your salvation.
- Do a real restore once, somewhere safe. If you have a spare machine or a virtual machine, restore your production backup to it and confirm it boots with your addresses and rules. That single exercise converts your backup from a hope into a known quantity, and it rehearses the recovery before the day you need it under pressure.
- Guard the password. If your backups are encrypted, the password belongs in your password manager next to the root password, tested by actually opening one backup with it.
Where backup habits usually fail
The failures are boringly consistent. The backup exists but only on the firewall that just died. The backup exists but is encrypted with a password nobody recorded. The backup exists but is from before the network was redesigned, because "after" backups stopped happening once the setup felt finished. Or the backup exists and is current, but nobody has ever restored one, so the recovery takes hours of first-time learning during an outage. Every item in the routine above exists to kill one of these four failures, and none of them requires new tools, only consistency.
How to confirm a restore worked
- The firewall reboots and the console banner shows the LAN address from the restored configuration.
- You can log in to the web interface using the credentials that were current when the backup was taken.
- Interfaces show the expected assignments and addresses, and WAN receives its expected address.
- LAN clients receive DHCP leases and can reach the internet.
- Spot check two or three things only you would know: a specific port forward, a VPN instance, a custom rule. If those are present, the restore took the whole configuration, not a subset.
- Download a fresh backup of the restored state and label it, so your backup folder reflects reality again.
With a tested backup routine in place, most other work on the firewall becomes low risk. Changes can be undone, updates can be rolled back to a known configuration, and hardware failure becomes an inconvenience instead of a rebuild. It is the highest value habit in this entire category of guides.