ZFS Handbook

Installing ZFS (Linux)

Introduction

ZFS is available on Linux through the ZFS on Linux (ZoL) project. This guide provides instructions for installing and configuring ZFS on various Linux distributions, focusing on Ubuntu as an example.

Installing ZFS on Ubuntu

  1. Updating the System:

    • Before installing ZFS, ensure the system is up to date:
      sudo apt update
sudo apt upgrade

  2. Installing the ZFS Utilities:

    • Install the ZFS utilities using the package manager:
      sudo apt install zfsutils-linux
    • This command installs the necessary ZFS packages and loads the ZFS kernel modules.

  3. Verifying Installation:

    • Check if the ZFS modules are loaded:
      lsmod | grep zfs
    • The presence of zfs in the output confirms that the ZFS modules are loaded.

Installing ZFS on Other Linux Distributions

Fedora

  1. Enabling the ZFS Repository:

    • Add the ZFS repository to your system:
      sudo dnf install https://zfsonlinux.org/epel/zfs-release.el7_9.noarch.rpm

  2. Installing ZFS:

    • Install the ZFS packages:
      sudo dnf install zfs

  3. Loading ZFS Modules:

    • Load the ZFS kernel module:
      sudo modprobe zfs

Arch Linux

  1. Installing ZFS via AUR:

    • Install ZFS using an AUR helper like yay:
      yay -S zfs-dkms zfs-utils

  2. Loading ZFS Modules:

    • Load the ZFS kernel module:
      sudo modprobe zfs

Creating and Configuring ZFS Pools

Once ZFS is installed, ZFS pools can be created using the zpool command. The process is the same across Linux distributions:

  1. Creating a ZFS Pool:

    • Example for creating a pool on a single disk:
      sudo zpool create mypool /dev/sda

  2. Verifying the Pool:

    • Check the status of the pool:
      sudo zpool status

A handful of dataset properties have defaults that suit ZFS's Solaris heritage better than a modern Linux system, and nearly every Linux deployment benefits from changing them. Because dataset properties are inherited, the best time to set them is at pool creation with -O, so that every dataset created later picks them up automatically:

sudo zpool create -o ashift=12 \
    -O xattr=sa -O acltype=posixacl -O atime=off \
    -O compression=lz4 -O dnodesize=auto \
    mypool /dev/sda

What each property does:

  • xattr=sa — the xattr property controls how extended attributes are stored, and Linux uses them heavily (SELinux labels, file capabilities, ACLs). The default xattr=on stores each one as a hidden file, costing extra disk seeks on every lookup. xattr=sa stores them compactly inside the file's dnode instead, which is significantly faster for metadata-heavy workloads.
  • acltype=posixacl — the default acltype discards POSIX ACLs entirely; setting it to posixacl enables them. This matters even on single-user systems, because systemd-journald uses ACLs on /var/log/journal; without this property, persistent journal permissions do not work correctly.
  • atime=off — by default every file read triggers a metadata write to update the access time (atime), which is wasted I/O for almost all workloads. If some software genuinely needs access times, relatime=on is the middle ground, updating them at most once a day.
  • compression=lz4 — effectively free on modern CPUs and often improves performance by reducing the amount of data written; incompressible data is detected and stored as-is.
  • dnodesize=auto — lets ZFS use larger dnodes when needed, which keeps xattr=sa attributes inside the dnode even when they are numerous. The two properties are usually set together.

On an existing pool the same properties can be applied with zfs set, and child datasets inherit them from that point on. Note that changing xattr=sa only affects newly written extended attributes; existing ones remain in the old format until rewritten.

Two caveats: setting dnodesize to auto activates the large_dnode pool feature, which GRUB does not understand — leave it unset on a boot pool, or constrain the pool with the compatibility property as described in Feature Flags and Pool Compatibility. And xattr=sa attributes may not be readable if the pool is later imported on platforms other than Linux and FreeBSD.

This completes the installation and setup of ZFS on Linux. The following sections will cover fundamental ZFS concepts in more detail.

Basic Components →