Installing ZFS (FreeBSD)

Introduction

FreeBSD natively supports ZFS, and the file system is deeply integrated into the operating system. This guide will walk through the steps required to install and configure ZFS on a FreeBSD system.

Installing FreeBSD with ZFS

Starting the FreeBSD Installer:
- Boot the system from a FreeBSD installation medium.
- Follow the initial setup prompts until the "Partitioning" screen is reached.
Choosing ZFS as the Root File System:
- On the "Partitioning" screen, select Auto (ZFS).
- Choose the disk or disks to be included in the ZFS pool.
- Configure the pool options, such as RAID level (if applicable), and proceed with the installation.
Post-Installation Configuration:
- Once the installation is complete, the system will reboot into FreeBSD with ZFS as the root file system.
- Verify that ZFS is active by running:
```
zpool status
```
- This command should display information about the root pool (zroot) and any configured datasets.

Installing ZFS on an Existing FreeBSD System

For users who already have FreeBSD installed and wish to add ZFS:

Installing the ZFS Packages:
- Ensure the system is updated:
```
sudo freebsd-update fetch install
sudo pkg update
```
- Install the ZFS utilities:
```
sudo pkg install zfs
```
Loading ZFS Kernel Modules:
- Load the ZFS kernel module manually:
```
sudo kldload zfs
```
- To load ZFS automatically at boot, add the following to /etc/rc.conf:
```
zfs_enable="YES"
```
Creating and Configuring ZFS Pools:
- ZFS pools can now be created and managed using the zpool command.
- For example, to create a simple pool on a single disk:
```
sudo zpool create mypool /dev/ada1
```
- Verify the creation of the pool:
```
zpool status
```

Boot Environments

One of the most practical benefits of installing FreeBSD on ZFS is boot environments. A boot environment is a bootable clone of the root filesystem: before a risky change — a freebsd-update release upgrade, a large package migration, a kernel patch — a new environment is created in seconds, and if the change goes wrong, the machine simply boots back into the previous environment exactly as it was. This works because the installer places the root filesystem in its own dataset under zroot/ROOT (named default); each boot environment is another dataset there, and the bootloader points at whichever one is active.

FreeBSD ships the bectl utility for managing boot environments. To see the existing environments:

sudo bectl list
BE      Active Mountpoint Space Created
default NR     /          2.06G 2026-01-12 09:15

In the Active column, N marks the environment running now and R the one that will be used on reboot. The typical workflow is to create a new environment immediately before any significant system change:

sudo bectl create pre-upgrade
sudo freebsd-update -r 14.2-RELEASE upgrade

If the upgraded system misbehaves, the previous state can be restored in either of two ways: by choosing the old environment from the Boot Environments entry in the loader menu at startup, which boots it once without making the choice permanent, or from the running system by activating it and rebooting:

sudo bectl activate pre-upgrade

Activating only selects which environment boots by default; both continue to exist until one is explicitly destroyed. Once an upgrade has proven itself, old environments can be removed to reclaim their space:

sudo bectl destroy pre-upgrade

Key points:

Boot environments are ZFS clones, so creating one is instant and consumes almost no space; the cost grows only as the environments diverge.
Only the datasets under zroot/ROOT belong to a boot environment. User data such as home directories lives in separate datasets, so booting an older environment rolls back the operating system without touching user files.
Boot environments are not built into ZFS on Linux, but the zectl tool and the ZFSBootMenu bootloader provide an equivalent workflow for Linux systems with a ZFS root.

This concludes the installation and initial setup of ZFS on FreeBSD. The next sections will cover basic concepts and more advanced configurations.