OpenZFS*¶
This tutorial shows how to set up OpenZFS* file system and volume manager on Clear Linux* OS, using a non-root device for zpools.
Background¶
The OpenZFS storage platform provides volume management, snapshot capabilities, and redundancy detection. Clear Linux OS does not ship with a binary ZFS kernel module (zfs.ko). Clear Linux OS users who wish to incorporate the zfs.ko kernel module must build and maintain this work themselves.
Caution
Use of the OpenZFS kernel module in connection with Clear Linux OS is neither recommended nor officially endorsed by the Clear Linux* Project. Users who follow this tutorial and build zfs.ko kernel module are encouraged to seek independent legal counsel regarding any plan to redistribute a software package containing zfs.ko and Clear Linux OS.
Known Issues¶
Using a long-term-support (LTS) kernel when running OpenZFS reduces the risk of incompatibilities with kernel updates. When new kernels or new versions of OpenZFS are released, users bear the responsibility to test those releases and ensure compatibility before deploying any updates.
Prerequisites¶
Learn to Add kernel modules with DKMS
Learn to use swupd
Install the DKMS kernel¶
Install the kernel-native-dkms or kernel-lts-dkms bundle.
Determine which kernel variant is running on Clear Linux OS. Only the native and lts kernels are enabled to build and load out-of-tree kernel modules with DKMS.
$ uname -r 5.XX.YY-ZZZZ.native
Ensure .native or .lts is in the kernel name.
Install the DKMS bundle corresponding to the installed kernel. Use kernel-native-dkms for the native kernel or kernel-lts-dkms for the lts kernel.
sudo swupd bundle-add kernel-native-dkms
or
sudo swupd bundle-add kernel-lts-dkms
Update the Clear Linux OS bootloader and reboot, and ensure that you can start the new kernel.
sudo clr-boot-manager update reboot
Bundles¶
Before installing OpenZFS, install the bundles that contain the build dependencies.
sudo swupd bundle-add wget devpkg-openssl devpkg-util-linux
Install¶
Download OpenZFS release¶
In this section, we download release 2.0.0 directly from the OpenZFS repository (the latest available as of the latest revision of this page).
Download release 2.0.0
cd /usr/src sudo wget https://github.com/openzfs/zfs/releases/download/zfs-2.0.0/zfs-2.0.0.tar.gz sudo tar -xvf zfs-2.0.0.tar.gz
Compile the module¶
We will build the module using DKMS. This will enable us to keep the module up to date as new kernels are released in the future.
The ZFS distribution provides a script to build a suitable dkms.conf file.
Build dkms.conf and install it into the DKMS tree.
cd /usr/src/zfs-2.0.0 sudo scripts/dkms.mkconf -n zfs -v 2.0.0 -f dkms.conf sudo dkms add -m zfs -v 2.0.0 sudo dkms build -m zfs -v 2.0.0 sudo dkms install -m zfs -v 2.0.0
Observe that this install the zfs kernel modules to:
/usr/lib/modules/<kernel-name>/extra/zfs
Compile userspace tools¶
Here we compile and install the zfs userspace tools (e.g., zpool, zfs, etc.).
cd /usr/src/zfs-2.0.0 sudo ./configure sudo make sudo make install
The binaries are installed at the following directory. While not required, it’s recommended to add /usr/local/sbin
to your path variable.
+ /usr/local/ |--+ bin/ |--zvol_wait |--zgenhostid |--raidz_test |--+ etc/ |--+ zfs/ |--* zed.d/ |--+ zpool.d/ |--zfs-functions |--+ include/libzfs/ [contents omitted] |--+ lib/ |--+ libexec/ |--+ zfs/ |-- zpool.d/ |-- zed.d |--+ share/zfs/ [contents omitted] |--+ sbin/ |--fsck.zfs |--zpool |--zdb |--zed |--zfs |--zhack |--zinject |--zpool |--ztest |--zstreamdump |--+ src/ |--+ zfs-2.0.0/ |--+ spl-2.0.0/
Set up systemd¶
We now have these unit files available.
zfs-env-bootfs.service
zfs-zed.service
zfs-import-cache.service
zfs-import-scan.service
zfs-mount.service
zfs-share.service
zfs-volume-wait.service
OpenZFS requires that we explicitly install and enable the services desired.
To use ZFS automatic zpool import and filesystem mount services, enable them.
sudo systemctl enable zfs-import-cache
sudo systemctl enable zfs-import.target
sudo systemctl enable zfs-import-scan
sudo systemctl enable zfs-mount
sudo systemctl enable zfs.target
Load the kernel module at boot¶
OpenZFS kernel modules must be loaded before any OpenZFS filesystems are mounted. For convenience, load the kernel modules at boot.
Systemd uses the /etc/modules-load.d/ directory to load out-of-tree kernel modules. Make sure that the directory exists:
sudo mkdir -p /etc/modules-load.d
Create the configuration file:
echo "zfs" | sudo tee /etc/modules-load.d/01-zfs.conf
Reboot your system. zfs.ko should be loaded automatically (the module should appear in the outout of command lsmod
).
Caution
When the Clear Linux OS kernel is upgraded, DKMS will attempt to rebuild the OpenZFS module for the new kernel.
DKMS may not have rebuilt the module
DKMS may not have auto-installed the module
The new kernel might introduce breaking changes that prevent zfs from compiling
To fix this situation, recompile zfs.ko with the new kernel code. OpenZFS might not compile at all with the new kernel.
Caution
Be sure not to put anything on an OpenZFS pool that will be needed to rebuild kernel modules. Ensure compatibility of OpenZFS with new Linux kernels when released.
Troubleshooting¶
If you suspect an issue with DKMS rebuilding your module, you can check two places for information. The dkms-new-kernel service will show status that may help in troubleshooting:
systemctl status dkms-new-kernel.service
The systemd journal may also have important information:
journalctl -xe
Caution
As of OpenZFS 2.0.0, the included file script/dkms.mkconf
contains a minor incompability – it calls the command lsb_release
, which is not available on Clear Linux by default. It is trivial to edit dkms.mkconf
and remove the singular reference to lsb_release
without any ill effects, and then execute the dkms
commands above. However, keeping the file as provided is perfectly fine, but will result in :file:`dkms` warnings.
Next steps¶
You’re now ready to create zpools and datasets! For more information on using ZFS, see: