Skip to content

initramfs: add guarded NFS root for bring-up - #503

Merged
derekross merged 5 commits into
derekross:mainfrom
quatrixone:initramfs-nfsroot
Nov 10, 2026
Merged

derekross merged 5 commits into
derekross:mainfrom
quatrixone:initramfs-nfsroot

Conversation

@quatrixone

@quatrixone quatrixone commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add an opt-in NFS-root path to the shared initramfs for testing a root filesystem over the phone USB network before installing it on userdata. Set OMAMOBILE_NFSROOT=<host>:/<export> when building the initramfs; this is a local build input, not a device descriptor value. The Dipper RAM-only builder supports the same input.

NFS mode makes every UFS disk and partition read-only on the first guard pass, including the normal boot allowlist. If the host or export is unavailable, PID 1 stays in the initramfs shell and never falls through to writable userdata. The existing no-USB watcher remains active: if USB never configures, it panics after about 65 seconds. A Dipper RAM boot then returns to the installed boot image. A hard NFS mount can freeze the root session if the host drops; use it only for a RAM-only probe. Dipper systemd takes over the watchdog with RuntimeWatchdogSec=60s after kill -9 -1 stops the initramfs feeder.

Checks

  • tests/storage-guard passed with fake UFS sysfs/dev nodes, including the first-pass NFS read-only case and no-fallback checks.
  • Shell syntax and git diff --check passed.
  • No initramfs image build or physical device test was run.

@derekross

Copy link
Copy Markdown
Owner

Thank you for splitting the NFS root out into its own PR, and for making it fail closed. If the root isn't there, it never falls back to userdata. That's the right rule. I read the change against the whole init. For the Pixel 7 Pro and every other phone it changes nothing, because nothing packs /etc/omamobile-nfsroot, so they take the same boot_arch path as before, and ufs_ro_start starts the same watcher. A few things need to change before it can go in.

1. tests/storage-guard fails on this branch.

not ok - initramfs/init has no allowlist of its own, only the packed one

The test makes sure the init has exactly two UFS_RW= assignments (the empty default and the packed list), and boot_nfs adds a third. CI hasn't run yet because it's waiting for my approval, so you couldn't have seen it. Main passes this test.

2. The lock comes too late. The description says that when NFS is requested, every partition is read-only, the allowlist included. In the code, that happens only after the mount has succeeded and systemd has been found. Until then, the packed allowlist is writable while SSH is up: through the USB wait and up to 15 mount attempts. If the mount fails, boot_nfs returns before the lock, and the phone stays in the initramfs with the allowlist writable. On the Mi 8 the allowlist is empty, so nothing is exposed there. On a Pixel with an NFS file, boot_b and userdata would be.

There's a simpler shape that fixes both points: decide the mode before the guard's first pass. Near ufs_rw_load, if /etc/omamobile-nfsroot is non-empty, log "NFS root requested: every partition read-only" and skip loading the allowlist, so UFS_RW stays empty. Then the first pass already locks everything, boot_nfs no longer needs to kill and restart the watcher or clear /run/ufs-ro, and the test's count stays at two. Keep the ufs_unguarded check before switch_root.

3. Nothing puts the file into an image. No tool in this PR or in #505 writes /etc/omamobile-nfsroot, so this path can't be built, tested or run as it stands. Please add the way in, for example an option or environment variable to bin/omamobile initramfs (and to tools/dipper/build). I'd keep it out of the descriptor, since it holds a host address. Then add a test along the lines of tests/storage-guard: with the file present, every partition is read-only from the first pass and boot_arch never runs; with the mount failing, the init stays put and nothing is writable. Then run it once on the phone, attended, with this exact init, and record it with uname -r and the image's sha256. Your 10-30 run used an earlier boot_nfs without the lock, and an initramfs that adds util-linux, so mount there was util-linux's. On the Pixels the initramfs has busybox only. I checked that Alpine's busybox has no NFS helper of its own, so it should pass the addr= option string to the kernel the same way. Still, nobody has run that yet.

