Synopsis #
A ZFS boot environment is a bootable clone of the root filesystem datasets managed by bectl. It can preserve the earlier root state across an update or configuration change. It does not protect data on unrelated datasets, another pool, or another host, and it is not a backup.
This procedure assumes that bectl check succeeds and that a known boot environment existed before the failure. It does not attempt pool repair or manual recovery-media imports.
Confirm that boot environments apply #
On a running host, check support and list the environments:
# bectl check
$ bectl list
The Active column uses N for the environment active now, R for the environment selected on reboot, and NR for both. Record the exact names. Do not select an environment only because it appears older; it must be a known recovery point for the failed change.
Before future high-risk maintenance, create and confirm a recursive environment:
# bectl create -r pre-change
$ bectl list
The 15.1 upgrade checklist uses this boundary before changing the base system.
Boot an earlier environment once #
When the host still boots far enough to run bectl, activate the recovery environment for only the next boot:
# bectl activate -t pre-change
$ bectl list
# shutdown -r now
Temporary activation limits the change to one boot. If that boot fails or the host is restarted again without permanent activation, the normal bootfs selection remains available.
When the current environment does not boot, use the FreeBSD loader’s Boot Environments menu to select the known earlier environment. Console access is required. Loader presentation varies by platform, so confirm the selected environment name before continuing the boot.
Verify before making recovery permanent #
After booting the earlier environment, confirm which root is active and inspect the system:
$ bectl list
$ freebsd-version -kru
$ zpool status
# service service-name status
Replace service-name with every essential service. Also verify network access, firewall behavior, storage mounts, scheduled jobs, and the data needed by the workload.
Data on separate datasets may still reflect changes made after the boot environment was created. Do not assume that application state, jail data, databases, or home directories were rolled back with the root environment. The ZFS snapshot and replication guide explains the separate dataset boundary.
If the recovered environment is the desired root, activate it persistently:
# bectl activate pre-change
$ bectl list
Perform another controlled reboot and verify it again.
Preserve the failed environment for diagnosis #
Do not immediately destroy the failed environment. It may contain configuration changes, logs, package state, or files needed to explain the failure. It can be mounted temporarily at an explicit empty directory:
# mkdir /mnt/failed-be
# bectl mount failed-environment /mnt/failed-be
Replace failed-environment with the recorded name. Treat the mounted tree as evidence. Avoid running its services or writing into it during comparison. Unmount it when finished:
# bectl unmount failed-environment
Destroying a boot environment is intentionally outside this recovery procedure because it is irreversible and space accounting can be surprising when snapshots and clones share blocks.
Know when this procedure is insufficient #
A boot environment does not solve:
- pool corruption or failed storage devices;
- a boot loader that cannot read the root pool;
- loss of the disk or host;
- application inconsistency across separate datasets;
- a missing pre-change environment;
- an unsupported release that still requires a planned upgrade.
Those cases require pool, boot-loader, application, or backup recovery appropriate to the failure. Do not use zfs rollback on the root dataset as a substitute for identifying those boundaries.
Use Diagnose the FreeBSD boot path when the failing stage has not yet been established or the loader cannot reach the boot-environment selection.