A ZFS-on-root MX Linux Tutorial

While ZFS is a very sophisticated device management technology and can be used to safely store incredibly large amounts of data in very complex arrangements, it is also quite capable of running on a single drive.

The following is a method to install MX Linux onto a single disk, with no encryption, and with legacy boot on a GPT-style disk layout on an amd64/x64/x86_64 64-bit architecture. These steps have been written for and tested on ONLY this setup. Both MX Linux and ZFS can run on different systems and under different configurations. These steps do not provide that versatility, though you can alter them to do so once you understand the process.

This tutorial is intended as a basic introduction to installing MX Linux with ZFS. It is not intended to make you an expert on any of these technologies, and it is not intended to be universally applicable to every person, every device, or every scenario.

Attempting these steps will destroy all data on your machine. This tutorial does not allow for dual-booting, UEFI booting, or any kind of disk encryption. This tutorial is designed to teach you the basic steps for creating a ZFS-on-root install of MX Linux. When you understand this process, you can adjust it to suit your needs.

Attempting these steps demands a certain level of knowledge and comfort with Linux in general, and perhaps with MX Linux specifically. If you find typing commands in a terminal to be scary or intimidating, this is not the right tutorial for you. If you do not know what a kernel or a file system is or why you might want to customize one of your own, this is not the right tutorial for you.

You have been warned. Use at your own risk.

These steps assert you have downloaded and are running a copy of MX-23.2_x64.iso. Other respins may also work. I’m a big fan of mx-23.2_sysVinit-only-respin_x64.iso. All following steps assume that you are running this ISO in a live session and are very comfortable with running commands in the terminal.

• (Optional.) If you do not require them, remove any other DKMS kernel packages, as taking the time to rebuild them will only make this process take longer.

    dpkg -l | grep "\-dkms" | awk '{print $2}' | while read f
    do
      sudo dpkg -r $f
    done
  

• (Suggested.) Remove the linux kernel image and linux header metapackages on the live session. This prevents the build environment from adding additional kernel software other than the version on the live image.

    sudo dpkg -r linux-image-amd64 linux-headers-amd64
  

  When you want to upgrade the kernel on the target machine, you can build a new kernel module. (More information about this is mentioned in Section 5.)

  Build the kernel module for your install. The kernel module you create must match the kernel version used by the live session. Verify this with:

    uname -r
  

  It is possible to build the kernel module on a different system and bring it to the live session, but only if that other system is running the exact same architecture and kernel. Do not attempt to mix and match kernels during this process. Whatever the live session kernel is must be the version of the kernel you install.

• Fetch and run 0-build-prep.sh as root. This script will install several packages needed to build ZFS.

    sudo sh 0-build-prep.sh
  

• Fetch and run 1-fetch-openzfs.sh. This script fetches the OpenZFS source code from GitHub, however, it will only fetch one specific tag, so as new versions of ZFS are released, be sure to update the value of ZFS_REPO_TAG in this script.

    sh 1-fetch-openzfs.sh
  

• Fetch and run 2-build-openzfs.sh. This is the script that creates (a) the necessary kernel module to use ZFS and (b) the programs you will need to create, modify, and delete ZFS zpools and datasets.

    sh 2-build-openzfs.sh
  

  Expect this script to take 15-30 minutes, depending on the speed of your system.

• When 2-build-openzfs.sh finishes successfully, there will be several .deb files in the directory. Make a copy of these files and keep them in a safe location since you can reuse them for other installs. You only need to build a kernel module once and it will work on any future install that uses that same kernel.

  The files to save are:

  • openzfs-libnvpair3_<ZFS_VERSION_HERE>_amd64.deb
  • openzfs-libuutil3_<ZFS_VERSION_HERE>_amd64.deb
  • openzfs-libzfs4_<ZFS_VERSION_HERE>_amd64.deb
  • openzfs-libzpool5_<ZFS_VERSION_HERE>_amd64.deb
  • openzfs-zfs-initramfs_<ZFS_VERSION_HERE>_all.deb
  • openzfs-zfs-modules-<KERNEL_VERSION_HERE>_<ZFS_VERSION_HERE>_amd64.deb
  • openzfs-zfsutils_<ZFS_VERSION_HERE>_amd64.deb

  The exact names of these files will vary depending on version numbers.

There are several different ways to boot a disk. This tutorial uses one specific setup: a GPT disk layout with one partition for BIOS-GRUB at the top of the disk and a second partition for the rest of the system.

It will be that second partition where you will put ZFS.

• Fetch and run 3-parted.sh as root. This requires you to know the name of your disk device. This step will destroy any data already present on your system.

    sudo sh 3-parted.sh sda
  

  Alternatively, you can run these commands manually. Example, using “sda” as your disk device:

    sudo parted -s /dev/sda mklabel gpt
    sudo parted -s --align optimal /dev/sda mkpart primary 1MiB 2MiB
    sudo parted -s --align optimal /dev/sda mkpart primary 2MiB 100%
    sudo parted -s /dev/sda set 2 legacy_boot on
    sudo parted -s /dev/sda set 1 bios_grub on
  

