phoebus_os/docs/DUAL-BOOT.md
Phoebus 962e125208 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.
2026-09-26 15:31:06 -07:00

3.7 KiB

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.

On the system that owns GRUB, add to /etc/grub.d/40_custom:

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:

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):

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