From 7fca38e634b6810721b73d15ded01164656d7d62 Mon Sep 17 00:00:00 2001 From: Chris Gray Date: Wed, 11 Nov 2026 12:06:37 -0600 Subject: [PATCH] install-phone: preserve development boot-update policy Keep the existing --serial pin unchanged. Accept only yes or no for the descriptor boot-update policy before preparing an image or contacting a phone; omitted policy retains the existing release image. Verify the prepared development image and fail-before-query behavior. Co-Authored-By: Codex --- docs/RELEASES.md | 13 +++++++++++++ tests/install-phone | 18 ++++++++++++++++++ tools/install-phone | 15 +++++++++------ 3 files changed, 40 insertions(+), 6 deletions(-) diff --git a/docs/RELEASES.md b/docs/RELEASES.md index ca3239b46..9d88dea22 100644 --- a/docs/RELEASES.md +++ b/docs/RELEASES.md @@ -79,6 +79,7 @@ Bring-up tools (`*-stage`, `display-hz`, `usbc-deadman`) stay per plan: they pok | `BOOT_METHOD` | `android-v4` (default when omitted) | Generic images, flash, push and installer accept only `android-v4`; other methods are refused before phone access. `ram-only` marks a probe with no persistent install support. `android-v0` (enchilada) is a header-v0 phone: `images` packs one `boot.img` for `fastboot boot`, and fastboot, flash, push and the installer refuse it | | `PAGESIZE`, `BASE`, `KERNEL_OFFSET`, `RAMDISK_OFFSET`, `SECOND_OFFSET`, `TAGS_OFFSET` | (enchilada: `4096`, `0x00000000`, `0x00008000`, `0x01000000`, `0x00f00000`, `0x00000100`) | `android-v0` only, all required: the header-v0 page size and load offsets, numbers in decimal or lower-case hex. `images` packs the gzip `Image` with the `DTB` appended as the kernel, the initramfs as the ramdisk and `CMDLINE` as the command line. `BOOT_IMAGES` is `boot` alone and `boot_b` must be on `UFS_RW` | | `BOOT_IMAGES` | `boot init_boot vendor_boot vendor_kernel_boot dtbo` | The images written to slot B (the `_b` suffix is added by the tools and is not configurable). `boot`, `vendor_boot` and `dtbo` are always there. Without `init_boot`, `boot` carries the empty generic ramdisk and the OS version; without `vendor_kernel_boot`, `vendor_boot` carries the DTB and the initramfs (the Pixel 6: `boot vendor_boot dtbo`) | +| `BOOT_UPDATE_AUTO_WRITE` | (unset; defaults to `yes`) | Optional: `yes` or `no`. The installer records it as `AUTO_WRITE` in `/etc/omamobile/boot-update.conf`; `no` keeps an installed development root from writing slot B through package updates. It does not change the installer's own allowed writes | | `UFS_RW` | `boot_b … dtbo_b userdata` | The storage guard's allowlist, packed into the initramfs as `/etc/omamobile-ufs-rw`. Only slot B's boot images (`boot_b`, `init_boot_b`, `vendor_boot_b`, `vendor_kernel_boot_b`, `dtbo_b`) and `userdata` are accepted, `userdata` and every `BOOT_IMAGES` entry must be on it, and each name only once. The init fails closed: a missing, empty or malformed file, or any other name in it, leaves every partition read-only | | `UFS_RW_LUNS` | (unset) | Optional. The LUNs besides `sda` that hold `UFS_RW` partitions, as disk names `sdb` to `sdz`, packed as `/etc/omamobile-ufs-rw-luns`. The init guards each as it guards `sda`: the whole-disk node removed, the disk left writable, and only its `UFS_RW` partitions left writable. Absent (every descriptor so far), malformed, or with a closed allowlist: every LUN but `sda` stays read-only at the disk level. Boot-image writers on the phone (`omamobile-boot-update`) still look only on `sda` | | `INITRAMFS_INIT` | `/initramfs/init` | The init script. A leading `/` is relative to the repo root, so devices share one script. Any other value is relative to the descriptor | @@ -341,6 +342,18 @@ The bundle's signed `SHA256SUMS` covers its `MANIFEST`, which names the exact ro - **Server:** `tools/server/releases-nginx.sh`, run once by the maintainer with sudo on the server, adds a `location ^~ /releases/` to the `pkgs.omamobile.org` vhost. The vhost already serves `/releases/` as plain files: a missing file is a 404, and byte ranges and `Content-Length` work. The script adds `Access-Control-Allow-Origin: *` with the exposed range headers and an answer to `OPTIONS` preflights, `Cross-Origin-Resource-Policy: cross-origin`, MIME types for `.json`, `.zst`, `.img`, `.sig` and `.sha256`, no gzip (so sizes stay exact), a year's immutable cache on version directories (but not on their 404s), `no-cache` on `latest.json`, a 403 for the upload's staging directories, and the security-headers snippet in every location. It does a dry run first, `nginx -t`, a verified reload and live checks, and it rolls back on any failure (`revert` undoes it). - **Bandwidth:** each install downloads about 2.8 GB (a 2.7 GB root image plus about 80 MB of boot images, from the `.tar` or file by file; the `.tar` doubles the storage a release takes on the server, not the transfer), so 1 TB of transfer is about 350 installs. GitHub's per-file limit is 2 GiB, so a root image there would have to be split and joined again, which a browser flasher and the signed manifest would both have to know about. Our own server stays the one source; check the VPS plan's monthly transfer allowance before announcing a release. +### Development installer policy + +A device descriptor may set `BOOT_UPDATE_AUTO_WRITE=no` to keep an installed +development root from writing boot images through package updates. The +installer records that value in `/etc/omamobile/boot-update.conf`; descriptors +that omit the key retain `AUTO_WRITE=yes`. Only `yes` and `no` are accepted. +This does not change which partitions the installer itself writes. + +Use `tools/install-phone --serial ` to pin the phone for an install; +this is the installer's existing command-line check, independent of the +automatic boot-update policy. + ## 7. Versions and tags | Thing | Version | Where it is recorded | diff --git a/tests/install-phone b/tests/install-phone index a3069366f..ed2820414 100755 --- a/tests/install-phone +++ b/tests/install-phone @@ -162,6 +162,24 @@ OMAMOBILE_FIRSTBOOT_ROOT=$t/fbroot "$SRC/packages/omamobile-firstboot/bin/omamob [[ $(debugfs -R 'cat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -v '^#') == AUTO_WRITE=yes ]] \ || fail "a release install turns the boot hook on (boot-update.conf AUTO_WRITE=yes)" debugfs -R 'stat /etc/omamobile/boot-update.conf' "$flashed" 2>/dev/null | grep -c 'User: 0 Group: 0' >/dev/null || fail "boot-update.conf belongs to root" +# Development devices keep the hook off in the actual prepared image. +echo 'BOOT_UPDATE_AUTO_WRITE=no' >> "$R/device/testdev/device.conf" +install || { cat "$t/out"; fail "a development install succeeds"; } +policy_image=$t/userdata.flashed +if command -v simg2img >/dev/null && [[ $(head -c4 "$policy_image" | od -An -tx1 | tr -d ' ') == 3aff26ed ]]; then + simg2img "$policy_image" "$t/policy.img"; policy_image=$t/policy.img +fi +[[ $(debugfs -R 'cat /etc/omamobile/boot-update.conf' "$policy_image" 2>/dev/null | grep -v '^#') == AUTO_WRITE=no ]] || + fail "the development image must disable automatic boot writes" +pass "development descriptor keeps automatic boot writes off in the image" +for value in '' YES true maybe; do + descriptor > "$R/device/testdev/device.conf" + printf 'BOOT_UPDATE_AUTO_WRITE=%s\n' "$value" >> "$R/device/testdev/device.conf" + if install --dry-run; then fail "invalid boot-update policy accepted: $value"; fi + [[ ! -s $t/fastboot.log ]] || fail 'invalid boot-update policy reached fastboot' +done +descriptor > "$R/device/testdev/device.conf" +pass "invalid boot-update policies refuse before any phone query" pass "the image copy gets a root-only firstboot.conf (hash, not password) and root's key, which firstboot accepts" # A root that already has /etc/omamobile and /root/.ssh (a restored or diff --git a/tools/install-phone b/tools/install-phone index c109848a4..fc597d600 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -28,10 +28,10 @@ # time zone, optional Wi-Fi and the SSH public key, writes them as # /etc/omamobile/firstboot.conf (and root's authorized_keys) into a LOCAL # COPY of the root image with debugfs (no root needed), with -# /etc/omamobile/boot-update.conf (AUTO_WRITE=yes: kernel package updates -# reach slot B through omamobile-boot-update, docs/RELEASES.md §5.3; a -# development phone, set up by hand, has no such file), shows exactly what it -# will run, and waits for the codename to be typed. The phone's first boot +# /etc/omamobile/boot-update.conf (AUTO_WRITE defaults to yes; descriptors +# may set BOOT_UPDATE_AUTO_WRITE=no to keep development kernel updates off +# slot B, docs/RELEASES.md §5.3), shows exactly what it will run, and waits +# for the codename to be typed. The phone's first boot # (omamobile-firstboot) creates the user from that file and deletes it. # The key also goes into a copy of slot B's ramdisk image, as # omamobile-boot-update appends it, so the initramfs's rescue SSH takes it. @@ -151,6 +151,9 @@ while IFS= read -r line || [[ -n $line ]]; do done < "$conf" CODENAME=${D[CODENAME]:-} [[ $CODENAME =~ ^[a-z0-9]+$ ]] || die "$conf: no CODENAME" +BOOT_UPDATE_AUTO_WRITE=${D[BOOT_UPDATE_AUTO_WRITE]-yes} +[[ $BOOT_UPDATE_AUTO_WRITE == yes || $BOOT_UPDATE_AUTO_WRITE == no ]] ||\ + die "$conf: BOOT_UPDATE_AUTO_WRITE must be yes or no" [[ $mode == bundle || $CODENAME == "$device" ]] || die "$conf: CODENAME=$CODENAME, expected $device" # Legacy descriptors omit BOOT_METHOD; only their Android v4 path is installable. # Refuse before image preparation or any fastboot query/write. @@ -547,7 +550,7 @@ trap cleanup EXIT printf '%s\n' "$ssh_key" > "$keys_file" printf '%s\n' "# Written by install-phone: a release install takes kernel updates through" \ "# omamobile-boot-update's pacman hook (docs/RELEASES.md §5.3). AUTO_WRITE=no stops it." \ - "AUTO_WRITE=yes" > "$boot_conf" + "AUTO_WRITE=$BOOT_UPDATE_AUTO_WRITE" > "$boot_conf" ) unset wifi_psk @@ -590,7 +593,7 @@ cmp -s <(debugfs -R "cat /etc/omamobile/firstboot.conf" "$copy" 2>/dev/null) "$c cmp -s <(debugfs -R "cat /root/.ssh/authorized_keys" "$copy" 2>/dev/null) "$keys_file" || die "writing authorized_keys into the image copy failed" cmp -s <(debugfs -R "cat /etc/omamobile/boot-update.conf" "$copy" 2>/dev/null) "$boot_conf" || die "writing boot-update.conf into the image copy failed" e2fsck -fn "$copy" >/dev/null 2>&1 || die "the image copy doesn't check clean after the writes" -note "firstboot.conf, root's authorized_keys and boot-update.conf (AUTO_WRITE=yes) written, file system checks clean" +note "firstboot.conf, root's authorized_keys and boot-update.conf (AUTO_WRITE=$BOOT_UPDATE_AUTO_WRITE) written, file system checks clean" userdata_image=$copy if command -v img2simg >/dev/null; then img2simg "$copy" "$sparse"