CI: Add Alpine Linux 3.23 runner to the pipeline (#18087)

Add an Alpine Linux 3.23 runner to the CI chain to run OpenZFS builds
and tests against musl libc.

Currently, zfs_send_sparse is killed after 10 minutes on Alpine, causing
cascading EBUSY failures in the test suite. With zfs_send_sparse
disabled, the ZFS test suite reaches a pass rate of 94.62%.

This commit introduces the required Alpine-specific setup and a small
set of shell and cloud-init compatibility fixes that also apply to
existing Linux runners.

The Alpine runner is not enabled by default and is not executed for new
pull requests.

Sponsored-by: ERNW Research GmbH - https://ernw-research.de/

Signed-off-by: Alexander Moch <amoch@ernw.de>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: Tony Hutter <hutter2@llnl.gov>
Reviewed-by: Tino Reichardt <milky-zfs@mcmilk.de>

.github/workflows/scripts/qemu-2-start.sh

@@ -43,6 +43,12 @@ case "$OS" in
     OSv="almalinux9"
     URL="https://repo.almalinux.org/almalinux/10/cloud/x86_64/images/AlmaLinux-10-GenericCloud-latest.x86_64.qcow2"
     ;;
+  alpine3-23)
+    OSNAME="Alpine Linux 3.23.2"
+    # Alpine Linux v3.22 and v3.23 are unknown to osinfo as of 2025-12-26.
+    OSv="alpinelinux3.21"
+    URL="https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/cloud/generic_alpine-3.23.2-x86_64-bios-cloudinit-r0.qcow2"
+    ;;
   archlinux)
     OSNAME="Archlinux"
     URL="https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-cloudimg.qcow2"
@@ -216,13 +222,21 @@ if [ ${OS:0:7} != "freebsd" ]; then
 hostname: $OS
 
 users:
-- name: root
-  shell: $BASH
-- name: zfs
-  sudo: ALL=(ALL) NOPASSWD:ALL
-  shell: $BASH
-  ssh_authorized_keys:
-    - $PUBKEY
+  - name: root
+    shell: /bin/bash
+    sudo: ['ALL=(ALL) NOPASSWD:ALL']
+  - name: zfs
+    shell: /bin/bash
+    sudo: ['ALL=(ALL) NOPASSWD:ALL']
+    ssh_authorized_keys:
+      - $PUBKEY
+    # Workaround for Alpine Linux.
+    lock_passwd: false
+    passwd: '*'
+
+packages:
+  - sudo
+  - bash
 
 growpart:
   mode: auto
@@ -305,3 +319,23 @@ else
   scp ~/src.txz "root@vm0:/tmp/src.txz"
   ssh root@vm0 'tar -C / -zxf /tmp/src.txz'
 fi
+
+#
+# Config for Alpine Linux similar to FreeBSD.
+#
+if [ ${OS:0:6} == "alpine" ]; then
+  while pidof /usr/bin/qemu-system-x86_64 >/dev/null; do
+    ssh 2>/dev/null zfs@vm0 "uname -a" && break
+  done
+  # Enable community and testing repositories.
+  ssh zfs@vm0 "sudo rm -rf /etc/apk/repositories"
+  ssh zfs@vm0 "sudo setup-apkrepos -c1"
+  ssh zfs@vm0 "echo '@testing http://dl-cdn.alpinelinux.org/alpine/edge/testing' | sudo tee -a /etc/apk/repositories"
+  # Upgrade to edge or latest-stable.
+  #ssh zfs@vm0 "sudo sed -i 's#/v[0-9]\+\.[0-9]\+/#/edge/#g' /etc/apk/repositories"
+  #ssh zfs@vm0 "sudo sed -i 's#/v[0-9]\+\.[0-9]\+/#/latest-stable/#g' /etc/apk/repositories"
+  # Update and upgrade after repository setup.
+  ssh zfs@vm0 "sudo apk update"
+  ssh zfs@vm0 "sudo apk add --upgrade apk-tools"
+  ssh zfs@vm0 "sudo apk upgrade --available"
+fi

