How it works under the hood

There is very little magic involved. Early in boot – before iwd, WireGuard, sshd or the webhook start – a small service called arch-iso-config finds the config partition and copies archiso-config/ into the live system, which runs entirely in RAM. Each file lands where the stock tools expect it, readable only by root:

Nothing else is ever written back to the stick. The one exception is the SSH host keys on the first boot: the partition is remounted read-write just long enough to save them, then read-only again. That is what keeps the fingerprint stable from one boot to the next.

Why the partition label matters

The service finds the partition by its ARCH_CONFIG label, and that label matters more than it looks. The Arch live system boots with copytoram: on a machine with enough memory, it copies itself into RAM and lets go of the boot partition before any of this runs. So the service cannot simply look at “the partition I booted from”; it searches for a filesystem labelled ARCH_CONFIG, mounts it, and unmounts it again.

If you relabel the partition, the stick still boots – but unconfigured.

A nice side effect is that the configuration does not have to be on the stick you booted from. Any FAT32 USB stick labelled ARCH_CONFIG with an archiso-config/ directory on it works too; start from a copy of the repo’s config-templates/. Just do not plug in two of them at once, because the first one found wins.

And a stick with no configuration at all still boots. It simply has no WiFi, no VPN, no SSH login and no webhook, and says so on the console.

One stick, two architectures

The combined image boots an x86_64 PC and a Raspberry Pi 5 from the same partition, which sounds like it ought to need something clever. It does not. There is one MBR disk image with a single FAT32 partition on it, and the whole trick is that the two firmwares never look at the same files:

config.txt cmdline.txt kernel8.img initramfs-linux.img *.dtb overlays/   # Pi 5 firmware
EFI/BOOT/BOOTx64.EFI  loader/  arch/boot/x86_64/                         # x86_64 UEFI (systemd-boot)
arch/x86_64/airootfs.sfs   arch/aarch64/airootfs.sfs                     # the two live systems
archiso-config/                                                          # your configuration
boot/<uuid>.uuid                                                         # how each initramfs finds the stick

The Pi’s firmware reads only the top-level files. There is no boot loader on the Pi at all: the firmware itself loads kernel8.img, the initramfs and the device trees straight off the FAT partition, and takes its kernel command line from cmdline.txt. UEFI firmware, for its part, looks only in EFI/ and loader/, where it finds systemd-boot. Neither one has any idea the other’s files are sitting next to it.

Once a kernel is running, its initramfs mounts arch/<its own architecture>/airootfs.sfs. That is why there are two airootfs.sfs files: they are two complete live systems, one per architecture, and each boot only ever touches one of them.

How each half finds the stick

archiso normally identifies the medium it booted from by the ISO’s volume UUID – which a FAT32 stick does not have, because there is no ISO filesystem involved. So it falls back to a second method: it searches the attached disks for a file at boot/<uuid>.uuid and uses whichever one matches the UUID it was told to expect. The Pi gets told through cmdline.txt:

archisobasedir=arch archisosearchuuid=1234-5678 console=serial0,115200 console=tty1

This is the same mechanism archiso provides for copying an ISO onto a FAT32 stick, used here for both halves.

It is worth noticing that this is a different search from the one that finds archiso-config/. The live system looks for its configuration by the ARCH_CONFIG filesystem label, as described above, because by then it may have let go of the boot device entirely. The two lookups are independent, which is exactly why the configuration can live on a second stick.

How the combined image is built

just build-usb builds an x86_64 ISO first, then builds the Pi image and merges the ISO’s UEFI boot files and live system into the Pi image’s FAT32 partition. The ISO is only an intermediate – it is where systemd-boot and the x86_64 kernel come from – and it is deleted once the combined image exists.

Where to go next

That is the whole of the stick. With one built and provisioned, the book proper starts at Boot the stick and connect.

Source and trademark

The source is at github.com/EnigmaCurry/boomstick.

BOOMSTICK is an independent project, not affiliated with or endorsed by the Arch Linux project. Arch Linux is a trademark of the Arch Linux project.