From 0cfbe9820d328010f4da22297438dff261d69495 Mon Sep 17 00:00:00 2001 From: Val Packett Date: Fri, 8 Aug 2025 02:53:13 -0300 Subject: [PATCH] Add readme notes --- README.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5f46938..df3aac1 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,38 @@ (it.. runs as a "sidecar" to a VM.. but manages D-*Bus*.. get it?) -TODO:WIP +A cross-domain smart D-Bus proxying system that makes (some) [XDG Desktop Portals] work across virtual machines. + +[XDG Desktop Portals]: https://flatpak.github.io/xdg-desktop-portal/docs/index.html + +## Design Overview + +- `sidebus-broker` host process: + - to be launched alongside the VMM + - hosts D-Bus servers in-process, based on [busd](https://github.com/dbus2/busd): + - a "private" bus for VM-instance-specific daemons such as permission-store and document-portal + - a "VM" bus, the one actually exposed to the guest over vsock + - orchestrates the lifecycle of the aforementioned daemons + virtiofsd + - (we are sharing the directory *provided by* the document-portal FUSE filesystem!) + - provides portal front-end interfaces like `org.freedesktop.portal.FileChooser` on the VM bus + - by proxying to the host session's xdg-desktop-portal!.. + - (not talking directly to impls: don't want to reimplement per-DE portal selection; also 1:1 mapping is nicer to code) + - but with extra hooks like exposing files to the guest using our private (per-VM) document-portal! +- `sidebus-agent` guest process: + - listens on a guest unix socket, proxies D-Bus messages to a vsock + - spawned on-demand by systemd via socket activation + - uses systemd credentials for config args like vsock port + - (very convenient to pass via the VMM, e.g. qemu: `-smbios type=11,value=io.systemd.credential:sidebus.port=1337`) + - guest NixOS configuration exposed via the flake + +## Development Notes + +- the Nix flake provides paths to the daemons we run via environment variables.. + conveniently, both in the release build *and* in the dev shell (so rust-analyzer doesn't complain)! +- the `--debug-access` flag of `sidebus-broker` allows for testing on the host, without needing to connect over vsock, e.g.: + - `clear; rm /tmp/b/* ; mkdir -p /tmp/{b,r} ; RUST_LOG=debug cargo run --bin sidebus-broker -- --debug-access /tmp/b --vsock-port 1234 --runtime-dir /tmp/r` + - `GTK_A11Y=none DBUS_SESSION_BUS_ADDRESS=unix:path=/tmp/b/vm.sock ashpd-demo` + +## Acknowledgments + +[Spectrum](https://spectrum-os.org/)'s work on a similar system has been very helpful during the development process.