From 91b8d5699c567cc41c508ce80c5921803428ec40 Mon Sep 17 00:00:00 2001 From: Nate Crawford Date: Tue, 17 Nov 2026 18:26:11 -0600 Subject: [PATCH 1/2] install-phone: always flash userdata sparse, with room checked first The installer flashed userdata as an Android sparse image when img2simg was installed and as the raw image otherwise, so the same command took two different paths depending on the host, and the dry run's printed commands changed with it. img2simg also ran unchecked: on a work directory without room for the sparse copy it failed part way, after the image copy had been prepared. img2simg is now required with the other tools (from android-tools, like fastboot, and already in CI), and userdata is always the sparse image. Before converting, the installer checks that --work has the raw copy's used blocks (it is decompressed with --sparse, so far fewer than its apparent size) plus 1 GiB free, and refuses with the numbers if not; a failing img2simg stops the install. Nothing is flashed in either case, and the copy is removed as before. tests/install-phone: img2simg and simg2img join the required tools, the raw-image fallbacks in the expected commands go, and a df that reports no room checks the refusal: no flash and no copy left behind. tests/install-phone-initramfs and tests/install-guided, which run the real installer, skip without img2simg as they do without its other tools. Co-Authored-By: Claude Opus 5.5 --- tests/install-guided | 2 +- tests/install-phone | 23 ++++++++++++++++++----- tests/install-phone-initramfs | 2 +- tools/install-phone | 34 ++++++++++++++++++++++------------ 4 files changed, 42 insertions(+), 19 deletions(-) diff --git a/tests/install-guided b/tests/install-guided index 84f31cf6c..ab79956da 100755 --- a/tests/install-guided +++ b/tests/install-guided @@ -41,7 +41,7 @@ pass() { printf 'ok - %s\n' "$1"; } # skipped every case here (as every run did while the workflow installed no # unzip) says nothing. Elsewhere the skip is said on both streams, with # what it leaves unchecked. -for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio gpg unzip python3 curl; do +for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio gpg unzip python3 curl img2simg; do command -v $tool >/dev/null && continue if [[ -n ${CI:-}${GITHUB_ACTIONS:-} ]]; then echo "not ok - tests/install-guided can't run in CI: no $tool (add it to .github/workflows/checks.yml)" >&2 diff --git a/tests/install-phone b/tests/install-phone index ac0f3c9e5..cf7bd8f1c 100755 --- a/tests/install-phone +++ b/tests/install-phone @@ -13,7 +13,7 @@ cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." 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 lz4 cpio timeout; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done +for tool in debugfs mkfs.ext4 zstd openssl lz4 cpio timeout img2simg simg2img; do command -v $tool >/dev/null || { echo "skip: no $tool"; exit 0; }; done t=$(mktemp -d) cleanup() { [[ ! -d $t/gnupg ]] || gpgconf --homedir "$t/gnupg" --kill gpg-agent 2>/dev/null || true @@ -195,6 +195,23 @@ install() { flashing_calls() { grep -v -E '^(devices|-s FAKE123 getvar all)$' "$t/fastboot.log" || true; } vars "" "" $'version-bootloader-a:cloudripper-17.0-15199429\nversion-bootloader-b:cloudripper-17.0-15199429' +# Too little room in --work for the sparse copy: refused before any flash. +real_df=$(command -v df) +cat > "$t/bin/df" </dev/null || { cat "$t/out"; fail "the refusal names the room the sparse copy needs"; } +[[ -z $(flashing_calls) ]] || fail "too little room flashes nothing: $(flashing_calls)" +[[ -z $(ls "$t/work") ]] || fail "a refusal for room removes the image copy" +pass "too little room in --work for the sparse copy: refused, nothing flashed, the copy removed" + install --dry-run || { cat "$t/out"; fail "a dry run succeeds"; } expected=" would run: fastboot -s FAKE123 flash boot_b $t/images/boot.img would run: fastboot -s FAKE123 flash init_boot_b $t/images/init_boot.img @@ -204,7 +221,6 @@ expected=" would run: fastboot -s FAKE123 flash boot_b $t/images/boot.img would run: fastboot -s FAKE123 flash userdata $t/work/root.simg would run: fastboot -s FAKE123 --set-active=b would run: fastboot -s FAKE123 reboot" -command -v img2simg >/dev/null || expected=${expected//root.simg/root.img} [[ $(grep 'would run:' "$t/out") == "$expected" ]] || { grep 'would run:' "$t/out"; fail "the dry run prints exactly the allowed commands"; } [[ -z $(flashing_calls) ]] || fail "a dry run only reads variables: $(flashing_calls)" grep -qF 'correct horse' "$t/out" && fail "the Wi-Fi password is never printed" @@ -228,7 +244,6 @@ want="-s FAKE123 flash boot_b $t/images/boot.img -s FAKE123 flash userdata $t/work/root.simg -s FAKE123 --set-active=b -s FAKE123 reboot" -command -v img2simg >/dev/null || want=${want//root.simg/root.img} [[ $(flashing_calls) == "$want" ]] || { flashing_calls; fail "a run sends exactly the allowed commands"; } grep -c 'bootloader cloudripper-17.0-15199429 on both slots$' "$t/out" >/dev/null || fail "per-slot versions from the phone are compared as they are" pass "full run: fastboot gets exactly slot B's images, userdata, set-active b, reboot (per-slot versions reported: no slot round trip)" @@ -1065,7 +1080,6 @@ expected=" would run: fastboot -s FAKE123 flash boot_a $t/images2/boot.img would run: fastboot -s FAKE123 flash dtbo_a $t/images2/dtbo.img would run: fastboot -s FAKE123 flash userdata $t/work/root.simg would run: fastboot -s FAKE123 reboot" -command -v img2simg >/dev/null || expected=${expected//root.simg/root.img} [[ $(grep 'would run:' "$t/out") == "$expected" ]] || { grep 'would run:' "$t/out"; fail "a format 2 dry run prints slot a's images, userdata and reboot, nothing else"; } [[ -z $(flashing_calls) ]] || fail "a format 2 dry run only reads variables: $(flashing_calls)" grep -c 'Android on this phone is REPLACED' "$t/out" >/dev/null && grep -c "Google's factory image" "$t/out" >/dev/null || @@ -1082,7 +1096,6 @@ want="-s FAKE123 flash boot_a $t/images2/boot.img -s FAKE123 flash dtbo_a $t/images2/dtbo.img -s FAKE123 flash userdata $t/work/root.simg -s FAKE123 reboot" -command -v img2simg >/dev/null || want=${want//root.simg/root.img} [[ $(flashing_calls) == "$want" ]] || { flashing_calls; fail "a format 2 run sends exactly slot a's images, userdata and reboot"; } [[ $(grep -c '^-s FAKE123 getvar all$' "$t/fastboot.log") == 3 ]] || fail "the phone is read three times: the first look, the gate before the first flash, the read-back" grep -c 'Done. The phone starts Omarchy Mobile from slot a' "$t/out" >/dev/null || fail "a format 2 run ends with the slot it wrote" diff --git a/tests/install-phone-initramfs b/tests/install-phone-initramfs index 108326a42..a766a0e8d 100755 --- a/tests/install-phone-initramfs +++ b/tests/install-phone-initramfs @@ -37,7 +37,7 @@ PKG=$SRC/packages/omamobile-boot-update fail() { printf 'not ok - %s\n' "$1" >&2; exit 1; } pass() { printf 'ok - %s\n' "$1"; } skip() { printf 'ok - # skip: %s\n' "$1"; exit 0; } -for tool in lz4 cpio dtc debugfs mkfs.ext4 zstd openssl python3 flock; do command -v $tool >/dev/null || skip "no $tool"; done +for tool in lz4 cpio dtc debugfs mkfs.ext4 zstd openssl python3 flock img2simg; do command -v $tool >/dev/null || skip "no $tool"; done t=$(mktemp -d) trap '[[ -n ${KEEP:-} ]] || rm -rf "$t"' EXIT diff --git a/tools/install-phone b/tools/install-phone index 0d14cf940..4b6a2205c 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -78,9 +78,11 @@ # image for this device in out/, or the exact # image named by a signed bundle's MANIFEST) # --work DIR where the local image copy goes (default -# ~/.cache/omamobile-install; needs the image's -# size free). The next run that finds no other -# run live removes killed runs' verify.* +# ~/.cache/omamobile-install; needs room for the +# image's used blocks twice, the copy and its +# sparse conversion, plus 1 GiB). The next run +# that finds no other run live removes killed +# runs' verify.* # directories; ones left by installers without # this cleanup are kept # --bootloader-slots-match VERSION @@ -281,8 +283,8 @@ if [[ $mode == repository ]]; then [[ $built_for == "$CODENAME" ]] \ || die "$images holds images for '${built_for:-an unknown device}', not $CODENAME (run: DEVICE=$CODENAME bin/omamobile images)" fi -for tool in "$FASTBOOT" debugfs dumpe2fs e2fsck zstd openssl sha256sum lz4 cpio python3 timeout; do - command -v "$tool" >/dev/null || die "$tool not found (fastboot: android-tools; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)" +for tool in "$FASTBOOT" debugfs dumpe2fs e2fsck img2simg zstd openssl sha256sum lz4 cpio python3 timeout; do + command -v "$tool" >/dev/null || die "$tool not found (fastboot, img2simg: android-tools; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)" done BOOT_IMAGES=${D[BOOT_IMAGES]:-} UFS_RW=${D[UFS_RW]:-} [[ -n $BOOT_IMAGES && -n $UFS_RW ]] || die "$conf: BOOT_IMAGES and UFS_RW are required" @@ -1200,13 +1202,21 @@ cmp -s <(debugfs -R "cat /root/.ssh/authorized_keys" "$copy" 2>/dev/null) "$keys 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=$BOOT_UPDATE_AUTO_WRITE$( ((fmt == 1)) || printf ', SLOT=%s' "$target")) written, file system checks clean" -userdata_image=$copy -if command -v img2simg >/dev/null; then - img2simg "$copy" "$sparse" - rm -f "$copy" - userdata_image=$sparse - note "converted to an Android sparse image ($(du -h "$sparse" | cut -f1))" -fi +# userdata is always flashed as an Android sparse image: one path, the one +# the dry run prints. The sparse copy takes about the raw copy's used blocks +# (decompressed with --sparse, so far fewer than its apparent size): check +# for that much free plus 1 GiB rather than let img2simg run out of room. +used_bytes=$(du -k "$copy" | awk '{printf "%.0f\n", $1 * 1024}') +free_bytes=$(df -Pk "$work" | awk 'NR == 2 {printf "%.0f\n", $4 * 1024}') +[[ $used_bytes =~ ^[0-9]+$ && $free_bytes =~ ^[0-9]+$ ]] || + die "can't tell the image copy's size or the free space in $work" +need=$((used_bytes + 1073741824)) +((free_bytes >= need)) || + die "$work has $free_bytes bytes free; the sparse copy needs $need (give a --work DIR on a larger file system)" +img2simg "$copy" "$sparse" || die "img2simg failed to convert the image copy in $work" +rm -f "$copy" +userdata_image=$sparse +note "converted to an Android sparse image ($(du -h "$sparse" | cut -f1))" # --- The owner's key in slot B's initramfs ----------------------------------- # omamobile-boot-update builds slot B's ramdisk with root's authorized_keys From 09cafa5824f270b6fbfc63fdb87b82c4eedc731b Mon Sep 17 00:00:00 2001 From: Derek Ross Date: Wed, 18 Nov 2026 13:12:25 -0500 Subject: [PATCH 2/2] install-guided, docs: img2simg is needed on the computer The guided install's preflight and package table name img2simg, with a case in its test; install-phone's hint gives the Debian and Ubuntu package; INSTALL, INSTALL-GUIDED and the bundle's README list it. Co-Authored-By: Claude Fable 5.2 --- docs/INSTALL-GUIDED.md | 2 +- docs/INSTALL.md | 2 +- tests/install-guided | 10 +++++++--- tools/install-guided | 6 ++++-- tools/install-phone | 2 +- tools/make-bundle | 2 +- 6 files changed, 15 insertions(+), 9 deletions(-) diff --git a/docs/INSTALL-GUIDED.md b/docs/INSTALL-GUIDED.md index 35c4584fc..6fc0d192e 100644 --- a/docs/INSTALL-GUIDED.md +++ b/docs/INSTALL-GUIDED.md @@ -99,7 +99,7 @@ Details that matter: - **Step 1** asks for every program the later steps run, so a missing one stops the install before the phone is erased, not after: `fastboot`, `debugfs`, `dumpe2fs`, `e2fsck`, `zstd`, `lz4`, `cpio`, `openssl`, `gpg`, - `python3`, `unzip`, `ssh`, `sha256sum`, `tar`, and for step 9's extract + `python3`, `unzip`, `ssh`, `sha256sum`, `tar`, `img2simg`, and for step 9's extract tools `lpunpack`, `simg2img`, `fsck.erofs` and `readelf` (or `llvm-readelf`). The stop names each missing program with its package on Arch Linux (and Omarchy) and on Debian and Ubuntu (a table in the diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 46c2ad71f..9e9738dbe 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -24,7 +24,7 @@ It takes about an hour, most of it downloads and waiting. **New to this? Use [th sudo pacman -S --needed android-tools e2fsprogs zstd lz4 cpio openssl gnupg python unzip binutils erofs-utils ``` - On other distributions, install the packages with the same names (Android's tools are often split into `fastboot`, `adb` and a "libsparse" package for `img2simg` and `simg2img`). + On other distributions, install the packages with the same names. Android's tools are often split into `fastboot`, `adb` and a "libsparse" package for `img2simg` and `simg2img` (`android-sdk-libsparse-utils` on Debian and Ubuntu), and the installer needs `img2simg`: Google's platform-tools download doesn't have it. - **Free disk space:** about 35 GB (the downloads, Google's factory image and a working copy of the system image while installing). - **An SSH key.** The installer puts your public key on the phone so your computer can reach it over USB later. If `~/.ssh/id_ed25519.pub` doesn't exist, make one: diff --git a/tests/install-guided b/tests/install-guided index ab79956da..1290775c0 100755 --- a/tests/install-guided +++ b/tests/install-guided @@ -1688,9 +1688,13 @@ done printf 'NAME="Arch Linux"\nID=arch\n' > "$t/os-arch" printf 'NAME="Ubuntu"\nID=ubuntu\nID_LIKE=debian\n' > "$t/os-ubuntu" printf 'NAME="Other"\nID=other\n' > "$t/os-other" -# missing ARCH-PACKAGE DEBIAN-PACKAGE (Debian's "-": none we know of) -for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsparse-utils" "fsck.erofs erofs-utils erofs-utils" "readelf binutils binutils"; do +# missing ARCH-PACKAGE DEBIAN-PACKAGE (Debian's "-": none we know of). +# img2simg is this computer's own (the installer runs it), so its link goes +# for its own turn only +real_img2simg=$(readlink -f "$t/sys/img2simg") +for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsparse-utils" "img2simg android-tools android-sdk-libsparse-utils" "fsck.erofs erofs-utils erofs-utils" "readelf binutils binutils"; do read -r missing arch deb <<<"$spec" + ln -sfn "$real_img2simg" "$t/sys/img2simg"; [[ $missing != img2simg ]] || rm -f "$t/sys/img2simg" rm -f "$t/sys/lpunpack" "$t/sys/simg2img" "$t/sys/fsck.erofs" "$t/sys/readelf" "$t/sys/llvm-readelf" mkdir -p "$t/extract-some"; rm -f "$t/extract-some/"* for c in lpunpack simg2img fsck.erofs readelf; do [[ $c == "$missing" ]] || cp "$t/extract-bin/$c" "$t/extract-some/"; done @@ -1714,7 +1718,7 @@ for spec in "lpunpack android-tools -" "simg2img android-tools android-sdk-libsp [[ $(tail -n 1 "$t/out") == " tools/install-guided "* ]] || fail "a missing $missing: the stop ends with the command to run once it is installed" done done -pass "a program a later step needs (lpunpack, simg2img, fsck.erofs, readelf) stops the install at step 1, named with its package on Arch and on Debian and Ubuntu, and the one install command for this system" +pass "a program a later step needs (lpunpack, simg2img, img2simg, fsck.erofs, readelf) stops the install at step 1, named with its package on Arch and on Debian and Ubuntu, and the one install command for this system" # --- The real tools/phone-provision takes what the installer hands it --------------- # Everywhere above phone-provision is a stub, and a stub accepts anything: diff --git a/tools/install-guided b/tools/install-guided index a24d4d09b..3f3820a56 100755 --- a/tools/install-guided +++ b/tools/install-guided @@ -558,6 +558,7 @@ PACKAGES=( "tar tar tar" "lpunpack android-tools -" "simg2img android-tools android-sdk-libsparse-utils" + "img2simg android-tools android-sdk-libsparse-utils" "fsck.erofs erofs-utils erofs-utils" "readelf binutils binutils" ) @@ -598,11 +599,12 @@ step_preflight() { title preflight # Every program a later step runs, asked for now: one that is missing must # stop the install here, not after the phone has been erased. The writes - # (tools/install-phone), the radio backup (tools/nv-backup) and the + # (tools/install-phone, which needs img2simg for the sparse userdata + # image), the radio backup (tools/nv-backup) and the # firmware (tools/phone-provision and the extract tools it runs: lpunpack, # simg2img, fsck.erofs, debugfs, readelf). for t in "$FASTBOOT" debugfs dumpe2fs e2fsck zstd lz4 cpio openssl gpg python3 unzip ssh sha256sum \ - tar lpunpack simg2img fsck.erofs; do + tar img2simg lpunpack simg2img fsck.erofs; do command -v "$t" >/dev/null || missing+=("${t##*/}") done command -v readelf >/dev/null || command -v llvm-readelf >/dev/null || missing+=(readelf) diff --git a/tools/install-phone b/tools/install-phone index 4b6a2205c..026fecb8f 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -284,7 +284,7 @@ if [[ $mode == repository ]]; then || die "$images holds images for '${built_for:-an unknown device}', not $CODENAME (run: DEVICE=$CODENAME bin/omamobile images)" fi for tool in "$FASTBOOT" debugfs dumpe2fs e2fsck img2simg zstd openssl sha256sum lz4 cpio python3 timeout; do - command -v "$tool" >/dev/null || die "$tool not found (fastboot, img2simg: android-tools; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)" + command -v "$tool" >/dev/null || die "$tool not found (fastboot, img2simg: android-tools, or fastboot and android-sdk-libsparse-utils on Debian and Ubuntu; debugfs: e2fsprogs; lz4: lz4; cpio: cpio)" done BOOT_IMAGES=${D[BOOT_IMAGES]:-} UFS_RW=${D[UFS_RW]:-} [[ -n $BOOT_IMAGES && -n $UFS_RW ]] || die "$conf: BOOT_IMAGES and UFS_RW are required" diff --git a/tools/make-bundle b/tools/make-bundle index 98773772c..f9a446099 100755 --- a/tools/make-bundle +++ b/tools/make-bundle @@ -303,7 +303,7 @@ needs you. Run it again after any stop: it goes on from there. Install by hand: put the phone in fastboot mode (bootloader unlocked), connect it, and run "bash install" from this directory ("bash install" works even when a download lost the file's execute bit). It needs fastboot -(android-tools), e2fsprogs, zstd, lz4, cpio, openssl, gpg and python3 on +and img2simg (android-tools), e2fsprogs, zstd, lz4, cpio, openssl, gpg and python3 on this computer. The installer checks the phone first, asks for your user name, password, Wi-Fi and SSH key, shows exactly what it will write, and waits for you to type "$DEVICE".