Skip to content

stage-boot-files: refuse an initramfs with a development boot policy - #831

Merged
derekross merged 1 commit into
derekross:mainfrom
only21mil:build/stage-boot-files-release-policy
Nov 16, 2026
Merged

derekross merged 1 commit into
derekross:mainfrom
only21mil:build/stage-boot-files-release-policy

Conversation

@only21mil

Copy link
Copy Markdown
Contributor

What and why

On main 6c11752, tools/stage-boot-files stages an initramfs that bin/omamobile initramfs --release refuses to build: one with an NFS root (OMAMOBILE_NFSROOT), a root mode (INITRAMFS_ROOT_MODE) or USB recovery off (INITRAMFS_USB_RECOVERY=no). A development initramfs staged in place of a --release one goes into the device package.

I followed the NFS suggestion on #503: "a cheap second guard behind --release". #562 later added the root mode and USB recovery keys, each with its own --release refusal beside the NFS one, so this PR covers all three.

The tool now takes only what --release packs, by listed member name (etc/x or ./etc/x): no etc/omamobile-nfsroot or etc/omamobile-root-mode, and at most one etc/omamobile-usb-recovery, saying exactly yes. Anything else is refused before DEST or DEST.new changes, saying to build it with --release. What --release builds still stages, INITRAMFS_ROOT_LABEL and INITRAMFS_USB_RECOVERY=yes included. An empty etc/omamobile-nfsroot (the init ignores it) is refused: --release never packs it.

