> 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-13-freebsd-system-updates/di-13.4-jie-tong-guo-zfs-qi-dong-huan-jing-shi-xian-duo-ban-ben-gong-cun.md). # 13.4 Multi-Version Coexistence with ZFS Boot Environments With ZFS boot environments, multiple independent system versions can be retained on the same machine. If an upgrade fails, you can roll back to the previous state without reinstalling, thus enabling atomic updates, multi-system coexistence, and fast rollbacks. The methods described in this section only apply to systems using the ZFS file system. > **Warning** > > PkgBase and freebsd-update **must not be mixed**. Once the system is converted to PkgBase, all system updates should be performed through the pkg package manager; freebsd-update must not be used again, otherwise system component conflicts, file corruption, or an unbootable system may result. ## Creating the Boot Environment 15.0-RELEASE ZFS Boot Environments (BE) allow the creation of multiple independent system environments on a single system, enabling coexistence and safe switching between different versions. The following operation will create the boot environment 15.0-RELEASE. * Use the bectl tool to create the boot environment `15.0-RELEASE`: ```sh # bectl create 15.0-RELEASE ``` > **Note** > > The boot environment is named 15.0-RELEASE here, but the current system is still 14.3-RELEASE. * Use bectl to check the boot environments: ```sh $ bectl list # Display all boot environments BE Active Mountpoint Space Created 15.0-RELEASE - - 176K 2025-12-05 22:27 default NR / 10.6G 2025-01-14 20:36 ``` * List all ZFS file systems and their properties in the system: ```sh # zfs list NAME USED AVAIL REFER MOUNTPOINT ……Others omitted…… zroot/ROOT/15.0-RELEASE 8K 83.8G 10.6G / ……Others omitted…… ``` The `zroot/ROOT/15.0-RELEASE` line is the newly created boot environment. ## Updating the System Version in the Boot Environment to 15.0-RELEASE After creating the boot environment, you need to update it to the target version. The operation consists of four steps: mounting, verifying the version, converting to PkgBase, and upgrading. ### Mounting the Boot Environment 15.0-RELEASE Before operating on the boot environment, you must first mount it to the file system. First, create a temporary directory: * Create a temporary directory for updating the system in the boot environment 15.0-RELEASE ```sh # mkdir /mnt/upgrade ``` ```sh /mnt/ └── upgrade/ # Boot environment mount directory └── usr/ └── local/ └── etc/ └── pkg/ └── repos/ └── FreeBSD-base.conf # PkgBase source configuration file ``` * Mount the boot environment (actually a dataset) 15.0-RELEASE to the specified path ```sh # bectl mount 15.0-RELEASE /mnt/upgrade /mnt/upgrade ``` * Display disk usage of mounted file systems: ```sh # df Filesystem 1K-blocks Used Avail Capacity Mounted on ……Others omitted…… zroot/ROOT/15.0-RELEASE 99036272 11132688 87903584 11% /mnt/upgrade ……Others omitted…… ``` ### Verifying the Current FreeBSD Version This boot environment (ZFS dataset) 15.0-RELEASE is actually still 14.3-RELEASE, which can be verified using `freebsd-version`: Run `freebsd-version` in the **/mnt/upgrade** environment: ```sh # chroot /mnt/upgrade freebsd-version -kru 14.3-RELEASE 14.3-RELEASE 14.3-RELEASE ``` `freebsd-version` parameter explanation: | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-k` | Print the version and patch level of the installed kernel. Unlike uname(1), if a new kernel has been installed but the system has not yet been rebooted, `freebsd-version` will print the version and patch level of the new kernel | | `-r` | Print the version and patch level of the running kernel. Unlike uname(1), `freebsd-version` is not affected by environment variables | | `-u` | Print the version and patch level of the installed userland. This information is written into the `freebsd-version` program during the build process | ### Converting 14.3-RELEASE (System Version) in the Boot Environment to PkgBase Using PkgBase Before upgrading, the traditional FreeBSD system must be converted to the PkgBase format. PkgBase is the base system packaging method officially provided by FreeBSD, using the pkg package manager to manage system components. For the upgrade method, refer to the chapter on converting the base system with PkgBase. ### Booting into the Boot Environment 15.0-RELEASE After completing all update operations, boot into the new boot environment to verify the results. * Enter the boot environment 15.0-RELEASE on the next boot ```sh # bectl activate -t 15.0-RELEASE # Enter the boot environment 15.0-RELEASE on the next boot Successfully activated boot environment 15.0-RELEASE for next boot ``` * Verify whether the setting was successful. List all ZFS boot environments in the system: ```sh $ bectl list BE Active Mountpoint Space Created 15.0-RELEASE T /mnt/upgrade 8.75G 2025-12-05 23:22 default NR / 10.9G 2025-01-14 20:36 ``` Note that this is a one-time activation (`T`); this is only used to verify whether it can boot properly. You also need to return to the current main system 14.3-RELEASE to update ZFS. * Reboot to enter the boot environment 15.0-RELEASE ```sh # reboot # Reboot to enter the boot environment 15.0-RELEASE ``` * Verify the version: ```sh $ freebsd-version -kru 15.0-RELEASE 15.0-RELEASE 15.0-RELEASE $ bectl list BE Active Mountpoint Space Created 15.0-RELEASE N / 8.75G 2025-12-05 23:22 default R - 10.9G 2025-01-14 20:36 ``` From the output, the FreeBSD system in the boot environment 15.0-RELEASE has been successfully upgraded to 15.0-RELEASE, and the boot environment name now matches the actual version. `R` means that rebooting again will return to the boot environment `default` (14.3-RELEASE). ## Appendix: Permanently Using 15.0-RELEASE The previous section completed verification through a one-time boot environment. If verification passes and there is no need to keep the old version, the new environment can be set as the permanent default. If you do not need multi-version coexistence and have verified that the current environment meets your needs, you can also set the boot environment 15.0-RELEASE as permanent: ```sh # bectl activate 15.0-RELEASE ``` Afterwards, you can also destroy boot environments that are no longer needed: ```sh # bectl destroy name-of-boot-environment-to-destroy ``` Replace the parameter `name-of-boot-environment-to-destroy` with the boot environment name corresponding to the `BE` column in the output of the `bectl list` command to destroy it. ### Replacing ZFS in the Base System with the Ports Version Readers who need multi-version coexistence can directly reboot into the boot environment `default` (14.3-RELEASE) and upgrade the OpenZFS version in 14.3-RELEASE. For upgrade details, refer to other relevant chapters. > **Warning** > > If you forcibly upgrade the ZFS pool/features without updating to the Ports version, you will not be able to access the old system. ## References * vermaden. ZFS Boot Environments Explained\[EB/OL]. \[2026-03-25]. . 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]. . Official FreeBSD Wiki page on boot environments. * FreeBSD Project. bectl(8)\[EB/OL]. \[2026-03-25]. . Official technical specification for the ZFS boot environment management tool. --- # 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-13-freebsd-system-updates/di-13.4-jie-tong-guo-zfs-qi-dong-huan-jing-shi-xian-duo-ban-ben-gong-cun.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.