Smaller things:

  • boot_nfs doesn't honour omamobile.initramfs on the command line, which is how we stay in the initramfs on purpose. It should return early like boot_arch does.
  • "It does not … reboot into the same image" isn't quite right. If the host never configures USB, the existing watcher still crashes the phone after about 65 s. On a RAM-booted Mi 8 that's what you want, since the restart goes back to the installed boot. Please say so in the description, so nobody reads it as "never reboots".
  • After the switch, kill -9 -1 also stops any watchdog feeder the initramfs started (device/dipper: add a RAM-only first-light build path #505's patched init starts one, with a 30 s timeout). Your own 10-30 notes found that systemd needs RuntimeWatchdogSec=60s on an NFS root, or the phone resets mid-boot. Worth a comment beside the kill, and a line in the dipper runbook.
  • The Pixel 4 work on main tried the same thing. device/flame/BRINGUP-M1.md records an NFSv3 root over USB losing the USB link under load, and an independent SSH server in RAM that stayed reachable. A hard NFS mount means a dropped link freezes the whole root. That's fine for a RAM-only probe, but please say it in the comment and in the runbook.
  • I'm working on initramfs, device-cheetah, device-raven, device-lynx (versions at merge): guard the boot LUNs as the main LUN (#252) #484 in the same part of the init (how the guard treats whole disks). It merges cleanly with this, but whichever lands second should rerun tests/storage-guard on the combined tree.
  • Please wrap the commit body at 72 columns. The title is fine for the squash.

@derekross

Copy link
Copy Markdown
Owner

Thank you, this is the shape I hoped for. The mode is now chosen in ufs_rw_load, before the guard's first pass, so the allowlist is never loaded when an NFS root is requested. tests/storage-guard passes again with the two UFS_RW= assignments. There's a way to build the file in (OMAMOBILE_NFSROOT, refused with --release). boot_nfs honours omamobile.initramfs, and the description now says what the 65-second watcher and a hard mount do. For the Pixels nothing changes: the file is never packed, and every new branch is keyed on it.

Two things before it can go in:

1. It now conflicts with #484. #484 changes how the guard treats whole disks: it removes every whole-disk node (ufs_is_disk) and never sets a disk's read-only flag. Your new /dev/sda branch sets that flag (blockdev --setro /dev/sda), and ufs_unguarded's sda line changes in the same place, so the two collide in initramfs/init. Once #484 lands, the simplest resolution is to drop both NFS-specific sda changes. With #484, every disk's node is removed in either mode, and with the allowlist empty every partition is set read-only on the first pass, which is all NFS mode needs. The NFS test then checks that the nodes are removed, as disk_checks does, instead of sda/ro == 1. I plan to merge #484 first, and I'll tell you here when it's in.

2. The NFS test doesn't test the lock yet. Its case packs no allowlist, so every partition is read-only whatever NFS mode does. I checked: if ufs_rw_load logs "NFS root requested" but still loads the allowlist, the test passes. One line fixes it. In the NFS case, right after writing omamobile-nfsroot, add

cp "$t/etc-cheetah/omamobile-ufs-rw" "$B/etc/omamobile-ufs-rw"

With that line the test passes on your branch and fails on the broken variant, which is the case that matters: a Pixel built with the variable set.

And one run on the phone, attended, with this exact init: uname -r, the image's sha256, every ro reading 1, the ufs-ro lines, and the mount succeeding through busybox's mount. Your 10-30 run used util-linux's mount. On the Pixels the initramfs has busybox only. It can be the same boot as #505's probe if you build that with OMAMOBILE_NFSROOT set.

Smaller things:

  • The two new comments name the Mi 8 ("Dipper's systemd takes over at 60 seconds", and "Dipper uses RuntimeWatchdogSec=60s" in boot_arch). The shared init runs on every phone, and nothing in the tree sets that value for the Mi 8 yet. Something like "systemd takes over the watchdog after the switch, if the root's RuntimeWatchdogSec is set" says the same for every phone.
  • If blockdev --setro on sda fails, the new branch logs on every 0.2 s pass. This goes away with point 1.
  • tools/stage-boot-files refuses an initramfs that carries SSH keys. Refusing one that carries etc/omamobile-nfsroot would be a cheap second guard behind --release. That's optional.

The title is fine for the squash.

@derekross

Copy link
Copy Markdown
Owner

Thank you for both changes. The comments now describe every phone, and with cheetah's allowlist packed the NFS case finally starts from a state where the lock matters. I checked it: a variant of ufs_rw_load that logs "NFS root requested" and then loads the allowlist anyway now fails the test.

One line still needs a fix. The second new assertion is

! grep -q '^allowlist: ' "$B/dev/kmsg"

but the guard writes every line through ufs_ro_log, so kmsg has omamobile: ufs-ro: allowlist: …, and ^allowlist: never matches. I tried an NFS branch that also logs an allowlist line, and the test still passed. With

! grep -q 'ufs-ro: allowlist: ' "$B/dev/kmsg"

it fails on that variant and passes on your branch.

The rest is waiting on me or on boots:

The title is fine for the squash.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Fixed the NFS allowlist log assertion: ufs_ro_log prefixes the message with omamobile: ufs-ro:, so the test now checks ufs-ro: allowlist: anywhere in kmsg. tests/storage-guard, bash -n initramfs/init, bash -n tests/storage-guard, and git diff --check pass.

@quatrixone

Copy link
Copy Markdown
Contributor Author

The remaining assertion fix is pushed at the current head. Local tests/storage-guard, tests/all, tools/pr-check origin/main, shell syntax checks and git diff --check pass. I cannot run the requested NFS boot yet: the phone responds on USB SSH but rejects the available identity (Permission denied (publickey)), and this host has no prepared NFS root/server. The branch remains conflicting with #484, as expected; I will rebase after #484 lands.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Attended NFS-root run update: I booted the RAM image with OMAMOBILE_NFSROOT set to the existing phone-only USB export. The initramfs switched to the exported root; SSH then confirmed PID 1 was systemd, / was nfs, systemctl is-system-running returned running, and the manager reported RuntimeWatchdogUSec=20s. No UFS write was performed. I did not capture the requested full UFS ro/ufs-ro evidence before the USB SSH path was lost. I did not bypass host-key checking when the live key no longer matched the pinned NFS-root key. This device run is therefore partial and needs a repeat after access is restored; the branch still conflicts with #484.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Clarification: the exported root used for that run was a generic Arch Linux ARM base with SSH, not a built Omarchy rootfs. The run verifies the initramfs NFS mount and systemd handover only; it does not verify the Omarchy desktop or release rootfs.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Follow-up from the persistent journal in the temporary NFS root: it records NFS mode selection and read-only confirmations for 85 unique UFS partitions plus all 6 UFS whole disks. The guard’s set read-only messages confirm the checks passed. The live SSH observation had already confirmed / was NFS and PID 1 was running systemd. Exact live sysfs ro output was not captured, and the test image predates #484, so the all-whole-disk-node absence check still needs a post-#484 boot.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Image details for the partial run: kernel release 7.3.0-rc6-omamobile-push1; RAM boot.img SHA-256 2244d74aea472b0c595b2056ad8618f614e6a9161b5b264c7f898939e626f318. It reused the kernel/DTB from the earlier #505 RAM artifact and only repacked its initramfs with OMAMOBILE_NFSROOT; it was not rebuilt against the latest #220 head. The guard logs its read-only success only after reading each sysfs ro value back as 1: 85 unique UFS partitions and all six UFS disks were confirmed. Exact direct sysfs output and the post-#484 absent-whole-disk check still need a new run.

@quatrixone

Copy link
Copy Markdown
Contributor Author

Correction on the preceding note: 7.3.0-rc6-omamobile-push1 is the kernel release embedded in the reused image; I did not capture uname -r from the phone during this NFS run before access was lost.

@quatrixone

Copy link
Copy Markdown
Contributor Author

The NFS-root persistent journal also records Linux version 7.3.0-rc6-omamobile-push1, confirming the booted kernel release. The requested interactive uname -r output itself remains uncaptured.

@derekross

Copy link
Copy Markdown
Owner

Thank you for the fix, and for the run. With 'ufs-ro: allowlist: ' the assertion now bites: I tried an NFS branch that also logs an allowlist line, and the test fails on it, where the old line passed. And NFS mode has now run on the phone: busybox's mount took the export, systemd came up as PID 1 on nfs, and the root's journal has the guard's read-only lines for all 85 partitions and six disks. I also appreciate that you corrected your own reports as you went, and that you didn't bypass the host-key check when the key changed.

Three things are left, the first one caused by my side:

1. A rebase onto main, and you don't need to wait for #484 any more. I merged #530 on 2026-11-09 (19:27 UTC), which lets a descriptor name a second LUN with allowlisted partitions. It rewrote the two lines your PR edits, so this PR now conflicts with main itself and CI can't run. I've resolved it here and run the tests on the result. Keep main's ufs_rw_disk test in both places and put your NFS branch inside it, with $name where you had sda:

    if ufs_rw_disk "$name"; then
      if [ -s /etc/omamobile-nfsroot ]; then
        blockdev --setro "/dev/$name"
        read -r ro < "$s/ro"
        if [ "$ro" = 1 ]; then
          : > "/run/ufs-ro/$name"
          ufs_ro_log "/dev/$name set read-only for NFS root"
          continue
        fi
        ufs_ro_log "FAILED to set /dev/$name read-only for NFS root"
        echo "omamobile: WARNING: /dev/$name is NOT read-only" > /dev/tty0 2>/dev/null
        continue
      fi
      rm -f "/dev/$name"

and in ufs_unguarded:

    ufs_rw_disk "$name" && [ ! -s /etc/omamobile-nfsroot ] && continue

In NFS mode ufs_rw_load returns before it reads the LUN list, so only sda reaches your branch and every other LUN is still set read-only at the disk level. With that, tests/storage-guard passes with both #530's new cases and your two NFS cases, and each of your three NFS assertions fails when I break the code it guards. #484 is mine to redo on top of this afterwards.

2. One repeat of the NFS boot on the rebased head, with the capture that got away this time: uname -r, the image's sha256, dmesg | grep ufs-ro, and cat /sys/block/sd*/ro /sys/block/sd*/sd*/ro, before anything else in the session. Expect /dev/sda present with ro 1 in this mode, the other five disks ro 1, and all 85 partitions ro 1. If the root's host key will differ from the initramfs's again, add it to known_hosts beforehand from the export itself, so the session survives the hand-over.

3. My Pixel 7 Pro. One routine boot with the rebased init before I merge, to read the guard's lines there.

The title is fine for the squash.

Let any device test an Arch root over its USB network link before using userdata. When an NFS root is requested, make every UFS partition read-only, including the usual allowlist, and stay in the initramfs shell if the host or root is unavailable.
@quatrixone

Copy link
Copy Markdown
Contributor Author

Rebased this branch onto current main and resolved the #530 overlap using the ufs_rw_disk shape you supplied. NFS mode keeps the allowlist empty before the first guard pass; the NFS case carries cheetah’s non-empty allowlist and checks the prefixed guard log. The NFS handover now calls BusyBox mount explicitly. tests/all, tests/storage-guard, shell syntax checks and git diff --check pass (the last three were rerun after the BusyBox change).

I repeated the attended Mi 8 NFS-root boot with the rebased #503 init and #505 Dipper builder. Image SHA-256: a2d435a7430e7e4c145c61cdb9866d16929731859d91c7105e6bfcaf9e3e9dd7; uname -r was 7.3.0-rc6-omamobile-push1; / was NFS. Direct sysfs reads showed all six UFS disks and all 85 partitions at ro=1; the guard’s ufs-ro messages were captured. BusyBox mount succeeded, systemd reached the multi-user target with RuntimeWatchdogUSec=1min, and SSH remained available. reboot-to bootloader returned the phone to fastboot. No UFS write was attempted. The export was a generic Arch test root, not an Omarchy desktop root, and link-loss recovery was not tested.

The requested routine boot on your Pixel 7 Pro remains for you to run; I do not have that device attached. This PR is now clean and mergeable.

@derekross

Copy link
Copy Markdown
Owner

Thank you. All three points are in. The rebase matches the resolution I posted, line for line, and it merges cleanly onto today's main. The repeat run has what the first one missed: uname -r, the image's sha256, all six disks and all 85 partitions at ro 1 read from sysfs, and the hand-over through busybox's mount. Calling busybox mount by name is a good catch too: your Mi 8 image installs util-linux, so this way your run used the same mount a Pixel's busybox-only initramfs would.

I ran tests/storage-guard on your head and on main with #503 and #505 together, and broke the code five ways to see what the tests notice. Three are caught. Two are not, and two lines close them, if you'd like to add them after the unguarded line of the NFS case:

echo 0 > "$B/sys/block/sda/ro"
[[ $(unguarded) == sda ]] || fail "NFS root's hand-over check reports a writable main disk (got: $(unguarded))"
awk '/^boot_nfs\(\) \{/ {on = 1} on && /ufs_unguarded/ {u = NR} on && /kill -9 -1/ {k = NR} on && /^}/ {exit} END {exit !(u && k && u < k)}' initramfs/init \
  || fail "boot_nfs checks ufs_unguarded before it stops the initramfs's processes"

The first fails if ufs_unguarded goes back to skipping sda in NFS mode, the second if boot_nfs loses its check before the kill.

One more suggestion, also not a condition: images and push use whatever initramfs is in KERNEL_OUT, so an initramfs built with OMAMOBILE_NFSROOT set and pushed later by mistake would leave a Pixel in the initramfs shell with everything read-only. A line from bin/omamobile initramfs when the variable is set ("NFS root : this initramfs never boots userdata") would make that hard to miss.

What's left is mine: one routine boot of this init on my Pixel 7 Pro, to read the guard's lines there. I'll merge after it, then #505, and redo #484 on top. The repeated log line when blockdev --setro /dev/sda fails came from the snippet I gave you, so I'll tidy that myself later.

The title is fine for the squash; I'll put your 11-10 run into the message.

@derekross

Copy link
Copy Markdown
Owner

The 7 Pro boot is done: this head merged with today's main, OMAMOBILE_NFSROOT unset, pushed to my Pixel 7 Pro on 2026-11-10 (7.3.0-rc6-omamobile-push1-gc7fb37460f84).

  • The initramfs holds no /etc/omamobile-nfsroot.
  • The storage guard's 61 ufs-ro: lines are the same as on the boot before it, line for line (the watcher's pid aside): the allowlist line, the six partitions left writable, /dev/sda: whole-disk node removed, guard running.
  • No NFS-root line from the init. /dev/sda is gone, persist reads ro 1, the root is userdata on ext4.
  • The system reached running with no failed units, and the modem came ONLINE.

