Skip to content

Check Mac snapshot restores against the boot files outside the snapshot - #560

Merged
maralcbr merged 12 commits into
quattro-upstreamfrom
mac/36-snapshot-restore
Sep 25, 2026
Merged

maralcbr merged 12 commits into
quattro-upstreamfrom
mac/36-snapshot-restore

Conversation

@maralcbr

@maralcbr maralcbr commented Sep 25, 2026 •

Copy link
Copy Markdown
Member

Ticket 36 of the Apple Silicon convergence plan: snapshot boot and restore with boot-coherence checks.

Uses #543's omarchy-apple-silicon-boot-check --boot-chain, which is now on quattro-upstream. Current quattro-upstream is merged in.

What changed

Limine Macs keep the x86 path: limine-snapper-sync writes the snapshot entries, you boot a snapshot from the Limine menu, and omarchy-snapshot restore runs limine-snapper-restore. omarchy-mac-boot adds omarchy-mac-snapshot-check, linked into limine-snapper-sync's hooks. It only acts on a restore on a Mac:

  • Pre hook (pre.d/04-omarchy-mac-snapshot-check). Exit 100 stops the restore before anything changes. It refuses:
    • A restore from the running system. It says to boot the snapshot first, and that snapshots taken before Limine was activated aren't in the menu, since Limine saved no kernel for them.
    • A booted snapshot that fails --boot-chain against the live /boot and system ESP, with no reboot pending (the kernel Limine saved with the snapshot is the one the restore puts back). The message gives the reason, why boot files aren't in snapshots, and the snapshot's kernel, m1n1, U-Boot and Limine package versions to install first if you want that snapshot anyway.
    • A booted root from before the Limine activation.
    • --restore-kernels <id> for a snapshot that doesn't carry the kernel on /boot. The snapshot is read off a read-only top-level mount in a snapshot boot.
    • On a GRUB Mac, it says to use omarchy-snapshot restore. It sorts before the activation gate so that message shows.
  • Post hook (post.d/99-omarchy-mac-snapshot-check). limine-snapper-restore's own list can put back a snapshot other than the booted one. After a finished restore, the restored @ must carry the Limine activation, tooling and ESP, and hold the booted root's kernel, device trees, m1n1, U-Boot, Limine, crypttab and root mount. The UKI the restore put on the ESP must carry that kernel.
    • If not, it exits 100, so the reboot isn't offered. It says to ignore the "Please reboot manually" line that follows, and to restore again and pick the backup the restore just made. The backup is named by when it was written.
    • The ESP then holds the refused root's boot files, so the booted root fails its own check. While it does, the pre hook lets that one undo through (a marker in /run), naming the backup only if it still exists. The post hook checks the undo's result and clears the marker on a match.
    • A root it cannot read, or a platform it cannot tell, is reported as not checked: exit 100 with no undo armed.
    • It trusts a restore lock only when root owns it.
    • It runs after Limine's own post hooks.
  • GRUB-era restore only on GRUB machines. GRUB Macs have limine-snapper-restore installed (omarchy-mac-boot depends on it) and were sent there. omarchy-snapshot now routes a Mac that doesn't boot Limine to the subvolume swap. A snapshot boot counts as Limine. The swap refuses a Limine Mac and a Mac's snapshot boot, and on a GRUB Mac it refuses a snapshot without the kernel on /boot. x86 routing and --rehearse are unchanged. mx-mac's omarchy-mac-snapshot-* tools already refuse or no-op on Limine Macs and aren't ported.
  • Docs. Mac manual snapshots page, boot package README, and a Snapshots section in docs/lifecycle-dispatch.md. Restore isn't a dispatch operation, so the boot-rebuild row no longer names this ticket.

Limits:

  • The hooks run from the booted snapshot's own omarchy-mac-boot, so snapshots taken before this package restore unchecked. The manual says so, and tickets 43/45 decide whether conversion prunes them.
  • A restore across a kernel, firmware or Limine update is refused, not coordinated.

