Skip to content

install-phone: append the owner's key to slot B's initramfs, as the boot hook does - #576

Merged
derekross merged 3 commits into
derekross:mainfrom
only21mil:build/install-phone-initramfs-keys
Nov 10, 2026
Merged

derekross merged 3 commits into
derekross:mainfrom
only21mil:build/install-phone-initramfs-keys

Conversation

@only21mil

@only21mil only21mil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Fixes #564. On a fresh release install the first omamobile-boot-update run rewrote vendor_kernel_boot_b with root's authorized_keys appended to the initramfs. Until then the initramfs's rescue SSH (dropbear, before switch_root) had no owner key, which matters exactly when the root doesn't mount, and the bundle didn't boot the bytes the hook writes later (RELEASES §11 step 4).

tools/install-phone now gives a copy of the ramdisk image (vendor_kernel_boot, or vendor_boot without one) what lib/omamobile-boot-images appends, using the builder's own commands, with the directory modes pacman's umask (022) gives the hook, each step stopping the install with its own message if it fails: a cpio holding the key, after the shipped archive, in one lz4 stream. A small inline Python then writes the new ramdisk size into the copy's v4 vendor boot header and ramdisk table, where mkbootimg puts it. Everything is inline because the bundle ships install-phone alone as install, without tools/lib (L-497).

  • The copy is what gets flashed. The bundle's image, the write path (slot B images and userdata only, the allowlist, the typed codename, dry run) and the hook are unchanged.
  • A ramdisk that already holds authorized_keys (a development initramfs) is flashed as built.
  • Refused before any write: an image the key makes larger than its partition, a ramdisk image under an AVB footer, and an image that isn't a single-ramdisk v4 vendor boot image.
  • install-phone now needs lz4, cpio and python3 on the laptop (INSTALL.md, the bundle's README.txt and the "not found" hint updated). CI installs lz4 explicitly.
  • --help prints its header from the file (the same line as in tools: print every tool's --help from its header with one helper #559), since the header grows here; the old range cut off --reinstall and --unsigned.

Test: tests/install-phone-initramfs runs the hook's own omamobile-boot-update build on a stand-in phone root with and without the owner's key. It installs a bundle of the keyless set with the bundle's install against a fake fastboot, and checks every flashed image is the hook's byte for byte, for a gs201 layout (vendor_kernel_boot, 2 KiB pages as on the Pixel 7 Pro) and a gs101 layout (vendor_boot, 4 KiB pages, for the header arithmetic). The hook's write --dry-run on a slot B holding them then writes nothing; on the bundle's own images it plans the vendor_kernel_boot rewrite #564 reported. It also checks each refusal, and that a failing install, cpio or lz4 step stops the install before anything is flashed; each check was mutation-tested. Every install runs under umask 077. It fails on main and needs mkbootimg (android-tools, or tools/fetch-toolchain's copy). CI has no mkbootimg yet, so it shows # skip there until android-tools is in checks.yml.

Limits:

  • The bytes match when the laptop's lz4 and GNU cpio produce what the phone's do (tested with lz4 1.10.0 and cpio 2.15). If they don't, the key is still there and the hook rewrites the image once, as it does today.
  • On a device with INITRAMFS_MODULES (raven) the hook's cpio also carries those modules, so its first run still rewrites the image (RELEASES §5.2 says so).
  • A web flasher following manifest.json would flash the bundle's image without the key.
  • GNU install -d (the phone's) makes parent directories 0755 under any umask, but uutils' (Ubuntu's default) follows the umask, so install-phone sets root/'s mode itself. The hook built with uutils at a umask other than 022 would give different bytes.

Overlap: #563 (install-phone: development boot-update policy and serial pin) edits tools/install-phone, tests/install-phone and docs/RELEASES.md too. This PR keeps its change in its own section and test file, and its hunks don't touch #563's lines. #559 changes the same --help line to the same text and adds a comment line above it, so whichever lands second needs a small resolution there. The suite list in tests/all conflicts with other open PRs that add a suite; the resolution keeps both entries.

Device and build

  • Phone: none: a laptop tool and tests (no phone run)
  • Kernel release (uname -r): n/a
  • Packages changed, with versions: none

Checks (no phone needed)

  • tools/pr-check origin/main passes
  • tests/all passes (486 ok, 0 not ok; tests/install-phone-initramfs ran here with mkbootimg installed: 8 ok, also under umask 077 and 002)
  • tests/packages: no package touched
  • Each changed package has its version bumped, and the new version is in the commit subject (no package changed)
  • Commits have area prefixes and bodies that say why; any AI help is a Co-Authored-By: or Assisted-by: trailer, never a Signed-off-by:

On the phone

  • I ran this on my own phone, booted into this build
  • Runbook steps passed (plan, step, result): none
  • What I did not test: no install on a phone. The bytes it flashes are the ones the hook already wrote and booted on the 2026.11.08 test install (device/cheetah: NOTES, the 2026.11.08 test install, and an update run as root #560). Not tested with the phone's own lz4 and cpio builds.
  • Nothing in this change writes outside slot B and userdata, weakens the storage guard, or reads registers from userspace (AGENTS.md §1)
tools/phone-smoke report

Not applicable: install-phone runs on the laptop.

Generated with Claude Opus 5.5 in T3 Code Nightly

…oot hook does

On a fresh release install the first omamobile-boot-update run rewrote
vendor_kernel_boot_b with root's authorized_keys appended to the
initramfs. Until then the rescue SSH in the initramfs had no owner key
(exactly when it is needed: a root that doesn't mount), and the bundle
did not boot the bytes the hook writes later (RELEASES §11 step 4).

install-phone now does to a copy of the ramdisk image
(vendor_kernel_boot, or vendor_boot without one) what
lib/omamobile-boot-images does: a cpio holding the key, made with the
builder's commands under pacman's umask (022), after the shipped archive
in one lz4 stream. A small inline Python then sets the new ramdisk size
in the copy's v4 vendor boot header and ramdisk table, where mkbootimg
puts it. The code is inline because a bundle ships install-phone alone
(L-497). The copy is what gets flashed; the bundle's own image and the
write path (slot B and userdata only, the allowlist, the typed codename)
are unchanged. A ramdisk that already holds SSH keys (a development
initramfs) is flashed as built. An image the key makes too large for its
partition, a ramdisk image under an AVB footer, or one that isn't a
single-ramdisk v4 vendor boot image stops the install before any write.
install-phone now needs lz4, cpio and python3 on the laptop.

tests/install-phone-initramfs runs the hook's own build (omamobile-boot-
update build on a stand-in phone root) with and without the owner's key,
installs a bundle of the keyless set with the bundle's install against a
fake fastboot, and checks that every flashed image is the hook's byte
for byte, for a gs201 and a gs101 layout; the hook's dry run on a slot B
holding them then writes nothing (on the bundle's own images it rewrites
vendor_kernel_boot, as in derekross#564). It also covers each refusal (each one
mutation-checked). It fails on main and skips without mkbootimg.
tests/install-phone's ramdisk images are now real v4 vendor boot images.
CI installs lz4 explicitly.

Fixes derekross#564

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@only21mil

only21mil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

Could you re-run the checks here? The only run on this head (42674238918) failed at 18:27 UTC with no jobs started, during GitHub's Actions incident that day (mitigated at 18:43 UTC), so none of the tests ran. A contributor on a fork can't re-run it from this side. Locally on this head tests/all passes (485 ok, 0 not ok).

@derekross

Copy link
Copy Markdown
Owner

Thank you, Victor. This is exactly the fix I hoped for in #564, and the test is
the right one: it builds the hook's image and the installer's image from the
same package and key and compares them byte for byte, then checks the hook's
next dry run writes nothing. The write path is untouched: flash() still only
accepts slot B images and userdata on the allowlist, and only the source
file of the ramdisk image changes.

I checked it against the real 2026.11.08 cheetah bundle. Your get returns
exactly the ramdisk unpack_bootimg finds (6847124 bytes, the number in
#564), mkbootimg with the hook's arguments reproduces the bundle's image, and
after appending a test key your header rewrite gives the same bytes as
mkbootimg built from the same parts. One note there: the 7 Pro's vendor
images use 2 KiB pages (VENDOR_PAGESIZE=0x800), while the test's "gs201"
fixture uses 4 KiB, so a 2 KiB fixture would match the reference phone. I also
ran tests/install-phone-initramfs and tests/install-phone here (both pass,
and the new test fails with main's installer, as it should).

Two small things before I merge:

  1. In the append block (tools/install-phone around lines 634-646), set -e
    doesn't apply inside ( … ) || die: bash turns errexit off in a subshell
    whose status is tested by ||. So if install -m 600 or cpio -o failed,
    the block would carry on, and only the last lz4 pipeline would decide.
    You can see it with bash -c 'set -euo pipefail; ( false; echo went on ) || echo caught', which prints "went on". The subshell is only there for
    umask 022, and that doesn't change the bytes here: GNU install -d -m 700 x/root/.ssh creates root as 0755 under any umask, and the test still
    passes with umask 077 in its place. Could you run those steps at the top
    level, or give each one its own || die "…"?
  2. The bundle's README.txt (tools/make-bundle around line 200) still lists
    "fastboot, e2fsprogs, zstd, openssl, gpg and python3". Please add lz4 and
    cpio there too, and maybe name their packages in the "not found" hint at
    tools/install-phone:152.

On my side: CI's run for this head ended as "failure" without starting a job,
which looks like a GitHub hiccup rather than your change, so I'll re-run it.
I'll also add android-tools to the CI package list so the byte comparison
runs there rather than skipping. And I'll think about manifest.json: it still
names the bundle's own vendor_kernel_boot.img, so a web flasher would flash
the image without the key, as you pointed out. That's for me to decide, not a
blocker for this PR.

A merge note: tests/all will conflict with #575 and #559 (keep both suites),
and #559 adds a comment line above the same --help line in
tools/install-phone, so those two don't quite merge cleanly; I'll resolve it
whichever lands second.

… lz4 and cpio

This addresses the review on derekross#576.

The append ran in ( ... ) || die only for umask 022, and bash turns
errexit off in a subshell whose status is tested, so a failing install
or cpio carried on and only the last lz4 pipeline decided: a cpio that
failed gave the shipped ramdisk recompressed without the key, flashed
with "the owner's key appended". The steps now run at the top level,
each with its own die: staging the key, cpio packing it, lz4
recompressing.

Dropping the umask alone would change the bytes on some laptops: GNU
install -d makes the parent root/ 0755 under any umask, but uutils'
install (coreutils 0.8.0 here, Ubuntu's default) gives it the umask's
mode, so under 077 or 002 vendor_kernel_boot no longer matched the
hook's. root/ is now made 0755 explicitly, the mode pacman's umask
gives the hook's.

tests/install-phone-initramfs runs every install under umask 077 and
checks that a stand-in install, cpio or lz4 that exits 1 stops it with
the step's message before anything is flashed (it fails on 8d5571e's
installer at the first injected install failure; each die removed in
turn fails it). The
gs201 fixture now uses 2 KiB pages as the Pixel 7 Pro does
(VENDOR_PAGESIZE=0x800, as every descriptor in device/), and the gs101
one 4 KiB, so both page sizes stay covered. The test passes with the
caller's umask at 022, 077 and 002, and fails under 077 and 002, and
from a 022 caller, without the explicit root/ mode.

The bundle's README.txt lists lz4 and cpio with the other tools the
install needs, and install-phone's "not found" hint names their
packages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@only21mil

only21mil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

Both points are fixed in a3b6793, plus the page-size note.

  1. The append now runs at the top level, and each step has its own die: staging the key, cpio packing it, lz4 recompressing. tests/install-phone-initramfs puts a stand-in install, cpio or lz4 on PATH that exits 1 on that call, and checks that the install stops with that step's message and flashes nothing. It fails against 8d5571e at the first injected install failure; on this head each injected install, cpio and lz4 failure stops with its matching message before any flash, and removing any corresponding die makes that case fail.

    Dropping the umask alone wasn't enough, though: GNU install -d makes root 0755 under any umask, but uutils' (coreutils 0.8.0, Ubuntu's default install) gives it the umask's mode, so on that laptop under umask 077 or 002 vendor_kernel_boot no longer matched the hook's. So root/ is now made 0755 explicitly, and the test runs every install under umask 077. It passes with the caller's umask at 022, 077 and 002, and fails without the explicit mode.

  2. README.txt now lists lz4 and cpio, and the "not found" hint names their packages.

The gs201 fixture now uses 2 KiB pages, as device/cheetah/device.conf does, and the gs101 one 4 KiB, so both page sizes stay covered. The --help line and CI are unchanged.

…id-tools

tests/all keeps every suite (main's, plus tests/install-phone-initramfs),
and tools/install-phone keeps main's comment above --help. checks.yml
adds android-tools, so the new test finds mkbootimg and runs on CI
instead of skipping.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@derekross
derekross merged commit ce7a1a3 into derekross:main Nov 10, 2026
2 checks passed
@derekross

Copy link
Copy Markdown
Owner

Thank you, Victor. Both points are fixed, and the uutils finding is a good catch I wouldn't have found on this laptop.

What I checked on a3b6793:

  • The append now stops at each step. With the previous commit's installer your new test fails at the injected install failure, and with the cpio die taken out it fails at the injected cpio failure; on your head all 8 checks pass.
  • The bytes, again on the real 2026.11.08 Pixel 7 Pro bundle: your append gives the same vendor_kernel_boot.img under umask 077, 022 and 002, and that image is byte for byte what mkbootimg packs from a ramdisk built with the hook's own lines under umask 022. I couldn't check the uutils case here (GNU coreutils 9.12), so that part rests on your run.
  • The write path is unchanged: flash() still takes only slot B images and userdata on the allowlist, and every new failure stops before the plan is shown.
  • The bundle's README.txt and the "not found" hint are as asked, and the 2 KiB fixture now matches the 7 Pro.

The branch conflicts with main now, in the two places I said I would resolve (tests/all, and the comment line #559 added above the --help awk), which is also why no checks ran on your last push. I merged main into your branch with both resolved, and on that merge tests/all gives 533 ok, 0 not ok here, with tests/install-phone-initramfs running against android-tools' mkbootimg. In the same push I added android-tools to CI's package list, as promised, so the byte comparison runs there rather than skipping. I'll merge once that run is green.

Two small things for a later PR if you feel like it, neither holding this one: a stand-in for a failing lz4 -dc (the decompress side; the test only fails the compress call today), and #563 now conflicts with main in tests/install-phone on a grep -q line that #575 converted, so it needs a rebase.

manifest.json still names the bundle's own image; that one stays on my list.

@only21mil

only21mil commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

The lz4 -dc stand-in is in #596. A failing decompress already stopped the install before anything was flashed, but blamed the recompress, and the key check's || true hid it and counted the ramdisk as holding no keys. The decompress is now its own step with its own message, the key check and the append read its output, and the image is unchanged byte for byte under umask 022, 077 and 002.

derekross pushed a commit that referenced this pull request Nov 10, 2026
)

Follow-up to #576: the shipped ramdisk is decompressed once, and a decompress that fails stops the install there, before the plan is shown and before any fastboot write. The key check and the append both read that one copy.
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…oot hook does (derekross#576)

A fresh install's initramfs rescue SSH had no owner key until the first
run of omamobile-boot-update's hook, which then rewrote vendor_kernel_boot
(derekross#564). tools/install-phone now appends the owner's authorized_keys to
the initramfs in its local copy of slot B's image, with the hook's own
steps, so the installed image is byte for byte what the hook builds from
the same package: checked on the 2026.11.08 cheetah image under umask
077, 022 and 002. Each step stops the install on failure. The write path
is unchanged: only slot B's images and userdata. The bundle's README
lists lz4 and cpio, and CI installs android-tools so
tests/install-phone-initramfs runs there.

Fixes derekross#564.
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…erekross#596)

Follow-up to derekross#576: the shipped ramdisk is decompressed once, and a decompress that fails stops the install there, before the plan is shown and before any fastboot write. The key check and the append both read that one copy.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release bundle: vendor_kernel_boot's initramfs has no owner SSH key until the first boot-update hook run

2 participants