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.
This commit is contained in:
Phoebus 2026-09-26 15:31:06 -07:00
parent 053fd3d28d
commit 962e125208
2 changed files with 92 additions and 1 deletions

View file

@ -205,7 +205,9 @@ the actual execution, so the UI cannot diverge from the backend.
stays explicit. stays explicit.
- **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel` - **Kernel/boot**: `sys-kernel/gentoo-kernel-bin` (safe) or `gentoo-kernel`
(optimized), dracut initramfs, systemd-boot BLS entries, plus a snapshot-based (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 ## Desktop assistant and administration architecture

89
docs/DUAL-BOOT.md Normal file
View file

@ -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 <ESP-UUID-HERE>
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 <ESP-UUID-HERE>
# Copy these three lines from your BLS entry. Note: Phoebus uses
# rd.luks.name=<LUKS-UUID>=cryptroot (not rd.luks.uuid), plus
# rootfstype=btrfs rootflags=subvol=@.
linux /<machine-id>/<kver>/linux rd.luks.name=<LUKS-UUID>=cryptroot root=/dev/mapper/cryptroot rootfstype=btrfs rootflags=subvol=@ rw quiet
initrd /<machine-id>/<kver>/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).