How Boot Environments Work¶

A ZFS Boot Environment is a snapshot of the filesystem at a specific point in time, plus a clone of that snapshot. Snapshots are read only views of the filesystem at a given point, whereas clones are read/write.

Each snapshot and clone consumes some disk space but the exact amount varies based on how much the current contents of the filesystem have diverged from the contents when the entries were created.

Note

For most users tracking periodic updates or creating occasional ZFS boot environments the disk usage will be moderate over time. Users tracking development snapshots with frequent updates may see much larger amounts of space consumed by ZFS Boot Environments from snapshots. See Boot Environment Disk Space Usage for details.

When an administrator triggers the upgrade process the firewall creates a new ZFS Boot Environment before the upgrade begins. This preserves the current state of the firewall as it was before the upgrade.

What happens next has changed over time. From pfSense Plus software version 22.05 until 23.09.1, the upgrade process then activates the new ZFS Boot Environment so that when the upgrade proceeds and reboots, it reboots into the new environment to complete the upgrade.

Starting with pfSense Plus software version 24.03, this changed to a more efficient and robust procedure: The upgrade process creates a new Boot Environment and performs the upgrade inside that entry before rebooting. It makes sure the upgrade succeeded and then reboots into the newly upgraded environment. It detects any errors during boot and if there is a problem it can automatically roll back to the previous Boot Environment.

Either way, if there is a problem, an administrator can manually activate a pre-upgrade ZFS Boot Environment and reboot the firewall and it will return to its state before the upgrade happened.