28.9 ZFS Boot Environments
Overview
ZFS Boot Environments (BE) is a system version management mechanism built on ZFS snapshot and clone technology.
From a technical definition, "a ZFS boot environment is a writable ZFS clone file system cloned from a ZFS snapshot created at a certain point in time" (see: ZFS Boot Environments Explained[EB/OL]. [2026-03-26]. https://vermaden.wordpress.com/2025/11/25/zfs-boot-environments-explained/), which enables atomic updates, multi-system coexistence, and fast rollback.
Boot environments share a similar design philosophy with the A/B partition scheme of the Android system. Their core functions include atomic updates, dual-system coexistence, and snapshot and rollback.
If we understand boot environments solely from the perspective of FreeBSD system backup and restoration, the currently running system can be viewed as the "normal world." Drawing on a physics perspective: the world branches into different event choices at every moment; the branch worlds generated by events we did not choose are possible worlds. Therefore, the normal world is always the latest and most complete; the possible world can only be used for testing and is inherently flawed — it is merely how we use it. Although boot management theoretically allows this operation, even if you restore it to the normal world, you are merely returning to the normal world's timeline, not replacing the normal world with the possible world. The possible world can also be regarded as a "normal world" — it is simply that we have selected a specific version or deployment of FreeBSD as the standard.
Thought Question
Do you believe that our world has uniqueness compared to other worlds, rather than being a copy of some other normal world? If so, can you simply prove that our world is the most perfect among all possible worlds? If not, then there must exist a normal world — where might it be normal?
Using technologies such as ZFS snapshots, multiple completely independent operating systems can be implemented within a single ZFS file system, such as FreeBSD 14.3-RELEASE, FreeBSD 15.0-RELEASE, Gentoo Linux, etc., without interfering with each other.
Boot environments can also implement so-called "immutable systems," and are more thorough than traditional methods in achieving immutability. This functionality can be used to directly and completely replace the operating system.
Thought Question
It can be seen that certain seemingly fashionable concepts are often old wine in new bottles, and what FreeBSD lacks is precisely this kind of packaging. What are your thoughts on this?
Viewing the Environment
First, check the upgradable ZFS pools and their supported features:
# zpool upgrade
This system supports ZFS pool feature flags.
All pools are formatted using feature flags.
Every feature flags pool has all supported and requested features enabled."This system supports ZFS storage pool feature flags. All storage pools are formatted using feature flags. Each feature flags pool has all supported and requested features enabled."
This indicates that the ZFS storage pool does not need updating. The above command is for preview purposes only and cannot perform the update by itself. To update, the command is as follows:
Basic Usage of Boot Environments
In a default installation, zroot/ROOT/default is the default boot environment.
Create a ZFS snapshot example:
Use the newly created snapshot to generate a clone file system:
The generated clone file system can serve as a boot environment. You can use the bectl tool to list all ZFS Boot Environments:
In the Active column, N (Now) indicates the currently active boot environment, R (Reboot) indicates the default boot environment for the next boot, and T (Temporary) indicates an environment used only once for the next boot (set via bectl activate -t). These can appear in combination (e.g., NR, NT, RT, NRT).
The bectl tool can change the boot environment for the next boot (when starting FreeBSD, you can also change the boot environment by selecting 8 in the boot menu). Using the -t flag will temporarily activate a boot environment (one-time only), while the -T flag clears the temporary boot configuration.
Activate the ZFS boot environment new; the next boot will use this environment:
Use bectl list again to view all ZFS Boot Environments and observe the changes in the Active column:
Restart FreeBSD (select the new boot environment in the boot menu, or use bectl activate new to switch to the new boot environment), and use df to view the mounted root file system to confirm that it has switched to zroot/ROOT/new.
List the disk usage of the current file system:
If you need to switch back to the zroot/ROOT/default boot environment, select default in the boot menu, or use bectl activate default to switch to the default boot environment.
References
vermaden. ZFS Boot Environments Explained[EB/OL]. [2026-03-25]. https://vermaden.wordpress.com/2025/11/25/zfs-boot-environments-explained/. A detailed explanation of the principles and practices of ZFS boot environments, including cross-version ZFS pool compatibility solutions.
FreeBSD Project. BootEnvironments[EB/OL]. [2026-03-25]. https://wiki.freebsd.org/BootEnvironments. The official FreeBSD Wiki page on boot environments.
FreeBSD Project. zfs -- configures ZFS datasets[EB/OL]. [2026-04-14]. https://man.freebsd.org/cgi/man.cgi?query=zfs&sektion=8. Manual page for the ZFS dataset management tool, covering snapshot, clone, and rollback operations.
FreeBSD Project. zpool -- configures ZFS storage pools[EB/OL]. [2026-04-14]. https://man.freebsd.org/cgi/man.cgi?query=zpool&sektion=8. Manual page for the ZFS storage pool management tool.
FreeBSD Project. bectl -- manage ZFS boot environments[EB/OL]. [2026-04-14]. https://man.freebsd.org/cgi/man.cgi?query=bectl&sektion=8. Manual page for the ZFS boot environment management tool, covering creation, activation, and destruction of boot environments.
Last updated