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

Install the DKMS kernel

Install the kernel-native-dkms or kernel-lts-dkms bundle.

  1. 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.

  2. 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

  3. 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 you install OpenZFS, install the bundles that contain the build dependencies.

sudo swupd bundle-add os-core-dev devpkg-openssl devpkg-util-linux

Install

Clone OpenZFS code

In this section, you download the source code directly from the ZFS on Linux repository.

Note

OpenZFS will not run from this location. We copy the source code into a DKMS directory in the following steps.

  1. Create a directory. In this example, we use /opt/src/zfs, but you can choose any workspace you like.

    sudo mkdir -p /tmp/zfs/

  2. Clone the repository.

    git clone https://github.com/openzfs/zfs.git /tmp/zfs
sudo cp -Rv /tmp/zfs /opt/src/zfs

Remember where you clone the git repository because you will need it when you upgrade ZFS. Do not delete the source location when you have completed this tutorial. You will need it later.

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.

  1. Check out the tagged version that you plan to use. As of the time of this writing, the latest release tag is 0.8.4:

    cd /opt/src/zfs
git checkout zfs-0.8.4

  2. Copy the source code into /usr/src/zfs-0.8.4. This exposes the source code to DKMS. We will build the code from the new location:

    sudo cp -Rv /opt/src/zfs /usr/src/zfs-0.8.4

  3. 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-0.8.4
sudo scripts/dkms.mkconf -n zfs -v 0.8.4 -f dkms.conf
sudo dkms add -m zfs -v 0.8.4
sudo dkms build -m zfs -v 0.8.4
sudo dkms install -m zfs -v 0.8.4

  4. Observe that this install the zfs kernel modules to: /usr/lib/modules/<kernel-name>/extra/zfs

    In addition, this installs the zfs userspace tools to:

    + /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-0.8.4/
   |--+ spl-0.8.4/

  5. Load the new kernel module:

Set up systemd

You should 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 you to explicitly install and enable the services you want. If you want to use other ZFS service units, you could create symlinks for them, similar to the example below.

To use ZFS automatic zpool import and filesystem mount services, link the systemd.unit files into /etc and enable them.

sudo ln -s ./etc/systemd/system/zfs-import-cache.service /etc/systemd/system/
sudo ln -s ./etc/systemd/system/zfs-mount.service /etc/systemd/system/

sudo systemctl enable zfs-import-cache
sudo systemctl enable zfs-import.target

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.

  1. 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

  2. Create the configuration file:

    echo "zfs" | sudo tee /etc/modules-load.d/01-zfs.conf

  3. Reboot your system. zfs.ko should be loaded automatically.

Caution

When the Clear Linux OS kernel is upgraded, DKMS will attempt to rebuild your 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, you may have to recompile zfs.ko with the new kernel code. OpenZFS might not compile at all with the new kernel.

Caution

Be sure you don’t put anything on an OpenZFS pool that you would need in order to rebuild kernel modules. You must ensure the compatibility of OpenZFS with new Linux kernels when they are 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

Also, the systemd journal may have important information:

journalctl -xe

Next steps

You are ready to create zpools and datasets! For more information on using ZFS, see: