Boot Environments

This page is meant to serve as an introduction to boot environments, primarily architected as expected by bectl(8)/libbe(3). The target audience is generally system administrators with pre-existing setups that are not currently operable with bectl(8), but some details are mixed-in for audiences that perhaps don't have as much experience and wish to understand how boot environments work for further manipulation.

The bare minimum required for bectl(8) to operate on your pool is a common-root dataset that all root datasets will be grouped under, e.g.

zroot
zroot/ROOT
zroot/ROOT/default

The name of the organizational dataset (“BE root”) doesn't matter; in this example, we're using “ROOT” to match the default layout created by the installer (hereby referred to as “the default layout”). zroot/ROOT/default is one boot environment (i.e. root dataset), and will show up in bectl list as default, based on the dataset name.

While already restructuring your pool, consider what you expect to be included in a boot environment and make sure your layout's structured accordingly. The default layout will exclude these paths from the boot environment by default:

/tmp
/usr/home
/usr/ports
/usr/src
/var/audit
/var/crash
/var/log
/var/mail
/var/tmp

Any path not listed should be assumed to be under the influence of the boot environment. When examining datasets, note that any dataset with a mountpoint and canmount=off (as seen by zfs get) will be included in the parent dataset, or the BE if the entire path from the dataset in question up to the top-level zroot is set to canmount=off.

In order for boot environments to be effective, you must let the zpool bootfs property control which dataset gets mounted as the root. Particularly, /etc/fstab must be purged of any / mount, and /boot/loader.conf must not be setting vfs.root.mountfrom directly.