Arch Linux Root on ZFS


ZFSBootMenu is an alternative bootloader free of such limitations and has support for boot environments. Do not follow instructions on this page if you plan to use ZBM, as the layouts are not compatible. Refer to their site for installation details.


Unless stated otherwise, it is not recommended to customize system configuration before reboot.

Only use well-tested pool features

You should only use well-tested pool features. Avoid using new features if data integrity is paramount. See, for example, this comment.

UEFI support only

Only UEFI is supported by this guide.


  1. Disable Secure Boot. ZFS modules can not be loaded if Secure Boot is enabled.

  2. Because the kernel of latest Live CD might be incompatible with ZFS, we will use Alpine Linux Extended, which ships with ZFS by default.

    Download latest extended variant of Alpine Linux live image, verify checksum and boot from it.

    gpg --auto-key-retrieve --keyserver hkps:// --verify alpine-extended-*.asc
    dd if=input-file of=output-file bs=1M
  3. Login as root user. There is no password.

  4. Configure Internet

    setup-interfaces -r
    # You must use "-r" option to start networking services properly
    # example:
    network interface: wlan0
    WiFi name:         <ssid>
    ip address:        dhcp
    <enter done to finish network config>
    manual netconfig:  n
  5. If you are using wireless network and it is not shown, see Alpine Linux wiki for further details. wpa_supplicant can be installed with apk add wpa_supplicant without internet connection.

  6. Configure SSH server

    # example:
    ssh server:        openssh
    allow root:        "prohibit-password" or "yes"
    ssh key:           "none" or "<public key>"
  7. Set root password or /root/.ssh/authorized_keys.

  8. Connect from another computer

    ssh root@
  9. Configure NTP client for time synchronization

    setup-ntp busybox
  10. Set up apk-repo. A list of available mirrors is shown. Press space bar to continue

  11. Throughout this guide, we use predictable disk names generated by udev

    apk update
    apk add eudev
    setup-devd udev
  12. Target disk

    List available disks with

    find /dev/disk/by-id/

    If virtio is used as disk bus, power off the VM and set serial numbers for disk. For QEMU, use -drive format=raw,file=disk2.img,serial=AaBb. For libvirt, edit domain XML. See this page for examples.

    Declare disk array

    DISK='/dev/disk/by-id/ata-FOO /dev/disk/by-id/nvme-BAR'

    For single disk installation, use

  13. Set a mount point

    MNT=$(mktemp -d)
  14. Set partition size:

    Set swap size in GB, set to 1 if you don’t want swap to take up too much space


    Set how much space should be left at the end of the disk, minimum 1GB

  15. Install ZFS support from live media:

    apk add zfs
  16. Install partition tool

    apk add parted e2fsprogs cryptsetup util-linux