AI agents made every run below. Reproduction, both runs in the block: the real tool for cheetah, real dtc and AOSP's pinned mkdtboimg.py, on archives packed from this tree's init and the files bin/omamobile initramfs-config writes, in place of a full build (Alpine's minirootfs, which the tool never reads). Main 6c11752 stages four development archives; bf8745b refuses them.

Regression test (a stand-in, not the reproduction): new tests/stage-boot-files cases on archives with cheetah's allowlist and this tree's init. Each policy is refused with its message, DEST kept, also as an empty, symlinked or directory NFS file and a symlinked, repeated or unreadable USB one; release archives stage; both spellings. They fail on main's tool, as does dropping or weakening any one check.

Device and build

  • Phone: none: a laptop tool only
  • Kernel release (uname -r): no phone
  • Packages changed, with versions: none

Checks (no phone needed)

  • tools/pr-check origin/main passes (AI agent)
  • tests/all passes (AI agent)
  • tests/packages passes (or the packages I touched: none, so not run)
  • 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: no: a laptop tool
  • Runbook steps passed (plan, step, result): none, no plan step
  • What I did not test: a full bin/omamobile initramfs build; a device package built from the staged files; anything on a phone
  • 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: a laptop tool that never runs on a phone (CONTRIBUTING.md §6.5).

AI agents made every run in this description, on an x86_64 desktop running Ubuntu 26.04. The tests and checks ran on bf8745b: tools/pr-check origin/main, tests/all, and tests/stage-boot-files and tests/boot-update-parity also with AOSP's pinned scripts in SRC_DIR. Each transcript below names its own commit.

Setup: Ubuntu 26.04 on x86_64, GNU cpio 2.15, lz4 1.10.0, dtc 1.7.2, AOSP's mkdtboimg.py as tools/toolchain.lock pins it; a fresh git archive of each commit at /mnt/repo in a bwrap sandbox with no network, with fresh archives and DEST under /mnt/run.

The driver strips only the colour codes of bin/omamobile's error: lines; nothing else is edited.

Steps: build six archives (this tree's init, bin/omamobile initramfs-config for a made-up sample device with cheetah's descriptor and the case's keys, initramfs_pack) → bin/omamobile initramfs --release for each development case → tools/stage-boot-files for cheetah on each archive in turn, into one DEST → cmp DEST's initramfs with the archive, ls -d DEST.new

Before, on main 6c11752a:

revision: 6c11752a
tools: cpio (GNU cpio) 2.15; lz4 1.10.0; dtc DTC 1.7.2; mkdtboimg.py from tools/toolchain.lock

# the archives: name and content of each policy file in out/<case>/initramfs.cpio.lz4 (read with lz4 -dc | cpio -i --to-stdout)
release-plain: 
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
release-keys: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_USB_RECOVERY=yes
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
  etc/omamobile-usb-recovery: yes
nfsroot: OMAMOBILE_NFSROOT=192.0.2.1:/srv/nfs/sample
  etc/omamobile-nfsroot: 192.0.2.1:/srv/nfs/sample
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
root-mode-persistent: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=persistent-development
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-root-mode: persistent-development
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
root-mode-ram-rescue: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=ram-rescue
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-root-mode: ram-rescue
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
usb-recovery-no: INITRAMFS_USB_RECOVERY=no
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
  etc/omamobile-usb-recovery: no

# what bin/omamobile initramfs --release says of each development case (scratch copy, DEVICE=sample)
$ OMAMOBILE_NFSROOT=192.0.2.1:/srv/nfs/sample bin/omamobile initramfs --release
error: OMAMOBILE_NFSROOT is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=persistent-development
error: INITRAMFS_ROOT_MODE is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=ram-rescue
error: INITRAMFS_ROOT_MODE is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_USB_RECOVERY=no
error: INITRAMFS_USB_RECOVERY=no is for local bring-up only, not --release
exit 1
$ ls -d /mnt/run/work /mnt/run/rel
ls: cannot access '/mnt/run/work': No such file or directory
ls: cannot access '/mnt/run/rel': No such file or directory

# staging each archive for cheetah, in turn, into one DEST; stdout (the list of staged files) goes to a log, stderr shows here
$ cd /mnt/repo; export DEVICE=cheetah DTC=/usr/bin/dtc MKDTBOIMG="python3 -I /mnt/aosp/system/libufdt/utils/src/mkdtboimg.py"
$ KERNEL_OUT=/mnt/run/out/release-plain tools/stage-boot-files /mnt/run/boot-files > /mnt/run/release-plain.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/release-plain/initramfs.cpio.lz4 && echo DEST holds release-plain; ls -d /mnt/run/boot-files.new
DEST holds release-plain
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/release-keys tools/stage-boot-files /mnt/run/boot-files > /mnt/run/release-keys.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/release-keys/initramfs.cpio.lz4 && echo DEST holds release-keys; ls -d /mnt/run/boot-files.new
DEST holds release-keys
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/nfsroot tools/stage-boot-files /mnt/run/boot-files > /mnt/run/nfsroot.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/nfsroot/initramfs.cpio.lz4 && echo DEST holds nfsroot; ls -d /mnt/run/boot-files.new
DEST holds nfsroot
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/root-mode-persistent tools/stage-boot-files /mnt/run/boot-files > /mnt/run/root-mode-persistent.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/root-mode-persistent/initramfs.cpio.lz4 && echo DEST holds root-mode-persistent; ls -d /mnt/run/boot-files.new
DEST holds root-mode-persistent
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/root-mode-ram-rescue tools/stage-boot-files /mnt/run/boot-files > /mnt/run/root-mode-ram-rescue.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/root-mode-ram-rescue/initramfs.cpio.lz4 && echo DEST holds root-mode-ram-rescue; ls -d /mnt/run/boot-files.new
DEST holds root-mode-ram-rescue
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/usb-recovery-no tools/stage-boot-files /mnt/run/boot-files > /mnt/run/usb-recovery-no.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/usb-recovery-no/initramfs.cpio.lz4 && echo DEST holds usb-recovery-no; ls -d /mnt/run/boot-files.new
DEST holds usb-recovery-no
ls: cannot access '/mnt/run/boot-files.new': No such file or directory

After, on bf8745bb:

revision: bf8745bb
tools: cpio (GNU cpio) 2.15; lz4 1.10.0; dtc DTC 1.7.2; mkdtboimg.py from tools/toolchain.lock

# the archives: name and content of each policy file in out/<case>/initramfs.cpio.lz4 (read with lz4 -dc | cpio -i --to-stdout)
release-plain: 
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
release-keys: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_USB_RECOVERY=yes
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
  etc/omamobile-usb-recovery: yes
nfsroot: OMAMOBILE_NFSROOT=192.0.2.1:/srv/nfs/sample
  etc/omamobile-nfsroot: 192.0.2.1:/srv/nfs/sample
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
root-mode-persistent: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=persistent-development
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-root-mode: persistent-development
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
root-mode-ram-rescue: INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=ram-rescue
  etc/omamobile-root-label: omamobile-root
  etc/omamobile-root-mode: ram-rescue
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
usb-recovery-no: INITRAMFS_USB_RECOVERY=no
  etc/omamobile-ufs-rw: boot_b init_boot_b vendor_boot_b vendor_kernel_boot_b dtbo_b userdata
  etc/omamobile-usb-recovery: no

# what bin/omamobile initramfs --release says of each development case (scratch copy, DEVICE=sample)
$ OMAMOBILE_NFSROOT=192.0.2.1:/srv/nfs/sample bin/omamobile initramfs --release
error: OMAMOBILE_NFSROOT is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=persistent-development
error: INITRAMFS_ROOT_MODE is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_ROOT_LABEL=omamobile-root INITRAMFS_ROOT_MODE=ram-rescue
error: INITRAMFS_ROOT_MODE is for local bring-up only, not --release
exit 1
$ bin/omamobile initramfs --release   # INITRAMFS_USB_RECOVERY=no
error: INITRAMFS_USB_RECOVERY=no is for local bring-up only, not --release
exit 1
$ ls -d /mnt/run/work /mnt/run/rel
ls: cannot access '/mnt/run/work': No such file or directory
ls: cannot access '/mnt/run/rel': No such file or directory

# staging each archive for cheetah, in turn, into one DEST; stdout (the list of staged files) goes to a log, stderr shows here
$ cd /mnt/repo; export DEVICE=cheetah DTC=/usr/bin/dtc MKDTBOIMG="python3 -I /mnt/aosp/system/libufdt/utils/src/mkdtboimg.py"
$ KERNEL_OUT=/mnt/run/out/release-plain tools/stage-boot-files /mnt/run/boot-files > /mnt/run/release-plain.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/release-plain/initramfs.cpio.lz4 && echo DEST holds release-plain; ls -d /mnt/run/boot-files.new
DEST holds release-plain
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/release-keys tools/stage-boot-files /mnt/run/boot-files > /mnt/run/release-keys.log
exit 0
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/release-keys/initramfs.cpio.lz4 && echo DEST holds release-keys; ls -d /mnt/run/boot-files.new
DEST holds release-keys
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/nfsroot tools/stage-boot-files /mnt/run/boot-files > /mnt/run/nfsroot.log
stage-boot-files: /mnt/run/out/nfsroot/initramfs.cpio.lz4 carries etc/omamobile-nfsroot (OMAMOBILE_NFSROOT, bring-up only): build it with --release
exit 1
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/nfsroot/initramfs.cpio.lz4 && echo DEST holds nfsroot; ls -d /mnt/run/boot-files.new
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/root-mode-persistent tools/stage-boot-files /mnt/run/boot-files > /mnt/run/root-mode-persistent.log
stage-boot-files: /mnt/run/out/root-mode-persistent/initramfs.cpio.lz4 carries a root mode (INITRAMFS_ROOT_MODE, bring-up only): build it with --release
exit 1
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/root-mode-persistent/initramfs.cpio.lz4 && echo DEST holds root-mode-persistent; ls -d /mnt/run/boot-files.new
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/root-mode-ram-rescue tools/stage-boot-files /mnt/run/boot-files > /mnt/run/root-mode-ram-rescue.log
stage-boot-files: /mnt/run/out/root-mode-ram-rescue/initramfs.cpio.lz4 carries a root mode (INITRAMFS_ROOT_MODE, bring-up only): build it with --release
exit 1
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/root-mode-ram-rescue/initramfs.cpio.lz4 && echo DEST holds root-mode-ram-rescue; ls -d /mnt/run/boot-files.new
ls: cannot access '/mnt/run/boot-files.new': No such file or directory
$ KERNEL_OUT=/mnt/run/out/usb-recovery-no tools/stage-boot-files /mnt/run/boot-files > /mnt/run/usb-recovery-no.log
stage-boot-files: /mnt/run/out/usb-recovery-no/initramfs.cpio.lz4 carries an etc/omamobile-usb-recovery that is not one file saying yes (INITRAMFS_USB_RECOVERY, bring-up only): build it with --release
exit 1
$ cmp -s /mnt/run/boot-files/initramfs.cpio.lz4 /mnt/run/out/usb-recovery-no/initramfs.cpio.lz4 && echo DEST holds usb-recovery-no; ls -d /mnt/run/boot-files.new
ls: cannot access '/mnt/run/boot-files.new': No such file or directory

Links: the regression test, tests/stage-boot-files at bf8745b; the suggestion on #503. The driver that builds the archives and runs the tools is not published; the reproduction paragraph above says what it does.

Not shown:

  • A full bin/omamobile initramfs build (Alpine's minirootfs and packages); the archives above stand in for it.
  • A device package built from the staged files, and anything on a phone.
  • Member names are matched as the listing gives them, as the tool's SSH-key check matches them; another spelling of the same path (etc//x) or an etc packed as a symlink is not normalised, on main or here.
  • tests/all in CI's Arch Linux image, where bsdcpio gives the ./etc/x cases (CI runs it).

Generated with Claude Opus 5.5 in T3 Code Nightly

tools/stage-boot-files copies KERNEL_OUT's initramfs into the device
package's boot files, which omamobile-boot-update builds slot B's
images from. It refused an initramfs with the builder's SSH keys,
dropbear host keys, another device's allowlist or another tree's init,
but not one with the development boot policies that
`bin/omamobile initramfs --release` refuses to build: OMAMOBILE_NFSROOT,
INITRAMFS_ROOT_MODE and INITRAMFS_USB_RECOVERY=no. Staging a
development initramfs that was already built, instead of building one
with --release, put it in the device package.

At the three policy paths it now takes only what --release packs,
matching member names as the archive's listing gives them (etc/x or
./etc/x), as its SSH-key check does: no member named
etc/omamobile-nfsroot or etc/omamobile-root-mode, whatever its type,
and at most one etc/omamobile-usb-recovery, which must read exactly
yes; a read that fails stops the tool. Anything else is refused before
DEST or DEST.new is touched, saying to build it with --release, so a
symlink, a directory or a repeated member under these names is refused
too, without unpacking the archive. It does not model what the kernel
unpacks: another spelling of the same path (etc//x, etc/./x) or an etc
packed as a symlink to another directory is not caught, as the SSH-key
check does not catch root//.ssh/authorized_keys. bin/omamobile
initramfs writes each policy file once, as a regular file at
etc/<name>, which is what this catches. One file the init ignores is
refused as well: an empty etc/omamobile-nfsroot. --release never packs
that file (the builder removes it in every build without
OMAMOBILE_NFSROOT), so nothing --release builds is refused;
INITRAMFS_ROOT_LABEL and INITRAMFS_USB_RECOVERY=yes still stage. The
maintainer suggested the NFS root guard on derekross#503; the root mode and USB
recovery keys came after it (derekross#562), each with its own --release
refusal beside the NFS one.

Tested: new tests/stage-boot-files cases (cheetah's allowlist and this
tree's init in every archive, GNU cpio's and bsdcpio's spellings, an
earlier DEST kept; besides each policy as the builder writes it, the
NFS file empty, as a symlink and as a directory, and the USB recovery
file as a symlink to no, packed twice, saying yes and then appended as
a symlink to no (GNU cpio only), and read through a stand-in cpio that
prints yes and fails) fail on main's tool and pass here; dropping or
weakening each check fails them. The real tool on main 6c11752 staged
four development archives built from this tree's init, the files
`bin/omamobile initramfs-config` writes and initramfs_pack, with the
real dtc and AOSP's pinned mkdtboimg.py; with this change it refuses
them and keeps the earlier staging. tools/pr-check origin/main,
tests/all and tests/boot-update-parity with AOSP's scripts pass. Not
tested: a full `bin/omamobile initramfs` build (it needs Alpine's
minirootfs), and anything on a phone.

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

Copy link
Copy Markdown
Owner

Thank you, Victor, this is a careful one. I checked the three paths against what bin/omamobile initramfs --release refuses and what initramfs_config writes. A release build packs no nfsroot file (it's removed in every build), no root mode, and at most one usb-recovery saying yes, which is exactly what you let through. No descriptor sets any of the three keys today, so nothing that stages now is refused.

I also liked that usb-recovery has to read exactly yes, not just "not no". I tried the init's own test (!= no) in place of yours, and your "symlink to no" case caught it. cpio --to-stdout prints nothing for a symlink member, while the init's cat would follow it to no. Your test runs clean here with GNU cpio and bsdcpio. It fails against main's tool, and each check I dropped or weakened failed the case that names it.

The tool isn't one of the boot files' tracked sources, so this needs no restage and no device-package version. It only adds refusals before anything is written, so release phones get the same images.

One optional thing: docs/RELEASES.md §5.3 lists what stage-boot-files refuses (SSH keys, host keys, another device's allowlist), and could name the development boot policies too. That can go in a later docs pass. I'll merge this as it is.

@derekross
derekross merged commit 64d064c into derekross:main Nov 16, 2026
2 checks passed
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.

2 participants