ZFS boot environments

freebsd 15 / published / guide #14 / ≈ 2 min read

If you installed FreeBSD on its default filesystem (ZFS), you have a powerful safety net built in: boot environments, or "BEs." A BE is a complete alternate copy of the system you can boot into — useful for trying an upgrade without committing to it.

What's ZFS, briefly? A modern filesystem with snapshots, integrity checking, and compression all built in. It's the standard on FreeBSD.

What's a boot environment? Imagine you clone your entire system to a parallel copy in a fraction of a second. You can then experiment on either copy; if you ruin one, boot the other. That's a BE.

Step 1: See your existing BEs

bectl list

On a fresh install you'll see one: default, marked active and "now booted." That's the system you're currently running.

Step 2: Make a snapshot before doing anything risky

Say you're about to run freebsd-update to install patches:

sudo bectl create pre-upgrade

That created a BE called pre-upgrade — a complete copy of the system as it is right now. It took maybe a second and almost no disk space (ZFS only stores differences).

Step 3: Run your upgrade

Now do whatever you were going to do:

sudo freebsd-update fetch
sudo freebsd-update install
sudo pkg upgrade

Step 4: If things broke, roll back

sudo bectl activate pre-upgrade
sudo shutdown -r now

Reboot and you're back to the system as it was before the upgrade. The post-upgrade BE is still around in case you want to compare or pick something out of it.

You can also pick a BE from the loader menu at boot — press Space when the boot screen appears, then "Boot environments."

Step 5: When you're happy, clean up

sudo bectl destroy pre-upgrade

This frees the disk space the snapshot was holding.

Other useful tricks

Mount a BE without booting into it — useful for grabbing a single file:

sudo bectl mount default /mnt
ls /mnt/etc
sudo bectl umount default

Rename a BE:

sudo bectl rename pre-upgrade pre-2026-05-15

Clone an existing BE — useful for staging an experiment without touching the live system:

sudo bectl create -e default experimental

The workflow, in summary

  1. Before any big change, bectl create.
  2. Do the thing.
  3. If it broke, bectl activate the old one and reboot.
  4. If it's fine, bectl destroy the snapshot you don't need.

This is one of FreeBSD's nicest comforts — the ability to undo system-level changes without learning a separate backup tool.

← back to index