From 90c33e173caecbaf72c0942fa3f0cb911e7b102b Mon Sep 17 00:00:00 2001 From: VallierDev <24893073+VallierDev@users.noreply.github.com> Date: Thu, 15 Oct 2026 10:48:07 +0800 Subject: [PATCH] Supervise authenticated virtual desktops on the linger user bus --- AGENTS.md | 6 ++ README.en.md | 8 ++- README.md | 8 ++- contrib/virtual-desktop/ACCEPTANCE.md | 33 +++++++++ contrib/virtual-desktop/uu-virtual-desktop | 71 +++++++++++++++---- .../uu-virtual-desktop.service | 5 ++ contrib/virtual-desktop/virtual-display.conf | 3 +- 7 files changed, 116 insertions(+), 18 deletions(-) create mode 100644 contrib/virtual-desktop/ACCEPTANCE.md diff --git a/AGENTS.md b/AGENTS.md index 2674352..a531115 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -246,3 +246,9 @@ PulseAudio and PipeWire-pulse use the same `pactl` interface (install `pulseaudi `libpulse` on Arch). When routing is unavailable, the existing mute/monitor path remains. Changing the switch restarts only the scoped audio encoder; normal non-muted capture is unchanged. `virtual-audio-probe` temporarily routes output for five seconds and restores it (local diagnostic). + +### Virtual desktop user bus + +The supervisor imports DISPLAY and XAUTHORITY into the linger user bus, waits for authenticated +X11 readiness, and keeps its cleanup trap alive. The sample drop-in uses `%t/uu-virtual-99.Xauthority`. +Use a dedicated headless account. See the [setup and official Mac acceptance checklist](contrib/virtual-desktop/ACCEPTANCE.md). diff --git a/README.en.md b/README.en.md index eabeed3..dcb3dea 100644 --- a/README.en.md +++ b/README.en.md @@ -176,7 +176,7 @@ Log in once with `uuremote-server login --no-gui` (QR in the terminal). **Virtual desktop**: for a full remote desktop, run a desktop session (Xfce recommended) on an Xvfb screen: ```sh -sudo apt install xvfb dbus-x11 xfce4 # or another session, chosen with UU_VIRTUAL_SESSION +sudo apt install xvfb xauth x11-utils dbus-x11 dbus-user-session xfce4 # or another session, chosen with UU_VIRTUAL_SESSION install -Dm755 contrib/virtual-desktop/uu-virtual-desktop ~/.local/bin/uu-virtual-desktop install -Dm644 contrib/virtual-desktop/uu-virtual-desktop.service ~/.config/systemd/user/uu-virtual-desktop.service install -Dm644 contrib/virtual-desktop/virtual-display.conf ~/.config/systemd/user/uuremote-native.service.d/virtual-display.conf @@ -284,3 +284,9 @@ PulseAudio and PipeWire-pulse use the same `pactl` interface (install `pulseaudi `libpulse` on Arch). When routing is unavailable, the existing mute/monitor path remains. Changing the switch restarts only the scoped audio encoder; normal non-muted capture is unchanged. `virtual-audio-probe` temporarily routes output for five seconds and restores it (local diagnostic). + +### Virtual desktop user bus + +The supervisor imports DISPLAY and XAUTHORITY into the linger user bus, waits for authenticated +X11 readiness, and keeps its cleanup trap alive. The sample drop-in uses `%t/uu-virtual-99.Xauthority`. +Use a dedicated headless account. See the [setup and official Mac acceptance checklist](contrib/virtual-desktop/ACCEPTANCE.md). diff --git a/README.md b/README.md index d32041c..5599bde 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,7 @@ X11 默认继续用 XTest,因为它能正确处理网络延迟下按住不放 **虚拟桌面**:需要完整的远程桌面时,用 Xvfb 创建一块虚拟屏幕,再在上面跑一个桌面环境(推荐 Xfce): ```sh -sudo apt install xvfb dbus-x11 xfce4 # 或其他桌面环境,用 UU_VIRTUAL_SESSION 指定 +sudo apt install xvfb xauth x11-utils dbus-x11 dbus-user-session xfce4 # 或其他桌面环境,用 UU_VIRTUAL_SESSION 指定 install -Dm755 contrib/virtual-desktop/uu-virtual-desktop ~/.local/bin/uu-virtual-desktop install -Dm644 contrib/virtual-desktop/uu-virtual-desktop.service ~/.config/systemd/user/uu-virtual-desktop.service install -Dm644 contrib/virtual-desktop/virtual-display.conf ~/.config/systemd/user/uuremote-native.service.d/virtual-display.conf @@ -266,3 +266,9 @@ PulseAudio and PipeWire-pulse use the same `pactl` interface (install `pulseaudi `libpulse` on Arch). When routing is unavailable, the existing mute/monitor path remains. Changing the switch restarts only the scoped audio encoder; normal non-muted capture is unchanged. `virtual-audio-probe` temporarily routes output for five seconds and restores it (local diagnostic). + +### Virtual desktop user bus + +The supervisor imports DISPLAY and XAUTHORITY into the linger user bus, waits for authenticated +X11 readiness, and keeps its cleanup trap alive. The sample drop-in uses `%t/uu-virtual-99.Xauthority`. +Use a dedicated headless account. See the [setup and official Mac acceptance checklist](contrib/virtual-desktop/ACCEPTANCE.md). diff --git a/contrib/virtual-desktop/ACCEPTANCE.md b/contrib/virtual-desktop/ACCEPTANCE.md new file mode 100644 index 0000000..0867092 --- /dev/null +++ b/contrib/virtual-desktop/ACCEPTANCE.md @@ -0,0 +1,33 @@ +# Virtual user-bus desktop acceptance + +Install Xvfb, xauth, xdpyinfo, Xfce and dbus-user-session (Debian) or dbus-broker (Arch). +The default is `UU_VIRTUAL_BUS=user`; use it on a dedicated headless account with no real +GUI session. Its D-Bus and systemd activation environment is shared by all that user's apps. +`private` isolates ordinary D-Bus activation but cannot redirect systemd-activated programs. + +1. Install the script in `~/.local/bin`, the unit in `~/.config/systemd/user`, and + `virtual-display.conf` in the host service's `.service.d/` directory. +2. `sudo loginctl enable-linger "$USER"`; set `UU_VIRTUAL_SESSION=startxfce4` in the desktop + unit. `systemctl --user daemon-reload`; enable both units. A different display needs a + matching `DISPLAY` and `XAUTHORITY=%t/uu-virtual-N.Xauthority` in the host drop-in. +3. Reboot a disposable VM with graphical login disabled. Before logging into a desktop, + check both user units are active, Xvfb is `:99`, no real GUI login session exists, and + host availability is `ready`. The desktop unit uses notify readiness after authenticated + X11 access succeeds, so the host does not race the X socket. +4. `DISPLAY=:99 XAUTHORITY="$XDG_RUNTIME_DIR/uu-virtual-99.Xauthority" xdpyinfo` must work. + `gnome-terminal` launched over the user bus must open on `:99`. Check its window via + `xdotool search --class gnome-terminal-server`; do not log terminal text. +5. Restart/stop the desktop unit: its Xvfb, desktop children and authority file must be + removed. A stale pre-existing display is rejected. The TCP X11 listener is disabled. + +## Official Mac client checklist (human acceptance) + +- [ ] Select the isolated VM device; confirm its identity before connecting. +- [ ] After VM boot, connect without a physical/graphical login; Xfce is visible. +- [ ] Open GNOME Terminal through its application launcher; it appears on the same `:99` desktop. +- [ ] Move/click/drag, scroll, type a synthetic test marker and verify key releases (no repeats). +- [ ] Verify both clipboard directions using synthetic text; keep the remote window focused. +- [ ] Toggle 静音运行 during playback: remote sound remains audible; VM physical output is silent. +- [ ] Disconnect/reconnect; confirm desktop and applications remain usable. +- [ ] End the last session: audio default/modules restore; auto-lock follows the saved setting. +- [ ] Repeat after reboot with no GUI login. Do not enter production credentials in test fixtures. diff --git a/contrib/virtual-desktop/uu-virtual-desktop b/contrib/virtual-desktop/uu-virtual-desktop index d31a2ac..1e3e69f 100755 --- a/contrib/virtual-desktop/uu-virtual-desktop +++ b/contrib/virtual-desktop/uu-virtual-desktop @@ -1,5 +1,5 @@ #!/bin/sh -# Virtual desktop for a monitorless Linux host: Xvfb + a desktop session on its own D-Bus session bus. +# Virtual desktop for a monitorless Linux host: Xvfb + a desktop session on the user bus (or an isolated private bus). # uuremote-server then serves it with DISPLAY=$UU_VIRTUAL_DISPLAY (see README in this folder). # UU_VIRTUAL_DISPLAY X display number (default :99) # UU_VIRTUAL_SIZE screen size (default 1920x1080) @@ -18,23 +18,64 @@ if [ -z "$session" ]; then fi [ -n "$session" ] || { echo "no desktop session found; set UU_VIRTUAL_SESSION" >&2; exit 1; } command -v Xvfb >/dev/null || { echo "Xvfb not installed (apt install xvfb)" >&2; exit 1; } -command -v dbus-run-session >/dev/null || { echo "dbus-run-session not installed (apt install dbus)" >&2; exit 1; } +bus="${UU_VIRTUAL_BUS:-user}" +case "$bus" in user|private) ;; *) echo "UU_VIRTUAL_BUS must be user or private" >&2; exit 1 ;; esac +command -v xauth >/dev/null || { echo "xauth not installed" >&2; exit 1; } +command -v xdpyinfo >/dev/null || { echo "xdpyinfo not installed" >&2; exit 1; } +case "$display" in :[0-9]*) ;; *) echo "UU_VIRTUAL_DISPLAY must be a local display number" >&2; exit 1 ;; esac +number="${display#:}" +case "$number" in *[!0-9]*|'') echo "invalid display number" >&2; exit 1 ;; esac +socket="/tmp/.X11-unix/X$number" +[ ! -e "$socket" ] || { echo "display already in use" >&2; exit 1; } +umask 077 +export XDG_RUNTIME_DIR="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}" +authority="$XDG_RUNTIME_DIR/uu-virtual-$number.Xauthority" +# The display socket was checked above; replace a stale authority after a service crash. +[ ! -L "$authority" ] || { echo "refusing a symlink authority" >&2; exit 1; } +temporary=$(mktemp "$XDG_RUNTIME_DIR/uu-virtual-xauth.XXXXXX") +xvfb= +child= +cleanup() { + trap - EXIT INT TERM + [ -z "$child" ] || kill "$child" 2>/dev/null || : + [ -z "$xvfb" ] || kill "$xvfb" 2>/dev/null || : + [ -z "$xvfb" ] || wait "$xvfb" 2>/dev/null || : + rm -f "$authority" "$temporary" +} +trap cleanup EXIT +trap 'exit 143' TERM +trap 'exit 130' INT +cookie=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n') +xauth -f "$temporary" add "$display" MIT-MAGIC-COOKIE-1 "$cookie" +unset cookie +mv "$temporary" "$authority" +export XAUTHORITY="$authority" -Xvfb "$display" -screen 0 "${size}x24" -nolisten tcp -noreset & +Xvfb "$display" -screen 0 "${size}x24" -auth "$authority" -nolisten tcp -noreset & xvfb=$! -trap 'kill "$xvfb" 2>/dev/null' EXIT INT TERM -socket="/tmp/.X11-unix/X${display#:}" -for _ in $(seq 50); do [ -S "$socket" ] && break; sleep 0.1; done -[ -S "$socket" ] || { echo "Xvfb did not start on $display" >&2; exit 1; } - export DISPLAY="$display" -unset WAYLAND_DISPLAY XAUTHORITY +unset WAYLAND_DISPLAY SESSION_MANAGER export XDG_SESSION_TYPE=x11 -if [ "${UU_VIRTUAL_BUS:-user}" = user ]; then - # Activated services inherit the user manager's environment, not this process's: export DISPLAY there. - dbus-update-activation-environment --systemd DISPLAY XDG_SESSION_TYPE - exec sh -c "$session" +ready=false +for _ in $(seq 50); do + kill -0 "$xvfb" 2>/dev/null || break + if xdpyinfo >/dev/null 2>&1; then ready=true; break; fi + sleep 0.1 +done +[ "$ready" = true ] || { echo "Xvfb did not become ready" >&2; exit 1; } +if [ "$bus" = user ]; then + # Linger creates the user manager and its bus without a graphical login. + : "${XDG_RUNTIME_DIR:=/run/user/$(id -u)}" + export XDG_RUNTIME_DIR + export DBUS_SESSION_BUS_ADDRESS="unix:path=$XDG_RUNTIME_DIR/bus" + [ -S "$XDG_RUNTIME_DIR/bus" ] || { echo "user bus unavailable; enable loginctl enable-linger" >&2; exit 1; } + systemctl --user unset-environment WAYLAND_DISPLAY + dbus-update-activation-environment --systemd DISPLAY XAUTHORITY XDG_SESSION_TYPE + # Keep the supervising shell alive: exec would discard the Xvfb cleanup trap. + sh -c "$session" & else - # Private bus: independent of the user manager; activation through systemd may still escape to the user bus. - dbus-run-session -- sh -c "$session" + dbus-run-session -- sh -c "$session" & fi +child=$! +if [ -n "${NOTIFY_SOCKET:-}" ]; then systemd-notify --ready; fi +wait "$child" diff --git a/contrib/virtual-desktop/uu-virtual-desktop.service b/contrib/virtual-desktop/uu-virtual-desktop.service index 5f09cf6..6fe345e 100644 --- a/contrib/virtual-desktop/uu-virtual-desktop.service +++ b/contrib/virtual-desktop/uu-virtual-desktop.service @@ -3,6 +3,11 @@ Description=Virtual X desktop for uu-remote-linux (Xvfb + session bus) After=dbus.socket [Service] +Type=notify +NotifyAccess=all +TimeoutStartSec=30 +TimeoutStopSec=10 +KillMode=control-group # Environment=UU_VIRTUAL_SESSION=startxfce4 # Environment=UU_VIRTUAL_SIZE=1920x1080 # Environment=UU_VIRTUAL_BUS=private diff --git a/contrib/virtual-desktop/virtual-display.conf b/contrib/virtual-desktop/virtual-display.conf index 2fb578d..d91b205 100644 --- a/contrib/virtual-desktop/virtual-display.conf +++ b/contrib/virtual-desktop/virtual-display.conf @@ -7,4 +7,5 @@ After=uu-virtual-desktop.service [Service] Environment=DISPLAY=:99 Environment=UU_DESKTOP_BACKEND=x11 -UnsetEnvironment=XAUTHORITY WAYLAND_DISPLAY +Environment=XAUTHORITY=%t/uu-virtual-99.Xauthority +UnsetEnvironment=WAYLAND_DISPLAY