Headless mode, virtual desktop scripts, tool peers without a desktop

- UU_DESKTOP_BACKEND=none: host goes online without a display; terminal, file
  transfer and port mapping stay available, desktop offers are ignored.
- Tool peers (file/terminal/port mapping) get a nominal ScreenSources/CaptureChange
  and Allow permissions when no desktop is available: the port-mapping viewer
  aborts otherwise (also affected portal hosts before local consent).
- x11_engine: an explicit DISPLAY that cannot be opened no longer falls back to
  :0/:1 (would silently capture the physical screen).
- contrib/virtual-desktop: Xvfb + desktop session on the systemd user bus
  (or a private dbus-run-session bus) and a uuremote-native drop-in.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
VallierDevandClaude Opus 5.5 committed 2026-10-15 10:13:58 +08:00
1 parent 49edf1d389
commit 26d4812480
7 files changed
+89 -7

No files matched your search

+5 -2
View File
@@ -60,9 +60,12 @@ int x11_init(const char *display_name) {
g_display = XOpenDisplay(display_name);
} else {
const char *configured = getenv("DISPLAY");
/* An explicit DISPLAY that fails must not silently fall back to another (physical) screen. */
if (configured && *configured) g_display = XOpenDisplay(configured);
if (!g_display) g_display = XOpenDisplay(":0");
if (!g_display) g_display = XOpenDisplay(":1");
else {
g_display = XOpenDisplay(":0");
if (!g_display) g_display = XOpenDisplay(":1");
}
}
if (!g_display) {
return -1;
+40
View File
@@ -0,0 +1,40 @@
#!/bin/sh
# Virtual desktop for a monitorless Linux host: Xvfb + a desktop session on its own D-Bus session 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)
# UU_VIRTUAL_SESSION session command (default: first of startxfce4, mate-session, startlxqt, openbox-session, xterm)
# UU_VIRTUAL_BUS user (default): the systemd user bus (`loginctl enable-linger`) gets DISPLAY, so
# D-Bus/systemd-activated apps (GNOME terminal, portals, ...) open on the virtual screen;
# private: own dbus-run-session bus, for machines that also run a real desktop session
set -eu
display="${UU_VIRTUAL_DISPLAY:-:99}"
size="${UU_VIRTUAL_SIZE:-1920x1080}"
session="${UU_VIRTUAL_SESSION:-}"
if [ -z "$session" ]; then
for candidate in startxfce4 mate-session startlxqt openbox-session xterm; do
if command -v "$candidate" >/dev/null 2>&1; then session="$candidate"; break; fi
done
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; }
Xvfb "$display" -screen 0 "${size}x24" -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
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"
else
# Private bus: independent of the user manager; activation through systemd may still escape to the user bus.
dbus-run-session -- sh -c "$session"
fi
@@ -0,0 +1,14 @@
[Unit]
Description=Virtual X desktop for uu-remote-linux (Xvfb + session bus)
After=dbus.socket
[Service]
# Environment=UU_VIRTUAL_SESSION=startxfce4
# Environment=UU_VIRTUAL_SIZE=1920x1080
# Environment=UU_VIRTUAL_BUS=private
ExecStart=%h/.local/bin/uu-virtual-desktop
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
@@ -0,0 +1,10 @@
# ~/.config/systemd/user/uuremote-native.service.d/virtual-display.conf
# Serve the virtual desktop instead of a physical display.
[Unit]
Requires=uu-virtual-desktop.service
After=uu-virtual-desktop.service
[Service]
Environment=DISPLAY=:99
Environment=UU_DESKTOP_BACKEND=x11
UnsetEnvironment=XAUTHORITY WAYLAND_DISPLAY
+6 -1
View File
@@ -2,6 +2,10 @@
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum DesktopBackend { X11, Wayland, Portal }
/// `UU_DESKTOP_BACKEND=none`: headless host — no display is opened; terminal, file transfer and
/// port mapping stay available (servers without a monitor or logged-in session).
pub fn headless() -> bool { std::env::var("UU_DESKTOP_BACKEND").is_ok_and(|v| v == "none") }
pub fn detect() -> Result<DesktopBackend, String> {
let backend=select(std::env::var("UU_DESKTOP_BACKEND").ok().as_deref(),
std::env::var("XDG_SESSION_TYPE").ok().as_deref(),
@@ -16,12 +20,13 @@ fn select(explicit: Option<&str>, session: Option<&str>, socket: Option<&str>) -
Some("x11") => Ok(DesktopBackend::X11),
Some("wayland") => Ok(DesktopBackend::Wayland),
Some("portal") => Ok(DesktopBackend::Portal),
Some("none") => Ok(DesktopBackend::X11), // never opened, see headless()
None | Some("auto") => {
if session == Some("wayland") || socket.is_some_and(|s| !s.is_empty()) {
Ok(DesktopBackend::Wayland)
} else { Ok(DesktopBackend::X11) }
},
Some(_) => Err("UU_DESKTOP_BACKEND must be auto, x11, wayland or portal".into()),
Some(_) => Err("UU_DESKTOP_BACKEND must be auto, x11, wayland, portal or none".into()),
}
}
+7 -1
View File
@@ -205,7 +205,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
}
log::info!("Starting uu-remote-linux host v{}...", env!("CARGO_PKG_VERSION"));
let mut capture = Arc::new((if desktop_backend::detect()?==desktop_backend::DesktopBackend::Portal
let mut capture = Arc::new((if desktop_backend::headless() {
Err("headless mode (UU_DESKTOP_BACKEND=none)".to_owned())
} else if desktop_backend::detect()?==desktop_backend::DesktopBackend::Portal
&& std::env::var("UU_PORTAL_PREAUTHORIZE").ok().as_deref()!=Some("1") {
Err("Portal screen access requires a desktop connection and local consent".to_owned())
} else { ScreenCapture::new() }).unwrap_or_else(|error| {
@@ -359,6 +361,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
}
let stale_portal=capture.portal.as_ref().is_some_and(|session|!session.is_alive())
&& crate::session_lock::locked_now() == Some(false);
if desktop && desktop_backend::headless() {
log::info!("Desktop connection ignored: headless mode (terminal, file transfer and port mapping remain available)");
continue;
}
let session_capture=if desktop && (capture.init_error.is_some() || stale_portal) {
if stale_portal {
input.release_held();input.bind_portal(None);
+7 -3
View File
@@ -438,18 +438,22 @@ impl WebRtcSession {
let next_seq = || sequence.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
// Default file-transfer folder: the desktop user's home directory.
let home = std::env::var("HOME").unwrap_or_else(|_| "/".into());
let desktop_permission=if screen.init_error.is_none() {
// Tool peers are permitted without a desktop; the port-mapping viewer aborts on Reject.
let desktop_permission=if screen.init_error.is_none() || !desktop {
crate::system_metrics::Permission::Allow
} else { crate::system_metrics::Permission::Reject };
// Without a desktop (headless/portal before consent) the port-mapping tool still waits
// for ScreenSources/CaptureChange and aborts otherwise: tool peers get a nominal screen.
let screen_size=if screen.init_error.is_none() { (screen.width, screen.height) } else { (1920, 1080) };
let messages = [
(8, crate::initialization::encode_capture_change(next_seq(), timestamp, 0, 0, "Linux desktop")),
(13, Ok(crate::initialization::envelope(next_seq(), timestamp, 13, &init_actions.metrics_payload(desktop_sound, desktop_permission)))),
(26, Ok(crate::initialization::envelope(next_seq(), timestamp, 26,
&crate::system_metrics::remote_download_path(&home)))),
(7, crate::capture_setting::screen_sources(next_seq(), timestamp, (screen.width, screen.height), init_video.borrow().output, "Linux desktop")),
(7, crate::capture_setting::screen_sources(next_seq(), timestamp, screen_size, init_video.borrow().output, "Linux desktop")),
];
for (field, message) in messages {
if screen.init_error.is_some() && matches!(field,7|8) { continue; }
if desktop && screen.init_error.is_some() && matches!(field,7|8) { continue; }
let message = match message {
Ok(message) => message,
Err(e) => { log::error!("CONTROL initialization encode failed: {}", e); return; }