One of the many nice features of ZFS on FreeBSD is the ability to create boot environments. Before doing an upgrade, or making some important change, you can create a boot environment, and then, if, after the upgrade or other change, something is broken, you can get back to what was working before with very little effort.

FreeBSD has bectl with the system, and vermaden has also written beadm. (The link goes to vermaden's main site which is full of good things).

Mike Lucas, who always writes great documentation, has an article on using beadm. For my fairly straightforward use, the two are almost identical and the reader can substitute bectl for beadm, in following the Mike Lucas article. (I do remember, quite some time ago, bectl not doing something correctly, while beadm did it without problem, but that was so long ago, I've forgotten what the issue was).

Much of this is a rehash of the Mike Lucas post, with a few additions, probably because he figured they were too obvious to be mentioned, though I'm using bectl rather than beadm in this article.

So, if you are about to make a possibly breaking change on your system, first create a boot environment of the working one. You can name it what you want, I usually use working and the date. You must be root or have root privilege.

bectl create working-$(date +%F)

Now doing bectl list might show

ctive Mountpoint Space Created default NR / 13.4G 2024-03-09 17:43 working-20250902 - - 11.3M 2025-09-02 17:11

The NR means that it's the one running now and the one that will be used on reboot.

Mike Lucas suggests creating a new environment for an upgrade in his example, and fix it so it will be active on the next boot. Something like

bectl create newboot bectl activate newboot

If you do this, and run bectl list you will see the R next to the newboot environment, meaning it will be used upon reboot.

Anyway, let's say we do our upgrade and something went wrong. Suddenly your main user doesn't have their home directory. You can just go back to the old system.

On boot, there is choice 8, boot environments. Select it and you're taken to another menu. Item one is hit backspace to go back to main menu, item 2 is the important one. It will say Active and list the name of the boot environment, probably zfs:zroot/ROOT/default if you stick with defaults. That's the boot environment that got messed up by your upgrade. Now, hit 2 and it should show your working-$(date +%F) boot environment. Select that one, and then hit enter. It should now boot back into the system you had before you ran that update. If you have more boot environments, you can cycle through them by hitting 2 and and it will show each one. This feature is obviously quite useful when making changes on your system and removes a lot of the risk from upgrading.