Skip to content
DOCUMENTATION

Device images

Besides the generic live ISOs, UFLinux builds installed GPT disk images for specific boards. A device image is written straight to the board’s SD card or eMMC, boots to the login screen, and grows its root partition to the size of the media on first boot. There is no squashfs modloop, no live user, and no live session.

Device images are supplementary. They are built on version tags and attached to the same release as the ISOs, but a failing or missing image never blocks publication of the ISOs and the signed package repository — and none of them has an automated boot test yet. Treat them as a preview.

Id Boards Architecture Kernel Boot Root fs Status
rpi Raspberry Pi 3, 4 and 5 aarch64 linux-rpi VideoCore firmware f2fs Supported
vm QEMU, KVM and other hypervisors x86_64, aarch64 linux-virt UEFI + systemd-boot XFS Supported
qcs6490 Arrow Dragon Q6A and similar aarch64 Nura linux-postmarketos-qcom-sc7280 board UEFI + systemd-boot f2fs Experimental
spacemit-k1 Orange Pi RV2, Orange Pi R2S, BananaPi-F3 riscv64 linux-lts U-Boot distro boot f2fs Experimental

f2fs is used on the single-board targets because it is built for the wear-levelling and small-write behaviour of SD cards and eMMC. The vm image uses XFS, the same filesystem as an installed ISO system, since a virtual disk has none of those constraints.

Every image has the same two-partition GPT layout:

Partition Start (512 B sectors) Size Filesystem
ESP 2048 512 MiB FAT32, label UFLINUX
ROOT 1050624 rest of the disk f2fs on boards, XFS on vm, label UFLINUX_ROOT

The uncompressed image is 6144 MiB (5120 MiB for vm), so any larger card works and the root partition grows to fill it. Disk, partition and FAT volume identifiers are derived from the version, board id and architecture, so a rebuild produces the same GUIDs.

The kernel command line uses root=UUID=<ROOT filesystem UUID> rootwait rootfstype=<fs> rootflags=ro. The formatters set the filesystem UUID to the root partition GUID too, and Alpine’s initramfs passes root to BusyBox mount, which resolves filesystem UUID= and LABEL= but not PARTUUID=. The explicit type means the initramfs carries only the one filesystem module it needs.

Terminal window
zstd -d < uflinux-0.1.0-rpi-aarch64.img.zst | sudo dd of=/dev/sdX bs=8M oflag=direct status=progress
sync

Verify the checksum sidecar first:

Terminal window
sha256sum -c uflinux-0.1.0-rpi-aarch64.img.zst.sha256
gh attestation verify uflinux-0.1.0-rpi-aarch64.img.zst --repo UFlinux-project/uflinux3

Images are published with Zstandard level 12 compression. See Boot-image compression.

Every device image ships a regular account: user / user. Select the UFLinux session at the graphical greeter, or use this account on the text/serial console. The account belongs to wheel, audio, video, input, netdev and, when available, render, and both sudo and doas allow administrative commands with its password. To change it after login:

Terminal window
passwd

greetd with the UFLinux greeter is enabled by default, so the account can log in graphically. Serial gettys are configured per board (ttyMSM0, ttyAMA0 or ttyS0 at 115200 8n1) in addition to tty1 and tty2.

The uflinux-device OpenRC service — from the uflinux-device package, published in the release repository but not bundled in the live ISO — runs early in the boot runlevel, after filesystem checks and before the root remount and localmount. It does nothing unless /etc/uflinux/device exists — which a device image writes with the board id — so it is inert on an ordinary installed system.

When armed, it runs growpart on the root partition once and grows the filesystem to fill it, then records /var/lib/uflinux/device-resized. A later manual partition change is therefore not undone, and a reboot does not repeat the work. Failures are warnings, not boot failures.

One quirk: an f2fs root is grown in place while mounted read-only — the only way the kernel allows — but the kernel does not re-read the superblock on remount, so the new space shows in df only after the next reboot. The full size is already usable for writes.

The shipped /etc/apk/repositories lists the published UFLinux repository, Alpine, and the apps repository on the architectures it indexes, so apk update works as soon as the release is public. The apps repository carries uflinux-files, which the desktop meta depends on; its separate uflinux3.ec384.pub key is downloaded, verified against the build lock and installed under that exact name during the device build, and uflinux-release ships the same file in the installed system.

The exception is qcs6490. Its kernel and the dtbloader EFI driver come from Nura, the postmarketOS distribution, and are fetched and unpacked rather than installed — Nura ships its own mkinitfs replacement that conflicts with Alpine’s, so apk must never solve across both repositories at once. Nura is never listed in /etc/apk/repositories. The trade-off is that unpacked packages get no triggers and cannot be upgraded with apk; they are replaced by flashing a newer image.

The device build stage has tests for disk geometry, identifiers, package set, boot configuration and post-build disk verification, and every package name is checked against the live Alpine and pinned Nura indexes.

On real hardware, the evidence is thinner. The qcs6490 image has been booted on an Arrow Dragon Q6A from a USB stick: the firmware reached systemd-boot and the entry loaded, but with Alpine’s linux-lts the HDMI output stayed black — which is what prompted the switch to the Nura mainline kernel. The other images have not been booted on physical hardware, and none is covered by the QEMU boot tests that the ISOs get.

That is why two of the four targets are labelled experimental and why release notes describe device images as a preview.

Derived from docs/device-images.md inUFlinux-project/uflinux3(b4f4817). Report documentation problems inUFlinux-project/docs.