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.
89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# 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).
|