Add enable_overlayfs option to set up Raspberry Pi OverlayFS root (#122)

raspi-config nonint do_overlayfs 0 fails under qemu-user emulation
because uname -r returns the host kernel, so update-initramfs produces
no initramfs. enable_overlayfs regenerates the initramfs against the
image kernel after the user commands run and configures cmdline.txt
and config.txt for overlay boot.

Signed-off-by: Paul Guyot <[email protected]>

Author: pguyot

.github/workflows/test-overlayfs.yml

@@ -0,0 +1,76 @@
+name: Test enable_overlayfs
+on:
+  push:
+    branches:
+      - 'main'
+      - 'releases/**'
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test_enable_overlayfs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: ./ # pguyot/arm-runner-action@HEAD
+      id: build_image
+      with:
+        base_image: raspios_lite:latest
+        # optimize_image shrinks the rootfs, which is unnecessary for this test.
+        optimize_image: 'no'
+        enable_overlayfs: 'yes'
+        commands: |
+            # raspi-config nonint do_overlayfs 0 fails to generate a working
+            # initramfs under qemu-user (uname -r returns the host kernel).
+            # enable_overlayfs runs after these commands and regenerates the
+            # initramfs against the image kernel; the test below verifies the
+            # produced image really is bootable in overlay mode.
+            sudo raspi-config nonint do_overlayfs 0
+
+    - name: Verify overlay configuration in produced image
+      run: |
+        set -euxo pipefail
+        sudo apt-get update
+        # unmkinitramfs (from initramfs-tools-core) handles the
+        # early-microcode + main archive concatenation produced by
+        # mkinitramfs, which a plain cpio/zstd/gunzip cannot.
+        sudo apt-get install -y file initramfs-tools-core
+
+        IMAGE="${{ steps.build_image.outputs.image }}"
+        LOOP=$(sudo losetup --find --show --partscan "$IMAGE")
+        sudo partprobe -s "$LOOP" || true
+
+        TIMEOUT=60; i=0
+        until sudo test -e "${LOOP}p1" || [ $i -ge $TIMEOUT ]; do sleep 1; i=$((i+1)); done
+        sudo test -e "${LOOP}p1" || { echo "${LOOP}p1 did not appear after ${TIMEOUT}s" >&2; exit 1; }
+
+        BOOT_MNT=$(mktemp -d)
+        sudo mount "${LOOP}p1" "$BOOT_MNT"
+
+        echo "::group::cmdline.txt"
+        sudo cat "$BOOT_MNT/cmdline.txt"
+        echo "::endgroup::"
+        sudo grep -q "boot=overlay" "$BOOT_MNT/cmdline.txt"
+
+        echo "::group::config.txt initramfs lines"
+        sudo grep -n "^initramfs" "$BOOT_MNT/config.txt" || true
+        echo "::endgroup::"
+        sudo grep -q "^initramfs initrd.img followkernel" "$BOOT_MNT/config.txt"
+
+        sudo test -s "$BOOT_MNT/initrd.img"
+        echo "initrd.img size: $(sudo stat -c %s "$BOOT_MNT/initrd.img") bytes"
+
+        WORK=$(mktemp -d)
+        sudo cp "$BOOT_MNT/initrd.img" "$WORK/initrd.img"
+        cd "$WORK"
+        sudo file initrd.img
+        sudo unmkinitramfs initrd.img extracted
+        # overlayroot ships init scripts under /scripts/*overlayroot*
+        sudo find extracted -path '*overlayroot*' | tee /tmp/overlayroot_files
+        test -s /tmp/overlayroot_files
+
+        cd /
+        sudo umount "$BOOT_MNT"
+        sudo losetup --detach "$LOOP"
+        sudo rm -rf "$WORK" "$BOOT_MNT"

README.md

@@ -322,6 +322,31 @@ environment.
 Note this parameter does not enable importing any contents written to
 `$GITHUB_ENV` ahead of running the commands. For that, use `import_github_env`.
 
+#### `enable_overlayfs`
+
+Enable Raspberry Pi OverlayFS (read-only root with tmpfs overlay) on the
+produced image. Default is `no`.
+
+Calling `raspi-config nonint do_overlayfs 0` from the `commands` block does
+not work on its own under qemu-user emulation: raspi-config invokes
+`update-initramfs -c -k "$(uname -r)"`, but `uname -r` reports the host
+kernel rather than the image kernel, so no initramfs is produced. The
+resulting image has `boot=overlay` in `cmdline.txt` but no
+`/boot/initrd.img`, and will not boot in overlay mode.
+
+When `enable_overlayfs` is set to `yes`, the action regenerates the
+initramfs against the image's actual kernel (detected from `/lib/modules`)
+after the `commands` step, places `/boot/initrd.img`, and ensures
+`cmdline.txt` and `config.txt` are configured for overlay boot. It is
+idempotent: it composes with `commands` that already invoke
+`raspi-config nonint do_overlayfs 0`.
+
+The script installs the `overlayroot` package into the image if it is not
+already present, so this option works with Raspberry Pi OS and custom images
+that have `apt` available. See
+[overlayfs test](.github/workflows/test-overlayfs.yml) for a verified
+example.
+
 ### Outputs
 
 #### `image`

action.yml

@@ -88,6 +88,10 @@ inputs:
     description: 'Exports $GITHUB_ENV from the image environment to subsequent tasks'
     required: false
     default: 'no'
+  enable_overlayfs:
+    description: 'Enable Raspberry Pi OverlayFS root in the produced image (regenerates initramfs against the image kernel and updates cmdline.txt / config.txt)'
+    required: false
+    default: 'no'
 outputs:
   image:
     description: "Path to image"
@@ -296,6 +300,11 @@ runs:
             cat ${script_dir}/github_env.sh >> $GITHUB_ENV
         exit $rc
       shell: bash
+    - name: Enable overlayfs
+      if: ${{ !cancelled() && steps.runcmd.conclusion == 'success' && (inputs.enable_overlayfs == 'yes' || inputs.enable_overlayfs == 'true') }}
+      run: |
+        sudo bash ${GITHUB_ACTION_PATH}/enable_overlayfs.sh ${{ steps.mount_image.outputs.mount }}
+      shell: bash
     - name: Copy artifacts within image
       if: ${{ always() && !cancelled() && (inputs.copy_artifacts_on_fail == 'yes' || steps.runcmd.conclusion == 'success') }}
       run: |

enable_overlayfs.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Enable Raspberry Pi OverlayFS root in a mounted image.
+#
+# raspi-config's do_overlayfs uses `update-initramfs -c -k "$(uname -r)"`,
+# but under qemu-user chroot `uname -r` returns the host kernel, so the
+# command fails silently and the image ships without /boot/initrd.img.
+# This script regenerates the initramfs against the image's actual kernel
+# and ensures cmdline.txt / config.txt are set up for overlay boot.
+set -euxo pipefail
+
+mount=$1
+
+kver=$(find "${mount}/lib/modules" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | sed 's|.*/||' | sort -V | tail -n1 || true)
+if [ -z "${kver}" ]; then
+    echo "enable_overlayfs: no kernel found under ${mount}/lib/modules/" >&2
+    echo "enable_overlayfs requires an image with a kernel installed (e.g. Raspberry Pi OS)." >&2
+    exit 1
+fi
+echo "enable_overlayfs: detected image kernel ${kver}"
+
+chroot "${mount}" sh -c '
+    set -e
+    if ! command -v overlayroot-chroot >/dev/null 2>&1; then
+        DEBIAN_FRONTEND=noninteractive apt-get update
+        DEBIAN_FRONTEND=noninteractive apt-get install -y overlayroot
+    fi
+'
+
+# Use mkinitramfs directly rather than update-initramfs: the
+# z50-raspi-firmware post-update hook copies to /boot/firmware/, which does
+# not exist in this mount layout (the FAT firmware partition is mounted at
+# ${mount}/boot, not ${mount}/boot/firmware). We place the file ourselves.
+chroot "${mount}" mkinitramfs -o "/boot/initrd.img-${kver}" "${kver}"
+
+cp -f "${mount}/boot/initrd.img-${kver}" "${mount}/boot/initrd.img"
+
+cmdline="${mount}/boot/cmdline.txt"
+if [ -f "${cmdline}" ] && ! grep -q "boot=overlay" "${cmdline}"; then
+    sed -i 's/[[:space:]]*$/ boot=overlay/' "${cmdline}"
+fi
+
+config="${mount}/boot/config.txt"
+if [ -f "${config}" ] && ! grep -q "^initramfs initrd.img followkernel" "${config}"; then
+    printf '\ninitramfs initrd.img followkernel\n' >> "${config}"
+fi