So nothing changes for a phone that doesn't ask for it. Merging. The two test lines from my last comment (the sda exemption in NFS mode, and boot_nfs's check before kill -9 -1) are still worth having; a small follow-up is fine.

@derekross
derekross merged commit dd5c93e into derekross:main Nov 10, 2026
2 checks passed
derekross pushed a commit that referenced this pull request Nov 12, 2026
…nd hand-over order are tested, and the notes say which boots removed /dev/sda (#675)

Two assertions for the NFS-only lines #503 left untested: in NFS mode `ufs_unguarded` reports a writable `sda`, and `boot_nfs` calls it before `kill -9 -1`. Dipper's notes now tie the whole-disk-node removal to the `93484a91…` and `f2f5cb2e…` boots the table records, apart from the `e2cdb765…` image where the node was present. `initramfs/init` is unchanged.
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
A bring-up option for phones whose storage can't be written yet: with OMAMOBILE_NFSROOT set when the initramfs is built, the init mounts its root over NFS through the USB network instead of from userdata. In that mode the storage guard is stricter, not looser: the allowlist is empty, every partition is read-only and the whole-disk node stays read-only at disk level.

Nothing changes for a phone that doesn't ask for it: every new branch is keyed on a file that only an initramfs built with the variable carries. The one shared change is that the guard's watcher now starts inside ufs_ro_start(), with the same loop and log line.

Tested by the contributor on a Xiaomi Mi 8 over NFS (six disks, every partition read-only). Tested on a Pixel 7 Pro on 2026-11-10 with the variable unset (7.3.0-rc6-omamobile-push1-gc7fb37460f84): the guard's 61 lines identical to the boot before, no NFS line, the root on userdata, the modem ONLINE.
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…nd hand-over order are tested, and the notes say which boots removed /dev/sda (derekross#675)

Two assertions for the NFS-only lines derekross#503 left untested: in NFS mode `ufs_unguarded` reports a writable `sda`, and `boot_nfs` calls it before `kill -9 -1`. Dipper's notes now tie the whole-disk-node removal to the `93484a91…` and `f2f5cb2e…` boots the table records, apart from the `e2cdb765…` image where the node was present. `initramfs/init` is unchanged.
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