ZFS Boot Environment Introduction


The boot environment (or BE) is a consequence of booting from ZFS. ZFS mounts the selected BE and loads everything from there. Even if you've never explicitly created a boot environment, by booting from ZFS, you're using one - the 'default' boot environment.

To take advantage of BEs, you must at some point create at least one additional BE and then switch to using that BE.

BEs allow you to make drastic changes inside one BE while leaving another clean BE as a fallback should things go awry. It is important to understand the BEs are separate from each other in that changes to one BE has no effect on the others. You can create two identical BEs A and B. If you edit a file on BE "A" and switch to "B" - those edits aren't available in "B". Likewise, you can delete a file in "B", switch to "A", and the file still appears on "A".

Obviously, you must have installed FreeBSD with ZFS as the boot partition to make use of BEs.

The ZFS command bectl combined with judicious use of reboot is all you need to manage BEs. The work flow becomes:


Here are some exercises to get you comfortable with using BEs.


# bectl list
(verify your current BE is named 'default')
# bectl create lab


Boot into this new BE by activating it and re-booting.

# bectl activate lab
# reboot

Make Changes

Log in as root and use your favorite editor to create a text file called "belab.txt".

TODO: clarify where in the hierarchy this works. BEs do not protect /var/log /var/tmp /var/mail /var/audit /tmp /mail /home /usr/ports or /usr/src.

# vi ~/belab.txt

Put some meaningful text in there. Something that shows you wrote it. Save and exit from the editor.

Install a binary package. For example, the text editor 'micro':

# pkg install micro

Verify the text file is there:

# cat ~/belab.txt

Verify the 'micro' package is installed.

# pkg info micro

Go Back

# bectl list
(verify spelling of your default BE)
# bectl activate default
# reboot

Check for Changes

Log back in as root and look for the pkg 'micro' and your text file 'belab.txt'.

# cat ~/belab.txt
# pkg info micro

Lab Cleanup

Let's clean up after ourselves by destroying the toy BE created above.

# bectl list
(verify spelling of the BE to be removed)
# bectl destroy -o lab


bectl was inspired by the Bourne shell script beadm contributed by FreeBSD ports contributor Slawomir Wojciech Wojtczak (vermaden). The syntax for beadm and bectl are nearly identical. beadm was inspired by the Solaris utility of the same name.

Thank you vermaden!

See Also




BE Details

Upgrade Freebsd with ZFS Boot Environments

Safely Upgrade

This page describes how to leverage BEs to manage upgrading FreeBSD.

Base Upgrade

Try All The X Environments

This pages describes how to leverage BEs to test out a dozen or more X.org Window Managers and Desktop Environments

X: Try Them All


unitrunker/BE (last edited 2021-02-24T08:00:53+0000 by unitrunker)