vnc-wayland mit Script-Listener für KDE Plasma unter Wayland

Wie ihr wahrscheinlich bereits festgestellt habt, ist Remote-Desktop unter Wayland nicht einfach nur eine Frage von „Dienst starten und verbinden“. Genau an diesem Punkt setzt das vnc-wayland-Setup an.

Der Unterschied zu klassischen Setups besteht hier nicht nur darin, dass unter Wayland kein normales X11-Framebuffer mehr direkt zur Verfügung steht. Der eigentliche Punkt ist, dass krfb selbst die Bildaufnahme und die Eingabebehandlung über das KDE-Portal und PipeWire erledigt – ohne rawfb-Datei, ohne separaten x11vnc-Prozess. Einzige übrige Aufgabe ist ein kleiner Listener, der die VNC-Verbindung annimmt, ein schlafendes Display aufweckt und die Verbindung an den internen krfb-Port weiterleitet.

Voraussetzungen

- laufende grafische Benutzer-Session
- KDE Plasma unter Wayland
- systemd --user für die kurzlebige krfb-Scope
- 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. Projekt holen

vnc-wayland auf GitHub

Zuerst das Projekt an die Stelle legen, an der es später auch wirklich verwendet werden soll, zum Beispiel:

cd ~/Documents git clone https://github.com/urpid/vnc-wayland.git cd vnc-wayland

Danach die beiden Startskripte ausführbar machen:

chmod +x start_krfb_wayland_ondemand.sh chmod +x start_krfb_wayland_listener.sh

Wichtig ist dabei nicht nur das Holen der Dateien, sondern dass sie 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 --needed krfb qt6-tools pipewire wireplumber xdg-desktop-portal xdg-desktop-portal-kde socat iproute2 procps-ng systemd

Wichtig ist dabei nicht nur pipewire und xdg-desktop-portal-kde für die Freigabe unter KDE Plasma, sondern auch socat für den Listener.

Wichtig: krfb selbst nicht über diese Zeile installieren. Seit Version 26.07 bindet das Haupt-Binary von krfb den VNC-Port nicht mehr: RfbServer::start() ruft listen nur auf, wenn das interne passwordSet-Flag gesetzt ist, das normales krfb nie setzt (nur krfb-virtualmonitor). Der Port bleibt daher zu und jede VNC-Verbindung wartet 60 Sekunden, bevor sie fehlschlägt. Ursache: krfb-Commit 842c91e (April 2026, BUG 497071), auf master nicht behoben.

Daher pinnt das Projekt krfb 26.04.3, die letzte Version ohne den Bug. Das gepinnte Paket liegt im Repository unter packages/:

sudo pacman -U packages/krfb-26.04.3-1-x86_64.pkg.tar.zst pkill -x krfb

Damit pacman -Syu krfb nicht versehentlich upgradet, IgnorePkg = krfb in /etc/pacman.conf eintragen.

Beachte: IgnorePkg blockt nur pacman -Syu, nicht explizite pacman -S krfb-Aufrufe. Die Paket-Zeile oben ist daher ab jetzt der einzige sichere Weg, krfb zu installieren.

Gesundheit prüfen:

pacman -Q krfb    # => krfb 26.04.3-1 ss -ltnp 'sport = :5901'   # nach krfb-Start: LISTEN-Eintrag muss da sein

Sobald upstream den Bug behoben hat: IgnorePkg = krfb in /etc/pacman.conf entfernen und krfb mit pacman -Syu aktualisieren.

3. krfb einmalig einrichten

Bevor der Listener krfb automatisch starten kann, muss krfb einmal konfiguriert werden:

./start_krfb_wayland_ondemand.sh --setup

Der Setup-Befehl löscht zuerst den bisherigen Portal-Restore-Token von krfb. Setup und die automatischen Starts laufen mit der Portal-Anwendungsidentität org.kde.krfb, dadurch erzeugt das KDE-Portal einen neuen Token, den krfb bei seinen automatischen Neustarts wiederverwendet.

Das aktuelle KDE-Portal bietet für die Remote-Desktop-Sitzung von krfb keine Monitorauswahl. Bei mehreren Monitoren überträgt krfb die gesamte Arbeitsfläche.

In krfb:

- Freigabe der Arbeitsfläche aktivieren
- Steuerung durch Maus und Tastatur erlauben

Danach das krfb-Fenster mit X schließen. Im Setup-Modus beendet das den Prozess vollständig. Wenn der Listener später krfb eigenständig startet, läuft es ohne Hauptfenster im Tray.

4. 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_krfb_wayland_listener.sh aus eurem Projektordner 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.