Testing

  • packages/omarchy-mac/boot/test/snapshot-check-test.sh runs both hooks on Post-update boot verification blocks update completion and the reboot #543's fixture Limine Mac with the real boot check, and checks the fixture is unchanged and nothing is left mounted. It covers:

    • staging and link order
    • pass-through for non-restores, non-Macs and roots without the platform detector
    • refusal on a detector error or no clear answer (status 127)
    • pre hook: allowed for a matching snapshot; refused for a kernel, m1n1 or Limine update since the snapshot, a saved kernel that isn't the installed one, a pre-Limine root, and a restore from the running system on Limine and on GRUB
    • --restore-kernels, including the top-level read
    • post hook: a matching restored root (including the snapshot overlay's commented fstab row), no finished restore, and a restored root with another kernel, m1n1, device trees, Limine, crypttab or root mount, a UKI with another kernel, or from before the Limine activation or on another ESP
    • post hook: the undo let through only while the booted root fails, the backup named by time or not at all when gone, the real mount and unmount of the top level through stubs, and unchecked outcomes arming no undo
    • tree mode
  • test/shell.d/snapshot-restore-mac-test.sh runs omarchy-snapshot restore on platform fixtures. A limine-snapper-restore stand-in runs pre hooks, the restore (the booted snapshot or one picked from the list) and post hooks. It covers:

    • x86 unchanged, with no Mac command run
    • a GRUB Mac uses the swap
    • a pre-Limine snapshot boot gets Limine's explanation
    • matching and mismatched booted snapshots
    • a mismatched snapshot picked from the list gets no reboot offer; its ESP UKI is swapped as limine-snapper-sync does, and the undo then goes through the hooks and is offered the reboot
    • the swap's refusals of a Limine Mac and a Mac's snapshot boot, and its kernel check
  • 51 seeded regressions were all caught over five rounds. They cover the hooks, routing, the list path, the undo and its gating, the UKI, Limine-activation, crypttab and fstab checks, the package list, the top-level mount, detector errors, backup naming and link order.

  • Shellcheck: nothing new in the scripts beyond an SC2001 note on a multi-line indent.

  • Arch Linux ARM container, non-root: packages/omarchy-mac/boot/test/all passes. Runtime ./test/all: 7 of 334 files fail, all of them on plain quattro-upstream in the same container too (no omarchy-pkgs checkout, host detection).

  • Converged M2, read-only, before its current reinstall. The hooks were copied to /tmp; the btrfs top level and ESP were mounted read-only and then removed. Results:

    • non-restore passes
    • a restore from the running system is refused
    • a simulated snapshot boot passes --boot-chain
    • the post hook passes with the live root as the restored one
    • --restore-kernels 1 passes
    • nothing is left mounted

    That run found the installed Omarchy lacks omarchy-hw-platform, so the hook falls back to omarchy-hw-apple-silicon there.

  • Not done: VM acceptance of booting and restoring a snapshot. That needs tickets 23 and 28. Steps:

    1. On a converged image, run omarchy-snapshot create and check limine-snapper-list shows it.
    2. Boot the snapshot from Snapshots, run omarchy-snapshot restore, and expect "matches". After the reboot, the root is restored and omarchy-apple-silicon-boot-check --boot-chain passes.
    3. Install another linux-aurora build and reboot. Boot the earlier snapshot and restore. Expect a refusal naming /boot/vmlinuz-linux-aurora, with the root unchanged.
    4. From a snapshot boot, press l in the restore and pick a snapshot from before that update. Expect "Do not reboot yet" and no reboot offer.

Second review: clean after five rounds. Fixed along the way:

  • the restore's own list putting back an unchecked snapshot
  • Limine missing from the advice
  • the undo blocked by the pre hook
  • crypttab, fstab, the Limine activation and its tooling not compared after the restore
  • "could not check" outcomes arming the unchecked undo
  • detector statuses waved through
  • a /tmp lock trusted from any user
  • the swap's handling of snapshot boots
  • doc overstatements

…atch

The kernel and initramfs on /boot, and m1n1, the device trees and U-Boot on
the ESP, stay outside every snapshot. omarchy-mac-snapshot-check runs as
limine-snapper-sync's pre hook: a Limine Mac restores only the snapshot it
booted, and only when that root passes the boot check. Given a snapshot root,
it checks the root carries the kernel on /boot, for the GRUB-era swap.
omarchy-mac-boot depends on limine-snapper-sync, so a Mac that still boots
GRUB has limine-snapper-restore installed and was sent to it. Route Macs by
the boot loader instead; x86 keeps its routing. The swap now refuses a Limine
Mac, and on a GRUB Mac refuses a snapshot without the kernel on /boot.
The staging check followed each staged /etc path to its target, so the pre
hook linked to /usr/bin read as unshipped wherever omarchy-mac-boot is not
installed.
The full boot check also holds LUKS keyslots, provisioning leftovers and
package file drift, none of which a restored root's next boot reads, so it
refused restores on healthy Macs. The restore hook now runs --boot-chain,
still with no reboot pending.
limine-snapper-restore's own list can restore a snapshot other than the
booted one the pre hook checked. A post hook now checks the restored @ holds
the booted root's kernel, device trees, m1n1, U-Boot and Limine, and that the
UKI the restore put back carries that kernel; otherwise it keeps the reboot
from being offered and says how to put the backup back.

Also name Limine among a refused snapshot's packages, read --restore-kernels
snapshots off the top level, refuse when the platform cannot be told, and
stop waiting for Enter after five minutes.
A snapshot from before Limine reads as a GRUB Mac from inside, so its boot
went to the subvolume swap, which cannot run there. Limine's restore hook
says why it cannot be restored.
…apshot-restore

# Conflicts:
#	docs/lifecycle-dispatch.md
After a mismatched snapshot is restored from limine-snapper-restore's list,
the ESP holds its UKI, so the pre hook refused the restore the post hook told
the owner to run. The post hook now leaves the backup to pick in /run, and the
pre hook lets that restore through for the post hook to check. The post hook
also compares crypttab and the root mount, names the backup by when it was
written, says to ignore the reboot prompt that follows, and refuses when the
platform detector does not give a clear answer.
…n a mismatch

The post hook passed a root from before the Limine activation picked from
the restore's list; it now requires the activation and the same ESP, as the
pre hook does for a booted root. A root it cannot read or a platform it cannot
tell is reported unchecked and no longer arms the undo, and the undo applies
only while the booted root fails its own check, so a leftover marker skips
nothing. Locks count only when root owns them, and the subvolume swap refuses
a Mac's snapshot boot with why. The top-level mountpoint's parent can be set
for tests, which now run the mount and unmount.
…snapshot-boot refusal plainly

The post hook now asks what omarchy-mac-limine-active asks of a root:
limine-update as well as the activation marker and defaults. A snapshot boot
refused by the subvolume swap may be a GRUB Mac's too, so the refusal no
longer says it predates Limine.
@maralcbr
maralcbr merged commit 84352fd into quattro-upstream Sep 25, 2026
6 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.

1 participant