System Installation

  1. Partition the disks.

    Note: you must clear all existing partition tables and data structures from target disks.

    For flash-based storage, this can be done by the blkdiscard command below:

    partition_disk () {
     local disk="${1}"
     blkdiscard -f "${disk}" || true
     parted --script --align=optimal  "${disk}" -- \
     mklabel gpt \
     mkpart EFI 1MiB 4GiB \
     mkpart rpool 4GiB -$((SWAPSIZE + RESERVE))GiB \
     mkpart swap  -$((SWAPSIZE + RESERVE))GiB -"${RESERVE}"GiB \
     set 1 esp on \
     partprobe "${disk}"
    for i in ${DISK}; do
       partition_disk "${i}"
  2. Setup temporary encrypted swap for this installation only. This is useful if the available memory is small:

    for i in ${DISK}; do
       cryptsetup open --type plain --key-file /dev/random "${i}"-part3 "${i##*/}"-part3
       mkswap /dev/mapper/"${i##*/}"-part3
       swapon /dev/mapper/"${i##*/}"-part3
  3. Load ZFS kernel module

    modprobe zfs
  4. Create root pool

    • Unencrypted:

      # shellcheck disable=SC2046
      zpool create \
          -o ashift=12 \
          -o autotrim=on \
          -R "${MNT}" \
          -O acltype=posixacl \
          -O canmount=off \
          -O dnodesize=auto \
          -O normalization=formD \
          -O relatime=on \
          -O xattr=sa \
          -O mountpoint=none \
          rpool \
          mirror \
         $(for i in ${DISK}; do
            printf '%s ' "${i}-part2";
  5. Create root system container:

    zfs create -o canmount=noauto -o mountpoint=legacy rpool/root

    Create system datasets, manage mountpoints with mountpoint=legacy

    zfs create -o mountpoint=legacy rpool/home
    mount -o X-mount.mkdir -t zfs rpool/root "${MNT}"
    mount -o X-mount.mkdir -t zfs rpool/home "${MNT}"/home
  6. Format and mount ESP. Only one of them is used as /boot, you need to set up mirroring afterwards

    for i in ${DISK}; do
     mkfs.vfat -n EFI "${i}"-part1
    for i in ${DISK}; do
     mount -t vfat -o fmask=0077,dmask=0077,iocharset=iso8859-1,X-mount.mkdir "${i}"-part1 "${MNT}"/boot

System Configuration

  1. Download and extract minimal Arch Linux root filesystem:

    apk add curl
    curl --fail-early --fail -L \ \
    -o rootfs.tar.gz
    curl --fail-early --fail -L \ \
    -o rootfs.tar.gz.sig
    apk add gnupg
    gpg --auto-key-retrieve --keyserver hkps:// --verify rootfs.tar.gz.sig
    ln -s "${MNT}" "${MNT}"/root.x86_64
    tar x  -C "${MNT}" -af rootfs.tar.gz root.x86_64
  2. Enable community repo

    sed -i '/edge/d' /etc/apk/repositories
    sed -i -E 's/#(.*)community/\1community/' /etc/apk/repositories
  3. Generate fstab:

    apk add arch-install-scripts
    genfstab -t PARTUUID "${MNT}" \
    | grep -v swap \
    | sed "s|vfat.*rw|vfat rw,x-systemd.idle-timeout=1min,x-systemd.automount,noauto,nofail|" \
    > "${MNT}"/etc/fstab
  4. Chroot

    cp /etc/resolv.conf "${MNT}"/etc/resolv.conf
    for i in /dev /proc /sys; do mkdir -p "${MNT}"/"${i}"; mount --rbind "${i}" "${MNT}"/"${i}"; done
    chroot "${MNT}" /usr/bin/env DISK="${DISK}" bash
  5. Add archzfs repo to pacman config

    pacman-key --init
    pacman-key --refresh-keys
    pacman-key --populate
    curl --fail-early --fail -L \
    |  pacman-key -a - --gpgdir /etc/pacman.d/gnupg
    pacman-key \
    --lsign-key \
    --gpgdir /etc/pacman.d/gnupg \
    tee -a /etc/pacman.d/mirrorlist-archzfs <<- 'EOF'
    ## See
    ## France
    #,Server =$repo/$arch
    ## Germany
    #,Server =$repo/$arch
    #,Server =$repo/$arch
    ## India
    #,Server =$repo/$arch
    ## United States
    #,Server =$repo/$arch
    tee -a /etc/pacman.conf <<- 'EOF'
    #Include = /etc/pacman.d/mirrorlist-archzfs
    #,Include = /etc/pacman.d/mirrorlist-archzfs
    # this #, prefix is a workaround for ci/cd tests
    # remove them
    sed -i 's|#,||' /etc/pacman.d/mirrorlist-archzfs
    sed -i 's|#,||' /etc/pacman.conf
    sed -i 's|^#||' /etc/pacman.d/mirrorlist
  6. Install base packages:

    pacman -Sy
    pacman -S --noconfirm mg mandoc efibootmgr mkinitcpio
    kernel_compatible_with_zfs="$(pacman -Si zfs-linux \
    | grep 'Depends On' \
    | sed "s|.*linux=||" \
    | awk '{ print $1 }')"
    pacman -U --noconfirm"${kernel_compatible_with_zfs}"-x86_64.pkg.tar.zst
  7. Install zfs packages:

    pacman -S --noconfirm zfs-linux zfs-utils
  8. Configure mkinitcpio:

    sed -i 's|filesystems|zfs filesystems|' /etc/mkinitcpio.conf
    mkinitcpio -P
  9. For physical machine, install firmware

    pacman -S linux-firmware intel-ucode amd-ucode
  10. Enable internet time synchronisation:

    systemctl enable systemd-timesyncd
  11. Generate host id:

    zgenhostid -f -o /etc/hostid
  12. Generate locales:

    echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen
  13. Set locale, keymap, timezone, hostname

    rm -f /etc/localtime
    systemd-firstboot \
    --force \
    --locale=en_US.UTF-8 \
    --timezone=Etc/UTC \
    --hostname=testhost \
  14. Set root passwd

    printf 'root:yourpassword' | chpasswd


  1. Install rEFInd boot loader:

    # from
    # use Binary Zip File option
    pacman -S --noconfirm unzip
    curl -L --output
    mkdir -p /boot/EFI/BOOT
    find ./refind-bin- -name 'refind_x64.efi' -print0 \
    | xargs -0I{} mv {} /boot/EFI/BOOT/BOOTX64.EFI
    rm -rf refind-bin-
  2. Add boot entry:

    tee -a /boot/refind-linux.conf <<EOF
    "Arch Linux" "root=ZFS=rpool/root rw zfs_import_dir=/dev/"
  3. Exit chroot

  4. Unmount filesystems and create initial system snapshot

    umount -Rl "${MNT}"
    zfs snapshot -r rpool@initial-installation
  5. Export all pools

    zpool export -a
  6. Reboot

  7. Mount other EFI system partitions then set up a service for syncing their contents.