Snapshots¶
Index
Quick Overview¶
Snapshots capture the base system at a given moment. They’re useful for administration, as they introduce a fallback boot option when more risky operations like major upgrades or experimental configurations fail. If something goes wrong, it is quite simple to roll back to the previous working state.
These Snapshots leverage ZFS features, making them space-efficient and easy to manage. During the boot process, the latest and previous saved Snapshots can be chosen with Option 8, effectively switching between different system states.
Attention
Snapshots require ZFS as filesystem. UFS will not work since it does not support file system level snapshots.
The Snapshots are differential. A new Snapshot is always the latest current running state. This means, there are no incremental Snapshot chains, as seen in other implementations such as Hypervisors.
Note
Each Snapshot can be created and deleted as its own self contained entity with no other dependencies. The size of each Snapshot will grow over time as the distance in bytes between the current active Snapshot and all stored non-active Snapshots grow.
Recommended Workflow¶
Create a new Snapshot with the name
known-good
Do administrative changes (e.g. firmware upgrade)
Reboot and test the changes:
- OPNsense works as expected:
Remove the known-good Snapshot and keep using the default Snapshot
- OPNsense has issues:
Activate the known-good Snapshot either in the WebGUI or the Boot Menu
After rebooting, remove the bad default Snapshot
Rename the known-good Snapshot back to default
Tip
Snapshots can also be used to safeguard against regressions introduced in configuration changes. Creating a new snapshot and activating it immediately, will make the system roll back automatically to the last known good configuration on reboot or power cycle.
Tutorial¶
As an example, there is a major upgrade to a new OPNsense version. To have the option of a quick rollback when things do not turn out as expected, creating a Snapshot before doing the changes is the best choice.
Note
This is useful for Hardware Appliances. A virtualized OPNsense will have other recovery options that leverage the features of the Hypervisor itself, like creating VM level snapshots.
Snapshots can have the following states:
Active |
Description |
---|---|
N |
Snapshot is active right now |
R |
Snapshot will be active after reboot |
NR |
Snapshot is active and will be used on reboots |
- |
Snapshot is not active |
Creating a Snapshot¶
- Go to
- Select + to create a new Snapshot, use
known-good
as name
At this point, upgrade the OPNsense to a new version. These changes will all happen in the current active default Snapshot, leaving the known-good Snapshot as last known good configuration.
Booting a Snapshot¶
If the upgrade introduced some issues, the known-good Snapshot can be activated from the WebGUI.
If the WebGUI is available:
- Go to
- Select ✓ to activate the known-good Snapshot
- Reboot the OPNsense to roll back to the known-good Snapshot
Note
In some cases, if the OPNsense does not boot to the WebGUI due to a software error, the Boot Menu can be used to roll back. If a Hardware Appliance does not have VGA, using the serial console is the best alternative.
If the WebGUI is unavailable:
- Boot the OPNsense, at the start of the boot sequence the Boot Menu will show up
- Press the Space Bar to pause it
- Press
8
to choose8. Boot Environments
which displays the current Snapshots - Press
2
to select a different active Snapshot, it should now displayzfs:zroot/ROOT/known-good
- Press
1
to go back to the main menu - Press
ENTER
to select1. Boot Multi user [ENTER]
Tip
If there are more Snapshots, press 2
repeatedly to cycle through them.
Deleting a Snapshot¶
Now that the OPNsense has booted either the known-good Snapshot or the default Snapshot, it is time to clean up to ensure a clear current system state.
If the upgrade succeeded and default has been booted:
- Go to
- Check that the default Snapshot is Active NR
- Press 🗑 to delete the known-good Snapshot
If the upgrade failed and known-good has been booted:
- Go to
- Check that the known-good Snapshot is Active NR
- Press 🗑 to delete the default Snapshot
- Press ✎ to rename the known-good Snapshot to default
At this point, the OPNsense is correctly configured at the last known good configuration state.
Tip
Snapshots can be kept for a while after an upgrade, to have the option to roll back after a few days of testing in production. Please note that all configuration changes in that time will be lost when rolling back, so creating a configuration backup and importing it into the old system state can become a necessity.
Note
Creating a Snapshot can be repeated to retry the major upgrade. Refer to the Recommended Workflow for a quick overview.