x11vnc-Wayland-Bridge mit Script-Listener für KDE Plasma unter Wayland

Wie ihr wahrscheinlich bereits festgestellt habt, ist klassisches x11vnc unter Wayland nicht einfach nur eine Frage von "Dienst starten und verbinden". Genau an diesem Punkt setzt diese x11vnc-Wayland-Bridge an.

Der Unterschied zu einfachen VNC-Setups besteht hier nicht nur darin, dass unter Wayland kein normales X11-Framebuffer mehr direkt zur Verfügung steht. Der eigentliche Punkt ist, dass das Bild über das KDE-/Portal-/PipeWire-Setup geholt, in eine rawfb-Datei geschrieben und danach von x11vnc weitergereicht wird. Gleichzeitig müssen Maus und Tastatur wieder sauber auf die ausgewählte Monitorfläche zurückgemappt werden.

Voraussetzungen

- laufende grafische Benutzer-Session
- KDE Plasma unter Wayland
- Python 3
- funktionierendes xdg-desktop-portal-kde- und PipeWire-Setup
- socat für den Listener
- ein VNC-Client für die Verbindung

Teil 1: Schnellstart

Wenn das Setup einfach nur zum Laufen gebracht werden soll, ist der praktische Ablauf im Grunde dieser:

1. Dateien entpacken

VNCBRIDGE-DOWNLOAD

Zuerst den Bridge-Ordner an die Stelle legen, an der er später auch wirklich verwendet werden soll, zum Beispiel:

cd ~/Documents
unzip x11vnc-wayland-bridge.zip -d x11vnc-wayland-bridge
cd x11vnc-wayland-bridge

Wichtig ist dabei nicht nur das Entpacken selbst, sondern dass die Dateien danach unter einem festen Pfad liegen. Die Skripte und die optionale systemd --user-Variante beziehen sich nämlich auf genau diesen Ordner.

2. Abhängigkeiten installieren

Zuerst die benötigten Pakete installieren:

sudo pacman -S x11vnc python-dbus python-gobject gstreamer gst-plugin-pipewire pipewire wireplumber xdg-desktop-portal xdg-desktop-portal-kde socat

Wichtig ist dabei nicht nur x11vnc, sondern auch:

- xdg-desktop-portal-kde für die Freigabe unter KDE Plasma
- pipewire und gst-plugin-pipewire für den Screencast-Transport
- socat für den Listener

3. Im Autostart anlegen

Damit der Listener nach dem Login automatisch bereitsteht, sollte das Startskript über die KDE-Oberfläche in den Autostart aufgenommen werden.

Der praktische Weg ist:

- Systemeinstellungen öffnen
- Autostart aufrufen
- Hinzufügen beziehungsweise Add New öffnen
- Login-Skript beziehungsweise Login Script... wählen
- das Skript start_x11vnc_wayland_listener.sh aus eurem Bridge-Ordner auswählen

Wichtig ist dabei nur, dass wirklich das Listener-Skript in dem Ordner ausgewählt wird, in dem ihr das Setup später auch benutzt.

4. Neu starten oder neu anmelden

Danach die grafische Session einmal neu starten oder sich einmal sauber ab- und wieder anmelden.

Der Grund ist einfach:

- Portal, PipeWire und die Benutzer-Session sollen in einem sauberen Zustand laufen
- der Listener soll über den Autostart direkt mitstarten

5. Verbindung aufbauen

Danach mit einem VNC-Client auf den Host und Port verbinden:

host:5900

Falls LISTEN_HOST oder LISTEN_PORT geändert wurden, gilt natürlich der jeweilige geänderte Port.

6. Portal-Auswahl treffen

Bei der ersten Verbindung öffnet sich der KDE-Freigabedialog. Dort den gewünschten Monitor beziehungsweise die gewünschte Auswahl bestätigen.

Dabei werden intern:

- die Auswahl in pwfb.meta
- und das Restore-Token in pwfb.restore_token

abgelegt.

7. Genießen

Wenn die Auswahl einmal gespeichert ist, kann das Setup später mit derselben Auswahl weiterarbeiten, ohne jedes Mal wieder ganz von vorne anzufangen.

Teil 2: Was das Setup intern macht und wie man es sauber betreibt

1. In den Ordner wechseln und zentrale Variablen kennen

Danach in den Projektordner wechseln:

cd ~/Documents/x11vnc-wayland-bridge

Die zentrale Konfiguration liegt in load-vars.sh. Dort stehen unter anderem:

- STATE_DIR
- RAWFB_PATH
- META_PATH
- TOKEN_FILE
- LISTEN_HOST
- LISTEN_PORT
- die festen Log-Dateien und deren Größenlimit

Der Standardport ist in diesem Setup:

5900

Die Standard-State-Dateien liegen unter:

~/.local/state/x11vnc-wayland-bridge

2. Bei Bedarf den State sauber leeren

Wenn bereits alte Auswahl- oder Token-Dateien existieren und ihr bewusst mit einem sauberen Zustand anfangen wollt, könnt ihr den State vorab leeren:

./start_x11vnc_wayland_ondemand.sh --clear

Dabei werden die Dateien direkt im State-Verzeichnis entfernt, also auch:

- pwfb.meta
- pwfb.restore_token
- die zugehörigen Log-Dateien

