From 962e125208f339f416d3583449c4225b35b7f7bd Mon Sep 17 00:00:00 2001 From: Phoebus Date: Sat, 26 Sep 2026 15:31:06 -0700 Subject: [PATCH] docs(dual-boot): safe GRUB chainload of systemd-boot plus login notes Phoebus stays systemd-boot + BLS (proven baseline, ADR 0002); external GRUB chainloads EFI/systemd/systemd-bootx64.efi so sys undo BLS rewrites (ADR 0007) keep working and LUKS2/Argon2id is never exposed to GRUB cryptodisk. The direct-kernel alternative is documented as fragile with the correct rd.luks.name command line. No installer change. --- docs/ARCHITECTURE.md | 4 +- docs/DUAL-BOOT.md | 89 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 docs/DUAL-BOOT.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0d1dd69..bddb1c4 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -205,7 +205,9 @@ the actual execution, so the UI cannot diverge from the backend. stays explicit. - **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel` (optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based - recovery entry that does not depend on the live root. + recovery entry that does not depend on the live root. For running Phoebus + alongside other OSes, chainload this systemd-boot from the other OS's GRUB; + see `docs/DUAL-BOOT.md` (GRUB is never installed into the Phoebus target). ## Desktop assistant and administration architecture diff --git a/docs/DUAL-BOOT.md b/docs/DUAL-BOOT.md new file mode 100644 index 0000000..548c100 --- /dev/null +++ b/docs/DUAL-BOOT.md @@ -0,0 +1,89 @@ +# Dual-booting Phoebus OS with GRUB (chainload, safe) + +Phoebus OS installs and boots with **systemd-boot + BLS entries** on the ESP. +That is the proven baseline (`docs/STATUS.md`, ADR 0002) and the layout that +`sys undo` rewrites on rollback (ADR 0007). **Do not replace it with GRUB +inside Phoebus.** + +To run Phoebus alongside Windows or another Linux distribution whose boot menu +is GRUB 2, **chainload Phoebus's `systemd-boot` from GRUB**. This preserves the +verified boot path, keeps snapshot rollbacks coherent, and avoids GRUB's +LUKS2/Argon2id limitations entirely (kernels stay on the FAT32 ESP; dracut +unlocks LUKS2 with the kernel's native crypto). + +## Login manager (already canonical, no change) + +`greetd` + `tuigreet` is the installed login stack (`vt = 7`, `greeter` user, +default session `/usr/local/bin/phoebus-session-mango` launching Mango + +DankMaterialShell). Implemented in `phoebus-core::system::greetd_config` and +`phoebus-executor::desktop::configure_login`; VM-verified through greeter +startup and seated PAM authentication. Dual-boot changes nothing here. + +## Recommended: GRUB chainloads systemd-boot + +On the system that owns GRUB, add to `/etc/grub.d/40_custom`: + +```grub +menuentry "Phoebus OS" --class phoebus --class os { + insmod part_gpt + insmod fat + insmod chain + # ESP filesystem UUID where Phoebus installed systemd-boot. + # Find it with: lsblk -f (or blkid) on the FAT32 ESP. + search --no-floppy --fs-uuid --set=root + chainloader /EFI/systemd/systemd-bootx64.efi +} +``` + +Then regenerate: + +```bash +sudo grub-mkconfig -o /boot/grub/grub.cfg +``` + +Verify on the ESP (mounted at `/efi` on Phoebus) that +`EFI/systemd/systemd-bootx64.efi` (plus the `EFI/BOOT/BOOTX64.EFI` fallback) +exists before rebooting. + +## Alternative (fragile): direct kernel boot from GRUB + +Prefer chainloading. A direct entry bypasses the systemd-boot menu and **drifts +out of sync** whenever `sys undo`, a kernel update, or a tuned-kernel install +rewrites `/loader/entries/*.conf`. If you use one anyway, never hand-write the +command line: copy the `linux`, `initrd`, and `options` lines verbatim from the +current Phoebus BLS entry (`/efi/loader/entries/*.conf`). + +Reference shape (values differ per install; copy yours exactly): + +```grub +menuentry "Phoebus OS (Direct)" --class phoebus --class gnu-linux { + insmod part_gpt + insmod fat + search --no-floppy --fs-uuid --set=root + # Copy these three lines from your BLS entry. Note: Phoebus uses + # rd.luks.name==cryptroot (not rd.luks.uuid), plus + # rootfstype=btrfs rootflags=subvol=@. + linux ///linux rd.luks.name==cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rootflags=subvol=@ rw quiet + initrd ///initrd +} +``` + +Re-copy after every kernel/rollback change, or switch back to chainloading. + +## Verification + +1. `lsblk -f` / `blkid`: record the FAT32 ESP UUID. +2. Confirm `EFI/systemd/systemd-bootx64.efi` is present on that ESP. +3. Make GRUB the default UEFI boot target; select **Phoebus OS**. +4. Expect the systemd-boot menu (or direct kernel load), then the dracut LUKS + passphrase prompt, then `greetd`/`tuigreet` on VT 7. +5. Log in and confirm Mango + DankMaterialShell start. + +## Non-goals / rules + +- The Phoebus installer does not install GRUB into the target and does not + support `bootloader = "grub"` (`InstallConfig` accepts `systemd-boot` only). +- Never enable GRUB `cryptodisk` against the Phoebus LUKS2 container as the + primary boot path (Argon2id incompatibility / CPU cost). +- Never share or reformat the Phoebus ESP destructively; destructive testing + stays on a disposable qcow2 image, never `/dev/*` (AGENTS.md rule 1).