Snapshots

Index

• Snapshots

  • Quick Overview

  • Recommended Workflow

  • Tutorial

    • Creating a Snapshot

    • Booting a Snapshot

    • Deleting a Snapshot

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

1. Create a new Snapshot with the name known-good

2. Do administrative changes (e.g. firmware upgrade)

3. 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 System ‣ Snapshots
• 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 System ‣ Snapshots
  • 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 choose 8. Boot Environments which displays the current Snapshots
  • Press 2 to select a different active Snapshot, it should now display zfs:zroot/ROOT/known-good
  • Press 1 to go back to the main menu
  • Press ENTER to select 1. 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 System ‣ Snapshots
  • 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 System ‣ Snapshots
  • 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.