Building ZFS

GitHub Repositories

The official source for OpenZFS is maintained at GitHub by the openzfs organization. The primary git repository for the project is the zfs repository.

There are two main components in this repository:

  • ZFS: The ZFS repository contains a copy of the upstream OpenZFS code which has been adapted and extended for Linux and FreeBSD. The vast majority of the core OpenZFS code is self-contained and can be used without modification.

  • SPL: The SPL is a thin shim layer which is responsible for implementing the fundamental interfaces required by OpenZFS. It’s this layer which allows OpenZFS to be used across multiple platforms. SPL used to be maintained in a separate repository, but was merged into the zfs repository in the 0.8 major release.

Installing Dependencies

The first thing you’ll need to do is prepare your environment by installing a full development tool chain. In addition, development headers for both the kernel and the following packages must be available. It is important to note that if the development kernel headers for the currently running kernel aren’t installed, the modules won’t compile properly.

The following dependencies should be installed to build the latest ZFS 2.1 release.

  • RHEL/CentOS 7:

sudo yum install epel-release gcc make autoconf automake libtool rpm-build libtirpc-devel libblkid-devel libuuid-devel libudev-devel openssl-devel zlib-devel libaio-devel libattr-devel elfutils-libelf-devel kernel-devel-$(uname -r) python python2-devel python-setuptools python-cffi libffi-devel git ncompress libcurl-devel
sudo yum install --enablerepo=epel python-packaging dkms

  • RHEL/CentOS 8, Fedora:

sudo dnf install --skip-broken epel-release gcc make autoconf automake libtool rpm-build libtirpc-devel libblkid-devel libuuid-devel libudev-devel openssl-devel zlib-devel libaio-devel libattr-devel elfutils-libelf-devel kernel-devel-$(uname -r) python3 python3-devel python3-setuptools python3-cffi libffi-devel git ncompress libcurl-devel
sudo dnf install --skip-broken --enablerepo=epel --enablerepo=powertools python3-packaging dkms

  • Debian, Ubuntu:

sudo apt install alien autoconf automake build-essential debhelper-compat dh-autoreconf dh-dkms dh-python dkms fakeroot gawk git libaio-dev libattr1-dev libblkid-dev libcurl4-openssl-dev libelf-dev libffi-dev libpam0g-dev libssl-dev libtirpc-dev libtool libudev-dev linux-headers-generic parallel po-debconf python3 python3-all-dev python3-cffi python3-dev python3-packaging python3-setuptools python3-sphinx uuid-dev zlib1g-dev

  • FreeBSD:

pkg install autoconf automake autotools git gmake python devel/py-sysctl sudo

Build Options

There are two options for building OpenZFS; the correct one largely depends on your requirements.

  • Packages: Often it can be useful to build custom packages from git which can be installed on a system. This is the best way to perform integration testing with systemd, dracut, and udev. The downside to using packages it is greatly increases the time required to build, install, and test a change.

  • In-tree: Development can be done entirely in the SPL/ZFS source tree. This speeds up development by allowing developers to rapidly iterate on a patch. When working in-tree developers can leverage incremental builds, load/unload kernel modules, execute utilities, and verify all their changes with the ZFS Test Suite.

The remainder of this page focuses on the in-tree option which is the recommended method of development for the majority of changes. See the custom packages page for additional information on building custom packages.

Developing In-Tree

Clone from GitHub

Start by cloning the ZFS repository from GitHub. The repository has a master branch for development and a series of *-release branches for tagged releases. After checking out the repository your clone will default to the master branch. Tagged releases may be built by checking out zfs-x.y.z tags with matching version numbers or matching release branches.

git clone https://github.com/openzfs/zfs

Configure and Build

For developers working on a change always create a new topic branch based off of master. This will make it easy to open a pull request with your change latter. The master branch is kept stable with extensive regression testing of every pull request before and after it’s merged. Every effort is made to catch defects as early as possible and to keep them out of the tree. Developers should be comfortable frequently rebasing their work against the latest master branch.

In this example we’ll use the master branch and walk through a stock in-tree build. Start by checking out the desired branch then build the ZFS and SPL source in the traditional autotools fashion.

