Upgrade like you can undo it, because with bectl you can

Here is the difference between an upgrade you dread and an upgrade you shrug at: whether you can get back to five minutes ago without a USB stick and a prayer.

On FreeBSD with root-on-ZFS, you can. A boot environment is a bootable clone of your root dataset — the whole system, as it is right now, snapshotted and made independently bootable. Make one before you touch anything, and the worst case for a bad kernel or a broken pkg upgrade stops being “boot the install media and chroot around in the dark” and becomes “reboot, pick the old one.” That’s the entire pitch. It is also, quietly, one of the best reasons root-on-ZFS exists.

The one command you run before every upgrade

bectl create pre-upgrade-$(date +%Y%m%d)

That snapshots your current root dataset and clones it into a new boot environment. It is nearly instant and nearly free — ZFS clones share every unchanged block, so the new BE costs you only what later diverges from it. You are not copying the system. You are bookmarking it.

List what you’ve got:

bectl list

BE                    Active Mountpoint Space Created
default               NR     /          12.3G 2026-06-01 09:14
pre-upgrade-20260807  -      -          8.00K 2026-08-07 22:40

N is what’s booted now, R is what boots next. Right now they’re the same environment. The new BE is 8K because nothing has diverged yet. Now go do the dangerous thing.

Then wreck the system on purpose

Run your freebsd-update and pkg upgrade. Reboot into the upgraded default. If it comes up clean and you’re happy — you’re done, the pre-upgrade BE just sits there costing you the delta until you destroy it. If it doesn’t come up clean — a kernel panic, a driver that hates your NIC, a pkg upgrade that ate a library half the base depends on — you don’t debug it at 11pm. You go back.

bectl activate pre-upgrade-20260807
reboot

activate sets that BE as the default for next boot. Reboot and you are exactly where you were before the upgrade, down to the block. Then you debug the broken one on your own schedule, awake, with coffee — not as an incident where the only recovery tool is the box you just broke.

The loader trick for when it won’t even boot

bectl activate is great when the running system still works. But the real nightmare is the upgrade that won’t boot at all — no shell to run bectl in.

FreeBSD’s loader has you covered, and this is the part people don’t know until they need it. At the boot menu, there’s a Boot Environments submenu. You can pick any BE to boot from the loader itself, before the kernel it’s broken on ever loads. Select pre-upgrade-20260807, hit enter, and you’re booting the old system with zero working userland required. The rollback path does not depend on the thing you broke. That’s the whole design, and it’s the reason this beats every “just keep backups” answer: a backup you have to restore is a project; a boot environment you select at the loader is a keystroke.

Test a kernel without committing to it

Use temporary activation when you want to try a BE for exactly one boot:

bectl activate -t upgrade-test
reboot

-t activates for the next boot only. If upgrade-test is good, bectl activate upgrade-test to make it stick. If it’s bad, just reboot again — with no permanent activation, you fall straight back to your previous default. You get to audition a kernel with an automatic undo. Solaris folks have been smug about this since before some of you had root; FreeBSD’s bectl is the same idea, and yes, I’ll say it: it’s good.

Patch a broken BE without booting it

You can mount a boot environment and fix it in place — reinstall a package, repair /etc, whatever — without making it the running system:

bectl mount upgrade-test /mnt
# poke around, chroot /mnt if you need to, fix the thing
bectl umount upgrade-test

That’s how you repair the upgrade that failed while you sit comfortably in the BE that works.

The boring operational version

1. bectl create pre-upgrade-<date> before any freebsd-update or pkg upgrade.
2. Do the upgrade. Reboot into it.
3. Good? Carry on; destroy the old BE later with bectl destroy.
4. Bad but bootable? bectl activate <old-be> && reboot.
5. Bad and won’t boot? Loader → Boot Environments → pick the old one.
6. Auditioning a kernel? bectl activate -t and let a plain reboot be your undo.
7. Keep the list clean — bectl destroy the ones you’ve stopped trusting, so the menu stays readable when you’re panicking.

An upgrade is only frightening if it’s a one-way door. Boot environments turn it into a revolving one. Make the BE, take the swing, and stop treating pkg upgrade like a restart you’re hoping fixes something — treat it like a move you can take back.

The greybeards who never fear an upgrade aren’t braver than you. They just made the snapshot first.