.github/workflows/scripts/qemu-3-deps-vm.sh

@@ -10,6 +10,32 @@
 
 set -eu
 
+function alpine() {
+  echo "##[group]Install Development Tools"
+  sudo apk add \
+    acl alpine-sdk attr autoconf automake bash build-base clang21 coreutils \
+    cpio cryptsetup curl curl-dev dhcpcd eudev eudev-dev eudev-libs findutils \
+    fio gawk gdb gettext-dev git grep jq libaio libaio-dev libcurl \
+    libtirpc-dev libtool libunwind libunwind-dev linux-headers linux-tools \
+    linux-virt linux-virt-dev lsscsi m4 make nfs-utils openssl-dev parted \
+    pax procps py3-cffi py3-distlib py3-packaging py3-setuptools python3 \
+    python3-dev qemu-guest-agent rng-tools rsync samba samba-server sed \
+    strace sysstat util-linux util-linux-dev wget words xfsprogs xxhash \
+    zlib-dev pamtester@testing
+  echo "##[endgroup]"
+
+  echo "##[group]Switch to eudev"
+  sudo setup-devd udev
+  echo "##[endgroup]"
+
+  echo "##[group]Install ksh93 from Source"
+  git clone --depth 1 https://github.com/ksh93/ksh.git /tmp/ksh
+  cd /tmp/ksh
+  ./bin/package make
+  sudo ./bin/package install /
+  echo "##[endgroup]"
+}
+
 function archlinux() {
   echo "##[group]Running pacman -Syu"
   sudo btrfs filesystem resize max /
@@ -27,6 +53,10 @@ function archlinux() {
 function debian() {
   export DEBIAN_FRONTEND="noninteractive"
 
+  echo "##[group]Wait for cloud-init to finish"
+  cloud-init status --wait
+  echo "##[endgroup]"
+
   echo "##[group]Running apt-get update+upgrade"
   sudo sed -i '/[[:alpha:]]-backports/d' /etc/apt/sources.list
   sudo apt-get update -y
@@ -140,6 +170,9 @@ case "$1" in
     sudo dnf install -y kernel-abi-stablelists
     echo "##[endgroup]"
     ;;
+  alpine*)
+    alpine
+    ;;
   archlinux)
     archlinux
     ;;
@@ -188,6 +221,16 @@ test -z "${ONLY_DEPS:-}" || exit 0
 # Start services
 echo "##[group]Enable services"
 case "$1" in
+  alpine*)
+    sudo -E rc-update add qemu-guest-agent
+    sudo -E rc-update add nfs
+    sudo -E rc-update add samba
+    sudo -E rc-update add dhcpcd
+    # Remove services related to cloud-init.
+    sudo -E rc-update del cloud-init default
+    sudo -E rc-update del cloud-final default
+    sudo -E rc-update del cloud-config default
+    ;;
   freebsd*)
     # add virtio things
     echo 'virtio_load="YES"' | sudo -E tee -a /boot/loader.conf
@@ -243,7 +286,7 @@ case "$1" in
 esac
 
 case "$1" in
-  archlinux|freebsd*)
+  alpine*|archlinux|freebsd*)
     true
     ;;
   *)

.github/workflows/scripts/qemu-5-setup.sh

@@ -58,13 +58,21 @@ for ((i=1; i<=VMs; i++)); do
 fqdn: vm$i
 
 users:
-- name: root
-  shell: $BASH
-- name: zfs
-  sudo: ALL=(ALL) NOPASSWD:ALL
-  shell: $BASH
-  ssh_authorized_keys:
-    - $PUBKEY
+  - name: root
+    shell: /bin/bash
+    sudo: ['ALL=(ALL) NOPASSWD:ALL']
+  - name: zfs
+    shell: /bin/bash
+    sudo: ['ALL=(ALL) NOPASSWD:ALL']
+    ssh_authorized_keys:
+      - $PUBKEY
+    # Workaround for Alpine Linux.
+    lock_passwd: false
+    passwd: '*'
+
+packages:
+  - sudo
+  - bash
 
 growpart:
   mode: auto

