Boot Environments

BE-01 // BOOT ENVIRONMENTS

A boot environment (BE) is a ZFS clone of your root filesystem. You can create one before any risky operation, then roll back to it instantly — without a live USB, without reinstalling, without restoring from backup.

omfreebdy auto-creates a boot environment before every system update.

What Gets Cloned

A boot environment captures the root pool at the moment of creation: the base system, all installed packages, and system configuration. Your home directory is a separate dataset and is not included.

zpool list
# NAME    SIZE  ALLOC   FREE  ...
# zroot   120G  18.4G  101G  ...

zfs list -t snapshot
# zroot/ROOT/default@before-update-2026-03-20  1.2G
# zroot/ROOT/default@before-experiment         890M

Commands

boot-env create

boot-env create <name>

Creates a ZFS snapshot and registers it as a bootable environment. Name should be descriptive.

boot-env create before-nvidia-driver
boot-env create before-pkg-upgrade
boot-env create working-state

boot-env list

boot-env list

NAME                          ACTIVE  MOUNTPOINT  CREATED
default                       *       /           2026-01-15
before-nvidia-driver                  -           2026-02-10
before-pkg-upgrade                    -           2026-03-01
working-state                         -           2026-03-18

The * marks the currently booted environment.

boot-env rollback

boot-env rollback <name>

Activates the named environment as the next boot target. Reboot to complete the rollback.

boot-env rollback before-nvidia-driver
sudo reboot

Rollback does not destroy other environments. You can switch between boot environments at any time. Delete old ones when you no longer need them.

boot-env delete

boot-env delete <name>

Destroys the ZFS snapshot and removes the environment from the bootloader menu.

Keybinding

Shortcut	Action
`Super` + `Ctrl` + `S`	Create boot environment with timestamp

Waybar Module

The Waybar status bar includes a boot environment indicator. It shows the name of the currently active environment and turns amber if the current BE has no recent snapshot.

Click the module to open a terminal with boot-env list.

Automatic Snapshots

mise run update creates a boot environment automatically:

mise run update
# [BE] Creating boot environment: before-update-2026-03-20
# [pkg] Updating package repository...
# [pkg] Upgrading 12 packages...
# [omfreebdy] Pulling latest configs...
# Done. Revert with: boot-env rollback before-update-2026-03-20

If the update breaks something, roll back before the next reboot or select the previous environment from the bootloader menu.

Bootloader Selection

At startup, the FreeBSD bootloader shows available boot environments. Use the arrow keys to select one before the OS loads — no running system required.

This means you can recover from a broken update even if the system will not boot:

Restart the machine
Interrupt the bootloader countdown
Select the last known-good boot environment
Boot into it

Boot environments protect against OS-level breakage. They do not replace backups. Home directory changes, database contents, and application data are not captured in a BE.

No Linux Equivalent

Why this doesn't exist on Linux by default

ZFS boot environments require the bootloader to understand ZFS datasets, which FreeBSD’s bootloader (loader) has done since FreeBSD 9. GRUB on Linux added ZFS support later and it remains fragile — dataset naming conventions differ, and most distributions do not configure it automatically.

Tools like btrfs-assistant and snapper provide similar functionality for Btrfs, but they require manual setup, are distribution-specific, and are not integrated into the bootloader the same way.

On FreeBSD, boot environments work at install time with zero configuration if you select ZFS during the FreeBSD installer.