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:
parent
053fd3d28d
commit
962e125208
2 changed files with 92 additions and 1 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
89
docs/DUAL-BOOT.md
Normal file
89
docs/DUAL-BOOT.md
Normal 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).
|
||||
Loading…
Add table
Reference in a new issue