Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ bin/omamobile images # boot, init_boot, vendor_boot, vendor_kernel_boo

# A first install: packages, root image, then the installer (phone in fastboot)
tools/build-packages # [omamobile] for aarch64 into out/repo, signed
tools/build-rootfs # out/omamobile-rootfs-<date>-aarch64.img.zst
tools/build-rootfs # out/omamobile-rootfs-<device>-<date>-aarch64.img.zst
tools/install-phone --dry-run # checks, questions, the exact commands; then without --dry-run
# after the first boot: a read-only backup of the modem's partitions into DIR (REINSTALL-RUNBOOK 4a)
tools/phone-provision --nv-backup DIR FACTORY.zip # firmware and per-phone data
Expand Down
12 changes: 8 additions & 4 deletions docs/RELEASES.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ For a first install, or to recover a phone that won't boot. One bundle per devic
| Piece | Where | Notes |
| --- | --- | --- |
| aarch64 packages without a phone | `tools/build-packages` | makepkg in an Arch Linux ARM container (the official tarball, MD5 and signature checked against the pinned build key, `tools/lib/alarm.sh`) under the laptop's qemu-user; signs with `keys/` into `out/repo/aarch64`. Mesa, Hyprland and libcamera take hours this way, so they're built only when named, once per version |
| The shared root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `patches/omarchy`. Output `out/omamobile-rootfs-<date>-aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) |
| The device's root image | `tools/build-rootfs`, `rootfs/` | pacstrap in that container: `rootfs/packages.base`, then Omarchy's own `install/omarchy-base.packages` (minus `rootfs/packages.omarchy-skip` and what isn't built for aarch64), then `rootfs/packages.omamobile`, the device package and the board's `ROOTFS_PACKAGES`, the `[omamobile]` repository itself, the kernel modules of the current build, and `patches/omarchy`. Output `out/omamobile-rootfs-<codename>-<date>-aarch64.img.zst`, `.sha256` and a `MANIFEST` with every package version (also inside, `/usr/share/omamobile/rootfs/MANIFEST`) |
| First boot | `packages/omamobile-firstboot` | reads `/etc/omamobile/firstboot.conf` (data, never sourced), creates the user, SSH keys, ufw with SSH on `usb0`, runs Omarchy's own setup leaves (skipping four that don't fit a phone), SDDM autologin and the lock, Omarchy's and our user setup, then deletes the file |
| Growing the root | `initramfs/init` (`grow_root`) | `resize2fs` before mounting, only for a file system labelled `omamobile-root` smaller than its partition; `omamobile.noresize` skips it |
| The installer | `tools/install-phone` (the bundle's `install`) | as described below, steps 1, 3-5; the factory-image step (2) is `tools/phone-provision` after the first boot instead |
Expand All @@ -241,6 +241,8 @@ For a first install, or to recover a phone that won't boot. One bundle per devic

Decisions taken in building it: the device packages are **installed** in the image, not only cached (one device so far; a first boot without a package step has one less way to fail; §12 decision 6 stays open for the second device); the image's `[omarchy]` is Omarchy's **stable** channel (from 2026-10-20; before that edge was the only one with aarch64 builds of `omarchy`, `omarchy-settings` and `quickshell`, and edge then moved to 4.5.0rc1, which the phone's patches don't apply to); the image is per device (its `MANIFEST` names the device, and the installer refuses a mismatch).

Root image filenames include the device so two devices can share a version without overwriting each other. Builds use separate temporary directories and refuse a concurrent build of the same device/version in the same output directory. Compression and smoke checks finish before replacing the published files. `--local NAME` still uses `out/NAME/repo` and writes images under `out/NAME/`; use `--rootfs` to select one there. Independent package snapshots also need separate `ALARM_CACHE` directories (§10). Repository-mode installation and bundling select only images whose root `MANIFEST` matches the device, including older filenames.

The design:

```
Expand All @@ -251,11 +253,13 @@ omamobile-<codename>-<version>/
images/boot.img init_boot.img vendor_boot.img vendor_kernel_boot.img dtbo.img
MANIFEST kernel release, package versions, both repositories' commits
SHA256SUMS SHA256SUMS.sig checksums of everything above, signed
omamobile-rootfs-<version>-aarch64.img.zst shared by every device, downloaded once
.sha256 .sig
omamobile-rootfs-<codename>-<version>-aarch64.img.zst
.sha256 .MANIFEST
```

**The shared root image** is an ext4 Arch Linux ARM root with Omarchy, the `[omamobile]` repository configured and its keyring, `linux-omamobile`, `omamobile-shell` and every device package in the package cache but **none installed**. It is built by `pacstrap` in an aarch64 container. It contains no Google file. Its size is a few GB, flashed sparse; the first boot grows it to the whole `userdata` partition (`resize2fs` in the initramfs, before mounting).
**The device's root image** is an ext4 Arch Linux ARM root with Omarchy, the `[omamobile]` repository configured and its keyring, `omamobile-shell`, the device package installed and the matching kernel modules. It is built by `pacstrap` in an aarch64 container. It contains no Google file. Its size is a few GB, flashed sparse; the first boot grows it to the whole `userdata` partition (`resize2fs` in the initramfs, before mounting).

The bundle's signed `SHA256SUMS` covers its `MANIFEST`, which names the exact root image and its SHA256 digest. The installer checks the selected image's name and bytes against that signed record before contacting the phone; changing the separate `.sha256` cannot authorize a replacement. Bundles use their own checked boot images; `--images` overrides are for repository mode. `--unsigned` remains available for development bundles, which use the root image's `.sha256` check.

**`install`** (`tools/install-phone`), run on the laptop with the phone in fastboot:

Expand Down
2 changes: 1 addition & 1 deletion tests/all
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ sh -n device/flame/initramfs/init
sh -n device/flame/initramfs/build
bash -n tools/build-flame-probe
echo "ok - scripts parse"
for t in tests/pr-check tests/kernel-pr-check tests/alarm-wake-test tests/install-phone tests/phone-provision tests/initramfs-grow tests/images-layout tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds; do
for t in tests/pr-check tests/kernel-pr-check tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/phone-provision tests/initramfs-grow tests/images-layout tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds; do
echo "# $t"
"$t"
done
Expand Down
109 changes: 109 additions & 0 deletions tests/build-rootfs
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
#!/bin/bash
# SPDX-License-Identifier: MIT
# Run the real builder with a small container stand-in: device namespaces,
# concurrent builds and failed-build cleanup, without an ARM image build.
set -euo pipefail
cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.."
for tool in zstd flock; do command -v "$tool" >/dev/null || { echo "skip: no $tool"; exit 0; }; done
fail() { echo "not ok - $*" >&2; exit 1; }
t=$(mktemp -d)
pid=""
cleanup() { touch "$t/release"; [[ -z $pid ]] || wait "$pid" 2>/dev/null || true; rm -rf "$t"; }
trap cleanup EXIT
R=$t/repo
mkdir -p "$R/tools/lib" "$R/tests" "$R/out/repo/aarch64" "$t/bin" "$t/kernel/include/config"
cp tools/build-rootfs tools/make-bundle tools/install-phone "$R/tools/"
touch "$R/out/repo/aarch64/omamobile.db" "$t/kernel/modules-fixture.tar.zst" "$t/alarm.tar"
echo fixture > "$t/kernel/include/config/kernel.release"
for device in first second; do
mkdir -p "$R/device/$device"
printf 'PACKAGE=omamobile-device-%s\nCODENAME=%s\nNAME="%s"\nBOOT_IMAGES="boot"\n' "$device" "$device" "$device" > "$R/device/$device/device.conf"
done
cat > "$R/tools/lib/alarm.sh" <<'EOF'
alarm_die() { echo "$*" >&2; exit 1; }
alarm_say() { echo "$*"; }
alarm_fetch() { :; }
alarm_build_image() { echo fixture; }
EOF
cat > "$t/bin/git" <<'EOF'
#!/bin/sh
if [ "$1" = rev-parse ]; then echo fixture; fi
EOF
cat > "$t/bin/docker" <<'EOF'
#!/bin/bash
set -euo pipefail
[[ $1 == run ]] || exit 0
work="" device=""
while (($#)); do
case $1 in
-v) [[ $2 != *:/out ]] || work=${2%:/out}; shift ;;
-e) [[ $2 != DEVICE=* ]] || device=${2#DEVICE=}; shift ;;
esac
shift
done
[[ -n $work && -n $device ]]
if [[ ${BLOCK_BUILD:-0} == 1 ]]; then
touch "$T/ready"
for ((i=0; i<100; i++)); do
[[ ! -e $T/release ]] || break
sleep 0.1
done
[[ -e $T/release ]]
fi
[[ ${FAIL_BUILD:-0} != 1 ]] || exit 1
printf '%s\n' "$device" > "$work/rootfs.img"
printf 'device: %s\n' "$device" > "$work/MANIFEST"
EOF
cat > "$R/tests/rootfs-smoke" <<'EOF'
#!/bin/bash
set -euo pipefail
[[ ${FAIL_SMOKE:-0} != 1 ]] || exit 1
zstd -qt "$1"
[[ -s ${1%.img.zst}.MANIFEST ]]
EOF
chmod +x "$t/bin/"* "$R/tests/rootfs-smoke"
export T=$t PATH="$t/bin:$PATH" KERNEL_OUT=$t/kernel ALARM_CACHE=$t/cache ALARM_TARBALL=$t/alarm.tar OMARCHY_CHANNEL=stable
build() { DEVICE=$1 "$R/tools/build-rootfs" --version fixture "${@:2}"; }
BLOCK_BUILD=1 build first > "$t/first.log" 2>&1 & pid=$!
for ((i=0; i<100; i++)); do [[ ! -e $t/ready ]] || break; sleep 0.05; done
[[ -e $t/ready ]] || { cat "$t/first.log"; fail "first build reached the container"; }
if build first > "$t/duplicate.log" 2>&1; then fail "concurrent builds of one artifact are refused"; fi
grep -q 'already building' "$t/duplicate.log" || { cat "$t/duplicate.log"; fail "names the conflicting build"; }
build second > "$t/second.log" 2>&1 || { cat "$t/second.log"; fail "another device can build concurrently"; }
touch "$t/release"
wait "$pid" || { cat "$t/first.log"; fail "first build completes"; }; pid=""
for device in first second; do
image=$R/out/omamobile-rootfs-$device-fixture-aarch64.img.zst
[[ $(zstd -qdc "$image") == "$device" ]] || fail "distinct $device image"
(cd "$R/out" && sha256sum -c "${image##*/}.sha256") >/dev/null
done
echo 'ok - different devices build concurrently; duplicate device/version is locked'

before=$(sha256sum "$R/out/omamobile-rootfs-first-fixture-aarch64.img.zst")
if FAIL_BUILD=1 build first > "$t/failed.log" 2>&1; then fail "container failure propagates"; fi
if FAIL_SMOKE=1 build first > "$t/failed.log" 2>&1; then fail "smoke failure propagates"; fi
[[ $(sha256sum "$R/out/omamobile-rootfs-first-fixture-aarch64.img.zst") == "$before" ]] || fail "failed rebuild preserves published image"
[[ -z $(find "$R/out" -maxdepth 1 -type d -name '.omamobile-rootfs-*') ]] || fail "temporary build directories are removed"
echo 'ok - failed rebuild preserves the previous image and removes only its own work'

mkdir -p "$R/keys/first" "$R/out/first/repo/aarch64"
touch "$R/keys/first/public.asc" "$R/out/first/repo/aarch64/omamobile.db"
build first --local first > "$t/local.log" 2>&1 || { cat "$t/local.log"; fail "local build"; }
[[ $(zstd -qdc "$R/out/first/omamobile-rootfs-first-fixture-aarch64.img.zst") == first ]] || fail "local image remains under out/first"
echo 'ok - --local keeps its device repository and output directory'

# Bundling must select this device even when another device sorts later.
mkdir -p "$t/kernel/images" "$R/packages/omamobile-keyring"
echo first > "$t/kernel/images/DEVICE"
echo boot > "$t/kernel/images/boot.img"
echo public-key > "$R/packages/omamobile-keyring/omamobile.gpg"
bundle() { DEVICE=first "$R/tools/make-bundle" --unsigned --version fixture "$@"; }
bundle > "$t/bundle.log" 2>&1 || { cat "$t/bundle.log"; fail "bundling selects this device's image"; }
image=omamobile-rootfs-first-fixture-aarch64.img.zst
digest=$(sha256sum < "$R/out/$image" | cut -d' ' -f1)
grep -Fxq "root image: $image ($digest)" "$R/out/bundle/omamobile-first-fixture/MANIFEST" || fail "bundle records the selected image and its actual digest"
if bundle --rootfs "$R/out/omamobile-rootfs-second-fixture-aarch64.img.zst" > "$t/bundle.log" 2>&1; then fail "bundling refuses another device's image"; fi
echo bad-checksum > "$R/out/$image.sha256"
if bundle > "$t/bundle.log" 2>&1; then fail "bundling refuses stale image checksum"; fi
grep -q "doesn't match its .sha256" "$t/bundle.log" || { cat "$t/bundle.log"; fail "bundling identifies the stale checksum"; }
echo 'ok - bundles select matching-device images and record verified bytes'
54 changes: 53 additions & 1 deletion tests/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,12 @@ SRC=$PWD
fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; }
pass() { printf 'ok - %s\n' "$1"; }
for tool in debugfs mkfs.ext4 zstd openssl; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done
t=$(mktemp -d); trap '[[ -n ${KEEP:-} ]] || rm -rf "$t"' EXIT
t=$(mktemp -d)
cleanup() {
[[ ! -d $t/gnupg ]] || gpgconf --homedir "$t/gnupg" --kill gpg-agent 2>/dev/null || true
[[ -n ${KEEP:-} ]] || rm -rf "$t"
}
trap cleanup EXIT

# A repository-shaped tree: the script, a descriptor, images, a tiny root image
R=$t/repo
Expand Down Expand Up @@ -98,6 +103,14 @@ grep -qF 'correct horse' "$t/out" && fail "the Wi-Fi password is never printed"
[[ -z $(ls "$t/work") ]] || fail "the image copy (with the password hash) is removed"
pass "dry run: exactly the allowed commands printed, only getvar sent"

# An adjacent image for another device must not change the default selection.
other=$R/out/omamobile-rootfs-zother-2099.01.01-aarch64.img.zst
cp "$img" "$other"
printf 'device: zother\n' > "${other%.img.zst}.MANIFEST"
install --dry-run || { cat "$t/out"; fail "default root selection ignores another device"; }
rm "$other" "${other%.img.zst}.MANIFEST"
pass "default selection matches the device, including legacy filenames"

install || { cat "$t/out"; fail "a full run succeeds"; }
want="-s FAKE123 flash boot_b $t/images/boot.img
-s FAKE123 flash init_boot_b $t/images/init_boot.img
Expand Down Expand Up @@ -227,6 +240,7 @@ cp tools/install-phone "$BD/install"
cp "$R/device/testdev/device.conf" "$BD/device.conf"
for p in boot init_boot vendor_boot vendor_kernel_boot dtbo; do cp "$t/images/$p.img" "$BD/images/"; done
cp "$img" "$img.sha256" "$R/out/omamobile-rootfs-2026.10.13-aarch64.MANIFEST" "$t/bundle/"
printf 'kernel release: 7.3.0-test-1\nroot image: %s (%s)\n' "$(basename "$img")" "$(cut -d' ' -f1 "$img.sha256")" > "$BD/MANIFEST"
(cd "$BD" && find . -type f ! -name SHA256SUMS -printf '%P\n' | sort | xargs sha256sum > SHA256SUMS)
binstall() {
: > "$t/fastboot.log"
Expand All @@ -246,6 +260,44 @@ if command -v gpg >/dev/null; then
gpg --homedir "$G" -q --batch --detach-sign -o "$BD/SHA256SUMS.sig" "$BD/SHA256SUMS"
if binstall --dry-run; then fail "refuses a bundle signed by another key"; fi
grep -q 'not signed by the Omarchy Mobile key' "$t/out" || fail "says the signature is not the release key's"

# Trust only this ephemeral key in the copied installer. Sign and verify
# real bundle bytes with GPG; production's pinned keys stay unchanged.
signer=$(gpg --homedir "$G" --with-colons --list-keys 2>/dev/null | awk -F: '$1 == "fpr" {print $10; exit}')
sed -i "s/^SIGNING_KEYS=.*/SIGNING_KEYS='$signer'/" "$BD/install"
seal() {
(cd "$BD" && find . -type f ! -name SHA256SUMS ! -name SHA256SUMS.sig -printf '%P\n' | sort | xargs sha256sum > SHA256SUMS)
gpg --homedir "$G" -q --batch --yes --detach-sign -o "$BD/SHA256SUMS.sig" "$BD/SHA256SUMS"
}
seal
binstall --dry-run || { cat "$t/out"; fail "a bundle signed by the pinned fixture key installs"; }
if binstall --dry-run --images "$t/images"; then fail "refuses images outside the signed bundle"; fi
[[ ! -s $t/fastboot.log ]] || fail "rejects unsigned boot images before contacting the phone"
grep -q 'a bundle uses its own images' "$t/out" || { cat "$t/out"; fail "names the external images refusal"; }
# The signed name wins over a newer neighbour, and --rootfs cannot rename it.
other=$t/bundle/omamobile-rootfs-zother-2099.01.01-aarch64.img.zst
cp "$img" "$other"
binstall --dry-run || { cat "$t/out"; fail "signed bundle selects exactly its named root image"; }
if binstall --dry-run --rootfs "$other"; then fail "refuses the right bytes under an unsigned name"; fi
[[ ! -s $t/fastboot.log ]] || fail "rejects an unsigned root name before contacting the phone"
rm "$other"
# Another matching-device image with its own valid checksum must not
# replace the root image named in the signed manifest.
cp "$t/root.img" "$t/changed.img"
printf 'substituted image\n' > "$t/changed.txt"
debugfs -w -R "write $t/changed.txt /etc/substituted" "$t/changed.img" >/dev/null 2>&1
zstd -q "$t/changed.img" -o "$t/changed.img.zst"
cp "$t/changed.img.zst" "$t/bundle/$(basename "$img")"
(cd "$t/bundle" && sha256sum "$(basename "$img")" > "$(basename "$img").sha256")
if binstall --dry-run; then fail "refuses a substituted root image with an updated checksum"; fi
[[ ! -s $t/fastboot.log ]] || fail "rejects substituted root before contacting the phone"
grep -q 'root image does not match the signed bundle' "$t/out" || { cat "$t/out"; fail "names the signed root mismatch"; }
cp "$img" "$img.sha256" "$t/bundle/"
# The manifest itself must be covered by the signed checksums.
sed -i '/ MANIFEST$/d' "$BD/SHA256SUMS"
gpg --homedir "$G" -q --batch --yes --detach-sign -o "$BD/SHA256SUMS.sig" "$BD/SHA256SUMS"
if binstall --dry-run; then fail "refuses a manifest outside the signed checksums"; fi
[[ ! -s $t/fastboot.log ]] || fail "rejects an unauthenticated manifest before contacting the phone"
fi
[[ -z $(flashing_calls) ]] || fail "a refused bundle flashes nothing"
pass "bundle mode: signature required (pinned key), checksums checked, its own images used"
Expand Down
2 changes: 1 addition & 1 deletion tests/rootfs-smoke
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
# SPDX-License-Identifier: MIT
# Smoke test of a root image from tools/build-rootfs, read through debugfs
# (no root, no loop mount, nothing written):
# tests/rootfs-smoke out/omamobile-rootfs-<version>-aarch64.img.zst (or a raw .img)
# tests/rootfs-smoke out/omamobile-rootfs-<device>-<version>-aarch64.img.zst (or a raw .img)
# Checks the label, that there is no account but a locked root, the keyrings,
# the [omamobile] repository and its place in pacman.conf, the first-boot
# unit, the kernel modules, the MANIFEST, and that no per-machine state,
Expand Down
Loading