ZFS boot environments with bectl: a rollback path around FreeBSD and package upgrades

Goal

Create a ZFS boot environment before a risky change on FreeBSD 14.x with Root-on-ZFS, activate a different one after testing, and remove environments that are no longer needed.

Prerequisites

A Root-on-ZFS installation (datasets live under zroot/ROOT, with the running system typically in zroot/ROOT/default); root access; bectl(8) present (base system tool, no package install needed).

Steps

1. Before a major change — an operating system upgrade or a large package upgrade — create a new environment: bectl create beforeupgrade. The FreeBSD Handbook describes creating a boot environment as snapshotting and cloning the root datasets, which "completes in seconds and consumes almost no space until the environments start to diverge." On a boot-environment-capable ZFS root, freebsd-update install also creates one automatically unless CreateBootEnv no is set in /etc/freebsd-update.conf; a named one is still easier to find.
2. Confirm it exists and see which environment is active: bectl list. The Active column marks the environment in use now with N and the one that will be active on the next reboot with R.
3. Perform the upgrade as usual — freebsd-update install or pkg upgrade — which modifies the currently active environment while beforeupgrade is left untouched.
4. If the upgraded system fails to boot or misbehaves, reboot and select beforeupgrade from the "Boot Environments" menu presented by the FreeBSD loader; selecting it there affects only the current boot.
5. To make that rollback permanent instead of re-selecting it at every boot, activate it: bectl activate beforeupgrade. bectl(8) documents activate as setting the given environment as the default boot filesystem. bectl activate -t beforeupgrade activates it for the next boot only, which is useful for testing a rollback on a remote system without committing to it.
6. To inspect or repair an inactive environment without booting it, mount it: bectl mount beforeupgrade, work under the printed temporary path, then bectl umount beforeupgrade.
7. Once an environment is confirmed unneeded, reclaim its space: bectl destroy beforeupgrade. bectl(8) notes this destroys the environment "without confirmation," unlike the older beadm tool, so double-check the name first with bectl list.

Expected result

bectl list shows the new environment immediately after create, with a Space value of only kilobytes; after activate and reboot, bectl list shows it marked NR.

Limits and test basis

A boot environment contains only the datasets under zroot/ROOT. On the default layout that includes /usr/local and /var/db, so installed packages roll back together with the base system — and so does application data kept there (a database under /var/db, for example), which activating an older environment silently returns to its older state. Datasets outside zroot/ROOT (zroot/home, zroot/var/log, zroot/var/mail) are shared by all environments and never rolled back; the Handbook recommends giving data that must survive a rollback its own dataset outside zroot/ROOT. Boot environments live on the same pool and are not a backup.