5. 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

Damit die Firewall passt: krfb bindet seinen internen Port an alle Netzwerkadressen, daher muss Port 5901 von außen gesperrt bleiben; nur der Wake-Listener auf 5900 soll erreichbar sein. Falls ufw aktiv ist:

sudo ufw allow 5900/tcp sudo ufw deny 5901/tcp

6. 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.

Bei der ersten Verbindung wird das VNC-Passwort der krfb-Sitzung abgefragt. Der Portal-Teil läuft im Hintergrund: das beim Setup erzeugte Restore-Token wird wiederverwendet, die Freigabe wird also nicht jedes Mal von vorne aufgebaut. Wie erwähnt bietet das aktuelle Portal keine Monitorauswahl – bei mehreren Monitoren wird die gesamte Arbeitsfläche übertragen.

7. Genießen

Wenn krfb einmal mit einem gültigen Portal-Token gelaufen ist, kann das Setup später mit derselben Konfiguration weiterarbeiten, ohne jedes Mal wieder ganz von vorne anzufangen. Jede neue VNC-Verbindung wird vom Listener angenommen, das Display wird bei Bedarf aufgeweckt und krfb wird neu gestartet, wenn eine frische PipeWire-Sitzung nötig ist.

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/vnc-wayland

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

- LISTEN_HOST (Standard 0.0.0.0)
- LISTEN_PORT (Standard 5900)
- KRFB_HOST (Standard 127.0.0.1)
- KRFB_PORT (Standard 5901)
- KRFB_UNIT (Standard krfb-wayland-server.service)
- KRFB_START_TIMEOUT (Standard 60)
- POLL_INTERVAL und WAKE_RETRY_EVERY für die Wake-Schleife

Der öffentliche Listener-Port in diesem Setup ist:

5900

Der interne krfb-Port, an den der Listener weiterleitet, ist:

5901

Es gibt kein separates State-Verzeichnis mit rawfb-Dateien. Der einzige wichtige Zustand ist das Portal-Restore-Token, das krfb selbst in seiner eigenen Konfiguration ablegt (krfbstaterc, Gruppe XdgPortal, Schlüssel RestoreToken).

2. Bei Bedarf das Setup sauber zurücksetzen

Wenn das Portal-Token veraltet ist, krfb versehentlich geupgradet wurde oder ihr bewusst mit einem sauberen Zustand anfangen wollt, den Setup einmal ausführen:

./start_krfb_wayland_ondemand.sh --setup

Dadurch wird ein laufendes krfb gestoppt, Port 5901 neu konfiguriert, das Portal-Restore-Token gelöscht, der KWin-Close-Watcher geladen und krfb mit Dialog gestartet.

Wenn krfb versehentlich geupgradet wurde, zuerst das gepinnte Paket neu installieren:

sudo pacman -U packages/krfb-26.04.3-1-x86_64.pkg.tar.zst pkill -x krfb

Das ist sinnvoll, wenn:

- das alte Portal-Token nicht mehr passt
- die erste Freigabe neu aufgebaut werden soll
- krfb nach einem Upgrade auf der falschen Version ist

3. Listener starten

Wenn die Voraussetzungen stimmen, kann der Listener gestartet werden:

./start_krfb_wayland_listener.sh

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

LISTEN_HOST=127.0.0.1 LISTEN_PORT=5902 ./start_krfb_wayland_listener.sh

Der interne krfb-Port bleibt dabei 5901. 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. Jede angenommene Verbindung läuft krfb in einer kurzlebigen systemd --user-Scope mit der Portal-Anwendungsidentität org.kde.krfb, damit das Portal immer dieselbe Anwendung sieht.

Als Alternative liefert das Projekt eine systemd --user-Variante mit krfb-wayland.socket auf Port 5900, krfb-wayland-server.service und der pro Verbindung krfb-wayland@.service. Die Units verlinken das Projekt über den festen Pfad ~/.local/lib/krfb-wayland, damit das Repository selbst an beliebiger Stelle liegen kann:

