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 can list available boot environments. No running system is required — this works even if the current environment will not boot.

To select a boot environment:

1. Restart the machine
2. Press Spacebar during the bootloader countdown to interrupt it
3. Press 8 to access the Boot Environments menu
4. Press 2 to cycle through available environments
5. Press Enter to boot the selected one

The omfreebdy installer creates a proper zroot/ROOT/default dataset layout, which is required for the bootloader to detect and list boot environments.

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.