> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/ask/flat/chapter-28-the-zfs-file-system/di-28.9-jie-zfs-qi-dong-huan-jing.md).
# 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]. ), 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:
```sh
# 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:
```sh
# zpool upgrade ZFS_pool_name
```
## Basic Usage of Boot Environments
In a default installation, `zroot/ROOT/default` is the default boot environment.
Create a ZFS snapshot example:
```sh
# zfs snap zroot/ROOT/default@new # Create snapshot new for the zroot/ROOT/default file system
```
Use the newly created snapshot to generate a clone file system:
```sh
# zfs clone zroot/ROOT/default@new zroot/ROOT/new # Create a new writable ZFS clone file system zroot/ROOT/new based on the zroot/ROOT/default@new snapshot
```
The generated clone file system can serve as a boot environment. You can use the `bectl` tool to list all ZFS Boot Environments:
```sh
# bectl list
BE Active Mountpoint Space Created
0915 - - 4.00M 2023-09-19 19:44
13.2-RELEASE-p2_2023-09-13_141111 - - 29.0M 2023-09-13 14:11
new - - 432K 2023-09-20 15:17
default NR / 40.8G 2023-04-10 10:06
```
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:
```sh
# bectl activate new
Successfully activated boot environment new
```
Use `bectl list` again to view all ZFS Boot Environments and observe the changes in the Active column:
```sh
# bectl list
BE Active Mountpoint Space Created
0915 - - 4.00M 2023-09-19 19:44
13.2-RELEASE-p2_2023-09-13_141111 - - 29.0M 2023-09-13 14:11
new R / 2.84M 2023-09-20 15:17
default N - 40.8G 2023-04-10 10:06
```
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:
```sh
# df
Filesystem 1K-blocks Used Avail Capacity Mounted on
zroot/ROOT/new 110611616 42612156 67999460 39% /
devfs 1 1 0 100% /dev
/dev/gpt/efiboot0 266176 1872 264304 1% /boot/efi
fdescfs 1 1 0 100% /dev/fd
```
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]. . 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]. . The official FreeBSD Wiki page on boot environments.
* FreeBSD Project. zfs -- configures ZFS datasets\[EB/OL]. \[2026-04-14]. . 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]. . Manual page for the ZFS storage pool management tool.
* FreeBSD Project. bectl -- manage ZFS boot environments\[EB/OL]. \[2026-04-14]. . Manual page for the ZFS boot environment management tool, covering creation, activation, and destruction of boot environments.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://book.bsdcn.org/ask/flat/chapter-28-the-zfs-file-system/di-28.9-jie-zfs-qi-dong-huan-jing.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.