.github/workflows/scripts/qemu-6-tests.sh

@@ -95,11 +95,18 @@ case "$1" in
     ;;
 esac
 
-# enable io_uring on el9/el10
+# Distribution-specific settings.
 case "$1" in
   almalinux9|almalinux10|centos-stream*)
+    # Enable io_uring on Enterprise Linux 9 and 10.
     sudo sysctl kernel.io_uring_disabled=0 > /dev/null
     ;;
+  alpine*)
+    # Ensure `/etc/zfs/zpool.cache` exists.
+    sudo mkdir -p /etc/zfs
+    sudo touch /etc/zfs/zpool.cache
+    sudo chmod 644 /etc/zfs/zpool.cache
+    ;;
 esac
 
 # run functional testings and save exitcode

.github/workflows/zfs-qemu.yml

@@ -10,6 +10,11 @@ on:
         required: false
         default: ""
         description: "(optional) Experimental kernel version to install on Fedora (like '6.14' or '6.13.3-0.rc3')"
+      specific_os:
+        type: string
+        required: false
+        default: ""
+        description: "(optional) Only run on this specific OS (like 'fedora42' or 'alpine3-23')"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
@@ -58,6 +63,9 @@ jobs:
               # They specified a custom kernel version for Fedora.
               # Use only Fedora runners.
               os_json=$(echo ${os_selection} | jq -c '[.[] | select(startswith("fedora"))]')
+          elif ${{ github.event.inputs.specific_os != '' }}; then
+              # Use only the specified runner.
+              os_json=$(jq -cn --arg os "${{ github.event.inputs.specific_os }}" '[ $os ]')
           else
               # Normal case
               os_json=$(echo ${os_selection} | jq -c)

tests/zfs-tests/callbacks/zfs_dbgmsg.ksh

@@ -26,7 +26,7 @@ echo "================================================================="
 sudo tail -n $lines /proc/spl/kstat/zfs/dbgmsg
 
 # reset dbgmsg
-sudo bash -c "echo > /proc/spl/kstat/zfs/dbgmsg"
+sudo sh -c "echo > /proc/spl/kstat/zfs/dbgmsg"
 
 echo "================================================================="
 echo " End of zfs_dbgmsg log"

tests/zfs-tests/callbacks/zfs_mmp.ksh

@@ -31,7 +31,7 @@ for f in /proc/spl/kstat/zfs/*/multihost; do
 	echo "================================================================="
 
 	sudo tail -n $lines $f
-	sudo bash -c "echo > $f"
+	sudo sh -c "echo > $f"
 done
 
 echo "================================================================="

tests/zfs-tests/include/libtest.shlib

@@ -559,7 +559,7 @@ function default_cleanup_noexit
 		# Here, we loop through the pools we're allowed to
 		# destroy, only destroying them if it's safe to do
 		# so.
-		while [ ! -z ${ALL_POOLS} ]
+		while [ -n "${ALL_POOLS}" ]
 		do
 			for pool in ${ALL_POOLS}
 			do

tests/zfs-tests/tests/functional/mount/mount_loopback.ksh

@@ -79,7 +79,8 @@ function do_test
 	imgfile=$1
 	log_note "Running test on $imgfile"
 	log_must losetup -f $imgfile
-	DEV=$(losetup --associated $imgfile | grep -Eo '^/dev/loop[0-9]+')
+	# Alpine Linux loop devices appear as `/dev/loop/N` instead of `/dev/loopN`.
+	DEV=$(losetup --associated $imgfile | grep -Eo '^/dev/loop/?[0-9]+')
 	log_must mkfs.xfs $DEV
 	mkdir $TEST_BASE_DIR/mnt
 	log_must mount $DEV $TEST_BASE_DIR/mnt