| name | remote-desktop |
| description | Connect to dev-secondary graphical desktop from dev-primary via VNC over SSH tunnel |
| type | reference |
| version | 1.0.0 |
| category | workspace-hub |
Remote Desktop — dev-secondary
Connect to dev-secondary graphical desktop from dev-primary via VNC over SSH tunnel.
Quick Start
Use the live repo script name:
bash scripts/operations/connection/vnc-ace-linux-2.sh
Historical docs/audits may mention vnc-dev-secondary.sh; verify the actual script path with find scripts/operations/connection -maxdepth 1 -type f -iname '*vnc*' before telling the user what to run.
Script is fully self-contained: detects display+auth, auto-starts x11vnc if needed, opens tunnel, launches viewer.
How It Works
- Checks if x11vnc is listening on port 5900
- If not: parses live Xorg
ps entry to find display + auth file dynamically
- Starts x11vnc (no sudo if vamsee owns display; sudo prompt if GDM/root owns it)
- Opens SSH tunnel
localhost:5900 → dev-secondary:5900
- Launches
xtigervncviewer localhost:5900
Required Flags (Hard-Won)
| Flag | Why Required |
|---|
-noshm | MIT-SHM denied when x11vnc user ≠ X server owner |
-noxdamage | GNOME/Mutter compositor causes XIO crash via XDAMAGE |
-noscr | GNOME conflicts with RECORD extension scroll detection |
-auth <explicit-path> | -auth guess fails when running as root on GDM display |
-o /dev/null | Avoids stale root-owned log file permission errors |
Auth File Location
Resolved dynamically from ps wwwaux | grep Xorg:
- GDM only (no user login):
/run/user/120/gdm/Xauthority — requires sudo
- User session active:
/run/user/1000/gdm/Xauthority — no sudo needed
Persistent Setup (Optional)
To avoid needing to start x11vnc each time, create a systemd service on dev-secondary:
sudo tee /etc/systemd/system/x11vnc.service <<'EOF'
[Unit]
Description=x11vnc VNC server for display :0
After=display-manager.service
Requires=display-manager.service
[Service]
ExecStart=/usr/bin/x11vnc -display :0 -auth /run/user/120/gdm/Xauthority -noshm -noxdamage -noscr -forever -nopw -listen localhost -rfbport 5900
Restart=on-failure
RestartSec=3
[Install]
WantedBy=graphical.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now x11vnc
Note: systemd service uses GDM auth path — update if user session display changes.
Viewer Notes
SetDesktopSize failed: 1 — harmless; physical display ignores client resize requestsEnd of stream immediately — x11vnc not running; rerun the scriptConnection refused — SSH tunnel failed or nothing on port 5900
References
references/ace-linux-2-vnc-live-check-2026-05-05.md — live SSH/VNC verification commands, observed listener state, and safe alternate-port tunnel probe.