cd ./zfs
git checkout master
sh autogen.sh
./configure
make -s -j$(nproc)
tip: --with-linux=PATH and --with-linux-obj=PATH can be passed to configure to specify a kernel installed in a non-default location.
tip: --enable-debug can be passed to configure to enable all ASSERTs and additional correctness tests.

Optional Build packages

make rpm #Builds RPM packages for CentOS/Fedora
make deb #Builds RPM converted DEB packages for Debian/Ubuntu
make native-deb #Builds native DEB packages for Debian/Ubuntu
tip: Native Debian packages build with pre-configured paths for Debian and Ubuntu. It’s best not to override the paths during configure.
tip: For native Debian packages, KVERS, KSRC and KOBJ environment variables can be exported to specify the kernel installed in non-default location.

Note

Support for native Debian packaging will be available starting from openzfs-2.2 release.

Install

You can run zfs-tests.sh without installing ZFS, see below. If you have reason to install ZFS after building it, pay attention to how your distribution handles kernel modules. On Ubuntu, for example, the modules from this repository install in the extra kernel module path, which is not in the standard depmod search path. Therefore, for the duration of your testing, edit /etc/depmod.d/ubuntu.conf and add extra to the beginning of the search path.

You may then install using sudo make install; sudo ldconfig; sudo depmod. You’d uninstall with sudo make uninstall; sudo ldconfig; sudo depmod. You can install just the kernel modules with sudo make -C modules/ install.

Running zloop.sh and zfs-tests.sh

If you wish to run the ZFS Test Suite (ZTS), then ksh and a few additional utilities must be installed.

  • RHEL/CentOS 7:

sudo yum install ksh bc bzip2 fio acl sysstat mdadm lsscsi parted attr nfs-utils samba rng-tools pax perf
sudo yum install --enablerepo=epel dbench

  • RHEL/CentOS 8, Fedora:

sudo dnf install --skip-broken ksh bc bzip2 fio acl sysstat mdadm lsscsi parted attr nfs-utils samba rng-tools pax perf
sudo dnf install --skip-broken --enablerepo=epel dbench

  • Debian:

sudo apt install ksh bc bzip2 fio acl sysstat mdadm lsscsi parted attr dbench nfs-kernel-server samba rng-tools pax linux-perf selinux-utils quota

  • Ubuntu:

sudo apt install ksh bc bzip2 fio acl sysstat mdadm lsscsi parted attr dbench nfs-kernel-server samba rng-tools pax linux-tools-common selinux-utils quota

  • FreeBSD:

pkg install base64 bash checkbashisms fio hs-ShellCheck ksh93 pamtester devel/py-flake8 sudo

There are a few helper scripts provided in the top-level scripts directory designed to aid developers working with in-tree builds.

  • zfs-helper.sh: Certain functionality (i.e. /dev/zvol/) depends on the ZFS provided udev helper scripts being installed on the system. This script can be used to create symlinks on the system from the installation location to the in-tree helper. These links must be in place to successfully run the ZFS Test Suite. The -i and -r options can be used to install and remove the symlinks.

sudo ./scripts/zfs-helpers.sh -i

  • zfs.sh: The freshly built kernel modules can be loaded using zfs.sh. This script can later be used to unload the kernel modules with the -u option.

sudo ./scripts/zfs.sh

  • zloop.sh: A wrapper to run ztest repeatedly with randomized arguments. The ztest command is a user space stress test designed to detect correctness issues by concurrently running a random set of test cases. If a crash is encountered, the ztest logs, any associated vdev files, and core file (if one exists) are collected and moved to the output directory for analysis.

sudo ./scripts/zloop.sh

  • zfs-tests.sh: A wrapper which can be used to launch the ZFS Test Suite. Three loopback devices are created on top of sparse files located in /var/tmp/ and used for the regression test. Detailed directions for the ZFS Test Suite can be found in the README located in the top-level tests directory.

./scripts/zfs-tests.sh -vx

tip: The delegate tests will be skipped unless group read permission is set on the zfs directory and its parents.