mkdir -p ~/.local/lib ~/.config/systemd/user ln -sfnT "$PWD" ~/.local/lib/krfb-wayland ln -sf ~/.local/lib/krfb-wayland/krfb-wayland-server.service ~/.config/systemd/user/krfb-wayland-server.service ln -sf ~/.local/lib/krfb-wayland/krfb-wayland.socket ~/.config/systemd/user/krfb-wayland.socket ln -sf ~/.local/lib/krfb-wayland/krfb-wayland@.service ~/.config/systemd/user/krfb-wayland@.service systemctl --user daemon-reload systemctl --user enable --now krfb-wayland.socket

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
- das Skript sendet immer einen Wake-Impuls gegen eine mögliche Abdunkelung
- war mindestens ein aktivierter Monitor im DPMS-Standby, wartet das Skript, bis alle aktivierten Monitore DPMS On melden
- nach einem Standby startet das Skript krfb neu, damit eine frische PipeWire-Sitzung entsteht
- vor einem Neustart beendet das Skript krfb sauber über D-Bus, damit das aktuelle Portal-Restore-Token gespeichert wird; nur wenn das nicht funktioniert, folgen TERM und danach KILL
- war kein Monitor im Standby, startet das Skript krfb nur, wenn sein interner Port nicht verfügbar ist
- socat leitet die unveränderte VNC-Verbindung an krfb auf 127.0.0.1:5901 weiter
- Bildschirmaufnahme sowie Maus- und Tastatureingaben laufen vollständig über krfb und das KDE-Portal

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

- Portal-Restore-Token
- PipeWire-Screencast
- krfb
- VNC auf dem internen Port
- Listener mit Wake-Behandlung

5. Erste Verbindung und Monitor-Verhalten

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

host:5900

Bei der ersten Verbindung gilt:

- das VNC-Passwort der krfb-Sitzung wird abgefragt
- der Portal-Teil läuft im Hintergrund mit dem gespeicherten Restore-Token
- das aktuelle Portal bietet keine Monitorauswahl; bei mehreren Monitoren wird die gesamte Arbeitsfläche übertragen

Zusatzpunkt, der in diesem Projekt wichtig ist:

- die eingehende Verbindung versucht das Display zuerst aufzuwecken
- wenn ein Monitor schläft, wartet die Verbindung auf DPMS On
- die Wake-Prüfung gilt für alle verbundenen und aktivierten DRM-Ausgänge

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

6. Logs und Fehleranalyse

Für die Praxis ist hilfreich, dass die Komponenten getrennt geprüft werden. Wenn der Listener manuell gestartet wird, schreibt er direkt ins Terminal. Jede angenommene VNC-Verbindung wird mit dem Zeitpunkt, der Client-Adresse, dem Startmodus und dem Zustand aller DRM-Ausgänge vor dem Wake-Befehl protokolliert.

Nutzbar sind zum Beispiel:

pgrep -af start_krfb_wayland_listener.sh pgrep -a -x krfb ss -ltnp 'sport = :5900' ss -ltnp 'sport = :5901'

Wenn der Listener über den Plasma-Autostart läuft, stehen diese Einträge im Journal:

journalctl --user -u Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein.'

Für die systemd-Variante:

systemctl --user status krfb-wayland.socket systemctl --user status krfb-wayland-server.service journalctl --user -u 'krfb-wayland@*'

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

- Listener nimmt keine Verbindung an
- Port 5900 ist bereits von einem anderen Prozess belegt
- krfb öffnet Port 5901 nicht (falsche Version – Pin prüfen)
- Portal-Restore-Token fehlt oder ist veraltet
- Display nach dem Wake-Versuch noch immer schlafend
- Firewall blockiert die Verbindung

7. Setup bei Bedarf neu aufbauen

Wenn das gespeicherte Portal-Token zwar prinzipiell existiert, aber bewusst neu geschrieben werden soll, ist erneut --setup der saubere Weg:

./start_krfb_wayland_ondemand.sh --setup

Dadurch wird das alte Restore-Token verworfen, der Port neu konfiguriert und der Portal-Teil wieder vorbereitet. Das ist sinnvoll, wenn:

- Monitore getauscht wurden
- krfb versehentlich geupgradet wurde
- 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:

- krfb lässt sich trotz Wayland verwenden, mit Bildaufnahme und Eingaben vollständig über das KDE-Portal
- der Pin auf 26.04.3 hält den VNC-Port zuverlässig offen
- der Wake-Listener nimmt Verbindungen an und weckt schlafende Displays auf, bevor er an krfb weiterleitet
- keine rawfb-Datei, kein x11vnc und kein Pipeinput-Helper – die ganze Kette ist kürzer und näher am Desktop selbst

Das ist kein minimalistisches Ein-Datei-Setup, sondern bewusst ein kleines Projekt aus Listener, Setup-Skript und dem gepinnten krfb-Paket. Gerade für KDE Plasma unter Wayland kann genau dieser Aufbau aber sinnvoll sein, wenn das eigene Remote-Framework des Desktops weitergenutzt werden soll, ohne auf ein klassisches X11-Setup zurückzufallen.