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.
Targets
Section titled “Targets”| 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.
Disk layout
Section titled “Disk layout”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.
Writing an image
Section titled “Writing an image”zstd -d < uflinux-0.1.0-rpi-aarch64.img.zst | sudo dd of=/dev/sdX bs=8M oflag=direct status=progresssyncVerify the checksum sidecar first:
sha256sum -c uflinux-0.1.0-rpi-aarch64.img.zst.sha256gh attestation verify uflinux-0.1.0-rpi-aarch64.img.zst --repo UFlinux-project/uflinux3Images are published with Zstandard level 12 compression. See Boot-image compression.
First login
Section titled “First login”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:
passwdgreetd 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.
First boot: the root partition grows
Section titled “First boot: the root partition grows”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.
Updates on a board
Section titled “Updates on a board”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.
How solid is this?
Section titled “How solid is this?”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.