sidebus/README.md

sidebus

(it.. runs as a "sidecar" to a VM.. but manages D-Bus.. get it?)

A cross-domain smart D-Bus proxying system that makes (some) XDG Desktop Portals work across virtual machines.

Currently supporting:

• Camera (*)
• FileChooser
• FileTransfer (*)
• Inhibit
• Notification
• Print
• ScreenCast (*)
• Screenshot
• Settings
• Wallpaper

(*): only when using virtio-gpu cross-domain channels as transport, with a VMM that implements the required features

Design Overview

• sidebus-broker host process:
  • to be launched alongside the VMM
  • spawns VM-instance-private instances of permission-store and document-portal daemons, providing an internal private bus to them
  • when the guest connects to its socket, uses the connection as a *client* socket for the guest session (reverse tunnel)
  • the socket it listens on can be:
    • a vsock on the host (can be used with sidebus-agent)
    • a unix socket on the host, exposed by the VMM as a vsock in the guest (libkrun only supports vsock like this)
    • a unix socket on the host, exposed by the VMM / vGPU (rutabaga_gfx) as a virtio-gpu cross-domain channel
      • (instead of sidebus-agent, muvm-guest utilities should be used, which will be eventually part of rutabaga itself)
      • this is required for FileTransfer (file drag&drop/copy&paste) to work, which depends on the VMM's integration between virtio-gpu and virtiofs (currently muvm only)
      • this is required for ScreenCast/Camera to work, which needs the guest to spawn a PipeWire bridge using the passed socket handle from the D-Bus bridge
  • optionally spawns virtiofsd as well
    • the directory provided by the document-portal FUSE filesystem must be shared, so there's a lifecycle dependency if we only want to share its contents..
    • in munix, we just mount the parent directory into the sandbox namespace which is passed through as an entire / virtiofs
  • provides portal front-end interfaces like org.freedesktop.portal.FileChooser on the guest session 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!
  • the list of supported portals can be configured (reduced) at build time using Cargo feature flags
• sidebus-agent guest process:
  • connects to the broker over vsock and splices the connection into the VM (session) bus
    • (not used when using virtgpu cross-domain channels, muvm guest tooling is used in that case instead)
  • can be spawned on-demand by D-Bus
  • 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)
    • (it's just a directory with files so it's trivial to do w/o systemd as well)

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's work on a similar system has been very helpful during the development process.