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.
|
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
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