• Install the ZFS packages on the live session. If you built them on a different machine, bring them into the live session either with a USB drive, or over the network with rsync or scp. For example:

    sudo dpkg -i openzfs-zfs-modules-6.1.0-17-amd64_2.2.3-1_amd64.deb \
      openzfs-libnvpair3_2.2.3-1_amd64.deb openzfs-libuutil3_2.2.3-1_amd64.deb \
      openzfs-libzfs4_2.2.3-1_amd64.deb openzfs-libzpool5_2.2.3-1_amd64.deb \
      openzfs-zfsutils_2.2.3-1_amd64.deb
  

  Note that the initramfs package is not included here. It is safe to skip installing this package in the live session. You will need to install it on the target system.

• Load the ZFS kernel module. If this command returns any errors, stop and check if your .deb files are correct.

    sudo modprobe zfs
  

• Download the MX Linux cli-installer.

    git clone "https://github.com/MX-Linux/cli-installer-mx.git"
    cd cli-installer-mx
    git checkout -b 74f1c1af0c296f90c7c5fa6e91ad6a9d71158330
  

  Download cli-installer-zfs.patch, put it in the cli-installer-mx directory, and apply it to cli-installer:

    patch -p0 < ./cli-installer-zfs.patch
  

• Verify that cli-installer has been patched by comparing its new content to its commit:

    git diff
  

• Run the patched cli-installer as root.

    sudo cli-installer
  

• In cli-installer at the prompt “Do you want to repartition the disk (y/N)?” choose yes. Quit without making changes. This is needed only to invoke cli-installer to ask to format the new partitions you created in Section 3.

    Do you want to repartition the disk (y/N)? y
  

• In cli-installer at the prompt “Root partition (hda1, sda2, etc):” Enter the second partition of your hard disk. Example: “sda2”.

    Root partition (hda1, sda2, etc): sda2
  

• In cli-installer at the prompt “Available file systems for sda2 are:” choose option “9)zfs”. Ignore the statement “Downloading necessary files for formatting partitions”, since by now you will have had to create and install all the necessary packages by hand.

    Enter your choice 1-9: 9
  

• When the installer asks for confirmation to destroy the data on your disk, choose yes. When asked if you want to use a separate /home partition, choose no. The installer has already created a separate /home dataset. Choose yes on the remaining confirmation prompts to begin copying files to the disk.

    The install will now destroy the data on sda2. Do you want to continue (No will abort the installation) (n/Y)? y
  
    Do you want to use a separate '/home' partition (y/N)? n
  
    Do you want to continue (No will abort the install) (n/Y)? y
  

  Pressing Enter to accept the default answer should suffice.

• When the files are finished copying, cli-installer will prompt “Where should grub be installed?”. Choose “1”.

    Where should grub be installed?
    1) MBR (Legacy - Master Boot Record)
    2) Root Partition
    1
  

• The installer will ask a new question, “Did you remember to install the ZFS packages on the target machine with chroot?” At this point, stop. Let cli-installer wait while you open another terminal window and copy the .deb files you created to the new install:

    sudo cp -p openzfs*.deb /media/sda2/root/
  

• Install the ZFS packages on the target machine. This is the same thing as Section 4 step 1, only you perform this step inside a chroot:

    sudo chroot /media/sda2
    cd /root
    dpkg -i openzfs-zfs-modules-6.1.0-17-amd64_2.2.3-1_amd64.deb \
      openzfs-libnvpair3_2.2.3-1_amd64.deb openzfs-libuutil3_2.2.3-1_amd64.deb \
      openzfs-libzfs4_2.2.3-1_amd64.deb openzfs-libzpool5_2.2.3-1_amd64.deb \
      openzfs-zfsutils_2.2.3-1_amd64.deb
  

  (As a note, if you ever attempt later on to repeat this process with a new kernel, meaning you’ve built a new kernel module and are going to install both the kernel and the ZFS kernel module packages on an existing system, make sure you install the ZFS kernel module before you install the kernel. This is because the kernel module must exist before the kernel install post-installation steps run and a new initramfs gets created.)

• Install the zfs-initramfs package on the target system. It’s fine not to install this package in the live session in Section 4 step 1, but you will need it in the target system in order for it to be able to boot.

  If you closed the chroot from the previous step, chroot to the target system again:

    sudo chroot /media/sda2
    cd /root
  

  Then run:

    dpkg -i openzfs-zfs-initramfs_2.2.3-1_all.deb
  

  It’s safe to ignore initramfs warnings about cryptsetup and mdadm. Neither of these will be used.

  When ZFS is installed on the target system, make sure all chroots are closed before you continue.

    exit
  

  Return to where you left off in cli-installer.

• Continue the cli-installer process.

    Did you remember to install the ZFS packages on the target machine with chroot (y/N)? y
  

• From this point, cli-installer will continue with more configuration questions. This is where you can create a user account and set a password. This tutorial assumes you can complete the installation normally.

• When cli-installer finishes, export the new zpool.

    sudo zpool export -a -f
  

• Remove the MX ISO from the machine and boot from the hard disk.

Further reading on the OpenZFS project and a really useful book:

• OpenZFS - Getting Started
• FreeBSD Mastery: ZFS
• zfs-mxlinux-scripts.tar.gz - A collection of the scripts listed in this tutorial