Das ist sinnvoll, wenn:

- eine alte Monitorauswahl nicht mehr passt
- die erste Freigabe neu aufgebaut werden soll
- ihr bewusst einen frischen Portal-Dialog erzwingen wollt

3. Listener starten

Wenn die Voraussetzungen stimmen, kann der Listener gestartet werden:

./start_x11vnc_wayland_listener.sh

Optional kann Host und Port auch direkt beim Start überschrieben werden:

LISTEN_HOST=127.0.0.1 LISTEN_PORT=5901 ./start_x11vnc_wayland_listener.sh

Der Listener macht dabei nicht selbst die Wayland-Freigabe, sondern lauscht nur auf eingehende Verbindungen und startet pro echter Verbindung intern denselben On-Demand-Pfad.

4. Was intern bei einer Verbindung passiert

Der eigentliche Vorteil dieses Setups ist nicht nur, dass auf Port 5900 gelauscht wird, sondern wie die Verbindung intern zusammengesetzt wird.

Sobald sich ein VNC-Client verbindet, passiert vereinfacht gesagt Folgendes:

- socat nimmt die Verbindung an
- start_x11vnc_wayland_ondemand.sh --inetd wird gestartet
- wenn pwfb.meta oder pwfb.restore_token fehlen, wird eine neue Portal-Auswahl vorbereitet
- portal_rawfb_bridge.py öffnet den KDE-Screencast über das Portal und PipeWire
- das Bild landet als rawfb in der Laufzeitdatei
- x11vnc liest genau diese rawfb-Datei
- x11vnc_pipeinput.py übersetzt Pointer- und Keysym-Eingaben für Wayland sauber zurück

Der Punkt ist also nicht nur "x11vnc unter Wayland", sondern die komplette Verkettung aus:

- Portal-Auswahl
- PipeWire-Bild
- rawfb
- x11vnc
- Pipeinput-Helper

5. Erste Verbindung und Monitorauswahl

Danach mit dem VNC-Client auf den Host und Port verbinden:

host:5900

Bei der ersten Verbindung gilt:

- wenn noch keine gespeicherte Auswahl vorliegt, öffnet sich automatisch der KDE-Freigabedialog
- die gewählte Auswahl wird in pwfb.meta gespeichert
- das Restore-Token wird in pwfb.restore_token abgelegt

Danach versucht das Setup, die ausgewählten Outputs wieder der aktuellen Geometrie aus xrandr beziehungsweise KDE zuzuordnen.

Zusatzpunkt, der in diesem Projekt wichtig ist:

- die eingehende Verbindung versucht den gewählten Monitor zuerst aufzuwecken
- wenn der Monitor schläft, wartet die Session auf dpms=On

Das ist praktisch, weil nicht einfach blind ein alter Zustand angenommen wird, sondern die echte aktuelle Monitorgeometrie erneut aufgelöst wird.

6. Logs und Fehleranalyse

Für die Praxis ist hilfreich, dass die Komponenten getrennt geloggt werden. Das Setup schreibt feste Log-Dateien mit Größenlimit, damit nicht alles in einer Datei verschwimmt.

Nutzbar sind zum Beispiel:

tail -f ~/.local/state/x11vnc-wayland-bridge/listener.log
tail -f ~/.local/state/x11vnc-wayland-bridge/inetd.log
tail -f ~/.local/state/x11vnc-wayland-bridge/bridge.log
tail -f ~/.local/state/x11vnc-wayland-bridge/pipeinput.log

Gerade bei Wayland ist das wichtig, weil Probleme ganz unterschiedlich entstehen können:

- Listener nimmt keine Verbindung an
- Portal-Auswahl oder Restore-Token fehlen
- PipeWire liefert keinen Stream
- Monitor-Geometrie passt nicht
- Pointer- oder Tastatur-Mapping ist nicht stimmig

7. Auswahl bei Bedarf neu aufbauen

Wenn die gespeicherte Auswahl zwar prinzipiell existiert, aber bewusst neu geschrieben werden soll, ist --reseed der saubere Weg:

./start_x11vnc_wayland_ondemand.sh --reseed

Dabei wird die alte Auswahl verworfen und der Portal-Teil neu vorbereitet. Das ist sinnvoll, wenn:

- Monitore getauscht wurden
- die alte Zuordnung nicht mehr zur aktuellen Geometrie passt
- ein neuer Restore-Token erzeugt werden soll

8. Ergebnis

Wenn alles richtig vorbereitet ist, hat dieses Setup genau den Vorteil, für den es gedacht ist:

- x11vnc lässt sich trotz Wayland weiterverwenden
- die Bildfreigabe läuft über das KDE-/Portal-/PipeWire-Setup
- die Monitorauswahl bleibt über State-Dateien und Restore-Token erhalten
- Maus und Tastatur werden über den Pipeinput-Helper wieder sauber auf die ausgewählte Fläche gemappt
- Verbindungen können über einen einfachen Script-Listener angenommen werden

Das ist kein minimalistisches Ein-Datei-Setup, sondern bewusst eine kleine Brücke aus mehreren Komponenten. Gerade für KDE Plasma unter Wayland kann genau dieser Aufbau aber sinnvoll sein, wenn x11vnc weitergenutzt werden soll, ohne auf ein klassisches X11-Setup zurückzufallen.