Ctrlk
VitePress 镜像站QQ 群 787969044视频教程Ⅰ视频教程Ⅱ
discord
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

# 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:

$ 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:

# 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

  • Mount the boot environment (actually a dataset) 15.0-RELEASE to the specified path

  • Display disk usage of mounted file systems:

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:

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

  • Verify whether the setting was successful. List all ZFS boot environments in the system:

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

  • Verify the version:

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:

Afterwards, you can also destroy boot environments that are no longer needed:

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

Previous13.3 Updating the Base System with PkgBaseNext14.1 Users and Basic Account Management

Last updated