phoebus_os/docs/VIRTUAL-MACHINES.md
Phoebus c5b1c34cbc
Some checks are pending
ci / test (push) Waiting to run
fix(desktop): enlarge Settings and align QEMU pointer
2026-10-01 17:39:22 -07:00

49 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Virtual machine guests
Phoebus detects the installer environment with `systemd-detect-virt --vm` and
DMI vendor/product information. A Mango desktop install selects only the
matching guest tools. The distribution kernel and Mesa remain the graphics
foundation; the hypervisor must expose its accelerated adapter and the host
must provide acceleration. Guest software cannot create 3D acceleration when
the host disables it.
| Host | Phoebus install selection | Host graphics setting | Resize path |
|---|---|---|---|
| QEMU/KVM | `qemu-guest-agent`, `spice-vdagent`, Mesa `virgl`, `wlr-randr` | VirtIO GPU; the interactive launcher defaults to 2D with aligned pointer input and offers VirGL through `--graphics gl` | For guest resolution changes, provide a SPICE vdagent channel and a client that sends display configuration (for example virt-viewer). |
| VMware | `open-vm-tools` with `resolutionkms`, Mesa `vmware`, `wlr-randr` | Enable the VMware accelerated graphics adapter in VM settings | `vmtoolsd` plus the virtual DRM driver's preferred-mode events; Phoebus applies a newly advertised preferred mode in Mango. |
| VirtualBox | Guest Additions with `gui`, Mesa `vmware` for the VMSVGA adapter, `wlr-randr` | Select VMSVGA and enable 3D acceleration if the host supports it | Guest Additions service and `VBoxClient-all` in the Mango session; Phoebus also applies a newly advertised preferred mode. |
The display watcher acts only when the hypervisor advertises a *new* preferred
mode. A manual choice remains in place if the preferred mode did not change.
If DMS has written an output configuration, Phoebus leaves it alone. The
existing low-VGA boot promotion now checks the `wlr-randr` output correctly.
`run-vm.sh --graphics auto` is the default for the disposable interactive
QEMU launcher and chooses the aligned 2D path. `--graphics gl` requires VirGL;
the GL viewers tested here scaled the picture without scaling pointer input,
causing clicks to drift farther from the cursor toward the lower right. Similar
problems are tracked in QEMU's [GTK](https://gitlab.com/qemu-project/qemu/-/issues/761)
and [SDL](https://gitlab.com/qemu-project/qemu/-/issues/2447) issue reports. The
launcher uses `virtio-vga` variants so the UEFI and LUKS prompt remain visible,
and attaches an absolute USB tablet. It also provides a QEMU guest-agent virtio port;
Gentoo's udev rule starts the otherwise static guest-agent unit when that port
appears.
## Verification boundary
The visible QEMU playground booted and reached Mango + DarkMaterialShell with
`virtio-vga-gl`; the guest kernel reported `+virgl`. The host's GTK and SDL GL
viewers both shrank a 1680×1050 guest image and offset clicks. Relaunching the
same qcow2 with 2D VirtIO, GTK zoom disabled and an absolute tablet filled the
window; a click on the visible Settings close icon closed that window. The QEMU
resize watcher cannot claim guest resolution changes through the tested GTK
setup. The new `wlr-randr` package was
installed and its output inspected in this disposable VM. Portage dependency
previews resolved the QEMU, VMware and VirtualBox package atoms. VMware and
VirtualBox guest sessions, 3D rendering and resize events still require tests
in those hypervisors before they are called VM verified.
The guest setup follows [QEMU's VirtIO GPU documentation](https://www.qemu.org/docs/master/system/devices/virtio/virtio-gpu.html),
[SPICE's guest agent description](https://www.spice-space.org/spice-user-manual.html),
[Oracle's VirtualBox Guest Additions manual](https://download.virtualbox.org/virtualbox/7.2.2/UserManual.pdf),
and the [Gentoo guest package guidance](https://wiki.gentoo.org/wiki/Virtual_machines).