So richten Sie einen Matrix Coturn TURN/STUN-Server für Audio- und Videoanrufe ein

Eine aktuelle Änderung bei Matrix Call betrifft die Erkennung, jedoch nicht die TURN-Zugangsdaten oder Ports von Coturn. In seinem Update vom 21. August 2026 berichtete Matrix.org, dass Element Call 0.24 die Erkennung von MatrixRTC-Transporten über die /.well-known/matrix/clientKonfigurationsdatei des Homeservers eingestellt hat. Standalone-Installationen von Element Call sollten den MatrixRTC-Transportendpunkt unterstützen; Element Web/Desktop und Element X verwenden weiterhin die alte Erkennungsmethode als Fallback, während Clients umstellen. Dies ist unabhängig von der klassischen TURN-Konfiguration.

Diese Anleitung konfiguriert Coturn für den TURN-Dienst von Synapse, der Clients mit herkömmlichen WebRTC-Anrufen temporäre ICE-Zugangsdaten bereitstellt. Aktuelle Element Call- und MatrixRTC-Gruppenanrufe nutzen eine LiveKit Selective Forwarding Unit (SFU) und einen MatrixRTC-Autorisierungsdienst. Coturn allein ersetzt diese Komponenten nicht. Wenn Sie Element Call selbst hosten möchten, verwenden Sie den im offiziellen Element Call-Leitfaden beschriebenen LiveKit-Pfad. Fügen Sie Coturn nur hinzu, wenn Ihre Medienarchitektur einen separaten TURN-Dienst erfordert.

Wählen Sie zuerst den richtigen Aufrufpfad.

Für MatrixRTC auf Synapse verwendet und aktiviert die aktuelle Anleitung zum Selbsthosting von Element Call matrix_rtc.transportsdie Homeserver-Transportregistrierung über das dokumentierte experimentelle Feature-Flag. Laut der Matrix.org-Mitteilung von 2026 ist diese Änderung der Erkennung hauptsächlich für eigenständige Element Call-Bereitstellungen relevant; andere Administratoren könnten den Endpunkt vorbereiten, während unterstützte Clients einen Fallback beibehalten. Prüfen Sie die Anleitung für die Clients und die Synapse-Version, die Sie verwenden.

Was Coturn tut

STUN ermöglicht es einem WebRTC-Client, die öffentliche Netzwerkadresse zu ermitteln, die er bekanntgeben kann. TURN leitet Medien weiter, wenn zwei Clients keine direkte Verbindung über ihre Router oder Firewalls herstellen können. Coturn implementiert beide Dienste. Ohne erreichbaren Relay-Server kann ein Anruf zwar klingeln, aber im Status „Verbinden“ verharren, wenn sich die Teilnehmer in restriktiven oder nicht verbundenen Netzwerken befinden.

Ein TURN-Server benötigt eine öffentliche IP-Adresse oder ein NAT-Gateway mit einer öffentlichen IP-Adresse und korrekten Weiterleitungsregeln. Ein rein privater Server kann nicht als Internet-Relay für entfernte Matrix-Benutzer fungieren. Bei einer kleinen Synapse-Installation können Sie Coturn auf dem Heimserver installieren oder einen separaten öffentlichen Host verwenden. Ein separater Host bietet klarere Firewall-Grenzen und unabhängige Skalierbarkeit; eine Installation auf demselben Host ist einfacher, erfordert jedoch sorgfältig konfigurierte Firewall-Regeln, um zu verhindern, dass private Dienste über das Relay offengelegt werden.

1. Installieren Sie Coturn und bereiten Sie ein gemeinsames Geheimnis vor.

Unter Debian oder Ubuntu installieren Sie das Distributionspaket:

sudo apt update
sudo apt install coturn

Das Paket stellt einen systemd-Dienst bereit, und die Hauptkonfigurationsdatei befindet sich üblicherweise unter /etc/turnserver.conf. Andere Distributionen verwenden ihren eigenen Paketnamen, ihre eigene Dienstverwaltung und ihren eigenen Konfigurationspfad.

Generieren Sie ein starkes, privates Geheimnis. Zum Beispiel:

openssl rand -hex 32

Verwenden Sie dasselbe Geheimnis in Coturn und Synapse. Behandeln Sie es wie ein Passwort: Verwenden Sie keine Beispielwerte aus der Dokumentation, übertragen Sie diese nicht in ein öffentliches Repository und geben Sie sie nicht in einem öffentlichen Fehlerbericht an. Wenn Ihre Synapse-Version dies unterstützt turn_shared_secret_path, können Sie das Geheimnis in einer geschützten Datei anstatt direkt in YAML speichern. Diese Einstellung wurde in Synapse Version 1.116.0 eingeführt; überprüfen Sie Ihre installierte Version, bevor Sie sie verwenden.

2. Konfigurieren Sie Coturn für die authentifizierte Weiterleitung

Bearbeiten /etc/turnserver.confund konfigurieren Sie den Dienstnamen und die Authentifizierungsmethode für den gemeinsamen Schlüssel. Ersetzen Sie die Platzhalter für Domäne und Schlüssel:

listening-port=3478
tls-listening-port=5349

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_THE_SAME_RANDOM_SECRET
realm=turn.example.org

min-port=49152
max-port=65535

no-tcp-relay
no-multicast-peers
user-quota=12
total-quota=1200

syslog

use-auth-secretAktiviert den zeitlich begrenzten TURN-Authentifizierungsmechanismus, den Synapse verwendet. Konfigurieren Sie keinen anonymen Zugriff und stellen Sie kein offenes Relay bereit. Die oben genannten Kontingentwerte dienen als Ausgangspunkt und basieren auf den Synapse-Richtlinien für CoTURN. Passen Sie sie an Ihre erwartete Benutzeranzahl und Kapazität an. no-tcp-relayVerhindert, dass Clients das Relay auffordern, Verbindungen zu beliebigen TCP-Zielen herzustellen; dies bedeutet jedoch nicht, dass Sie TCP als Client-zu-TURN-Transport deaktivieren müssen.

TURN kann als Relay zu internen oder sensiblen Netzwerkadressen missbraucht werden. Wenden Sie die vollständigen Adressbereiche für gesperrte Peers aus dem aktuellen Synapse-Coturn-Sicherheitsbeispiel an, einschließlich der für Ihre IPv4- und IPv6-Netzwerke relevanten Bereiche. Überprüfen Sie die Regeln, bevor Sie sie kopieren, falls Benutzer berechtigterweise private Netzwerk-Peers erreichen müssen. Halten Sie Coturn außerdem auf dem neuesten Stand und überwachen Sie dessen Protokolle und Kontingente.

Legen Sie die öffentliche Adresse fest, wenn sich Coturn hinter einem NAT befindet.

Befindet sich der TURN-Host hinter einem Router, fügen Sie seine öffentliche Adresse zur Konfiguration hinzu, damit Coturn eine erreichbare Relay-Adresse bekannt gibt:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Ersetzen Sie die Beispielwerte durch die tatsächlichen Adressen. Die Listening-Adresse ist optional, falls Coturn bereits an die richtige Schnittstelle gebunden ist. Leiten Sie den TURN-Listener und den Relay-Bereich vom Router an diesen Server weiter. Eine nicht übereinstimmende externe Adresse ist eine häufige Ursache dafür, dass Anrufe im selben LAN funktionieren, aber zwischen verschiedenen Netzwerken fehlschlagen.

3. Öffnen Sie die Listener- und Relay-Ports.

Erlauben Sie die Ports, die Ihrer Coturn-Konfiguration entsprechen, sowohl in der Host-Firewall als auch in jeder Cloud-Firewall oder jedem Router:

• TCP und UDP 3478 für den üblichen TURN-Listener.
• Der Standard-Relay-Bereich für UDP 49152–65535 wird oben angezeigt. Wenn Sie einen kleineren Bereich wählen, konfigurieren Sie denselben Bereich in Coturn und der Firewall.
• TCP 5349 für TURN over TLS und UDP 5349 nur dann, wenn Sie DTLS aktivieren und anbieten möchten.

Für UFW kann ein grundlegender UDP/TCP-Listener und ein UDP-Relay-Regelsatz wie folgt aussehen:

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp

Fügen Sie die 5349-Regeln nur dann hinzu, wenn der entsprechende TLS- oder DTLS-Listener konfiguriert und bekanntgegeben wurde. Überprüfen Sie auch die Sicherheitsgruppe Ihres Providers; eine UFW-Regel auf Hostebene kann eine blockierte Cloud-Ingress-Regel nicht außer Kraft setzen. Veröffentlichen Sie die administrative Steuerungsschnittstelle von Coturn nicht im Internet.

4. Konfigurieren Sie Synapse so, dass es Coturn-Anmeldeinformationen ausstellt.

Fügen Sie die folgenden TURN-Einstellungen zur aktiven Synapse-Konfiguration hinzu, üblicherweise homeserver.yaml. Der Hostname muss öffentlich zum TURN-Host aufgelöst werden:

turn_uris:
  - "turn:turn.example.org:3478?transport=udp"
  - "turn:turn.example.org:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_THE_SAME_RANDOM_SECRET"
turn_user_lifetime: 1h
turn_allow_guests: true

Die ersten beiden URIs bewerben normale TURN-Transporte auf Port 3478. Wenn TLS konfiguriert und getestet ist, können Sie auch eine URI wie beispielsweise „/“ bewerben turns:turn.example.org:5349?transport=tcp. Bewerben Sie keine URI, solange Zertifikat, Listener, Firewall und Clientkompatibilität nicht gewährleistet sind. Das TLS-Zertifikat und der private Schlüssel von Coturn werden in der Konfiguration mit „ /“ und turns:„/“ festgelegt .certpkey

Die Einstellungen richten sich turn_allow_guestsnach Ihren Zimmer- und Gästerichtlinien. Durch die Aktivierung können nicht authentifizierte Gäste TURN-Zugangsdaten anfordern, was zwar für Gästeanrufe erforderlich sein kann, aber das Missbrauchsrisiko erhöht. Die Deaktivierung kann die Zuverlässigkeit von Anrufen für Gäste beeinträchtigen. Nutzen Sie in jedem Fall Überwachung und Kontingente.

Starten Sie Coturn und Synapse nach der Änderung ihrer Dateien neu:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Verwenden Sie Ihren tatsächlichen Synapse-Systemd-Unit-Namen, falls dieser abweicht. Laden Sie betroffene Clients neu oder starten Sie sie neu; die TURN-Einstellungen von Synapse werden regelmäßig aktualisiert, daher ist eine Änderung möglicherweise nicht sofort sichtbar.

Sollte TURN over TLS aktiviert werden?

Beginnen Sie mit UDP/TCP TURN auf Port 3478 und prüfen Sie, ob ein Relay-Kandidat funktioniert. Fügen Sie TURN über TLS nur dann hinzu, wenn die Netzwerke Ihrer Benutzer dies erfordern, beispielsweise Unternehmensfirewalls, die TLS-ähnlichen Datenverkehr zulassen, aber normales UDP blockieren. TLS erweitert die Konnektivität, erfordert jedoch zusätzliche Zertifikatserneuerung, einen weiteren Listener und Client-Kompatibilitätsprüfungen.

Es gibt eine wichtige Einschränkung bezüglich Matrix: Die aktuelle Synapse Coturn-Anleitung warnt davor, dass TLS/DTLS mit Let's Encrypt-Zertifikaten nicht mit Matrix-Clients funktioniert, die die WebRTC-Bibliothek von Chromium verwenden, einschließlich Element für Android und iOS (wie in der Anleitung beschrieben). Überprüfen Sie die Kompatibilität Ihrer Clientversionen, bevor Sie eine TLS-URI veröffentlichen. Die gleiche Anleitung empfiehlt, zuerst den Basisdienst einzurichten und TLS/DTLS anschließend hinzuzufügen.

5. Überprüfen Sie die Anmeldeinformationen und testen Sie den Test von einem externen Netzwerk aus.

Prüfen Sie zunächst, ob Coturn ausgeführt wird, und überprüfen Sie dessen Protokolle:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Überprüfen Sie anschließend in einer authentifizierten Matrix-Client-Sitzung die Anfrage an den aktuellen Client-Server-API-Endpunkt von Synapse /_matrix/client/v3/voip/turnServer. Eine erfolgreiche Antwort sollte Benutzername, Passwort, Gültigkeitsdauer (TTL) und die von Ihnen konfigurierten TURN-URIs enthalten. Geben Sie diese Antwort nicht öffentlich weiter; die Anmeldeinformationen sind temporäre Zugriffstoken für Ihr Relay.

Verwenden Sie das offizielle WebRTC Trickle ICE-Beispiel, um mit einem von Synapse zurückgegebenen Benutzernamen und Passwort zu testen. Fügen Sie Ihre TURN-URI und Ihre Anmeldeinformationen hinzu, führen Sie den ICE-Erfassungstest aus und suchen Sie nach einem Kandidaten vom Typ „ relayserver-reflexiv“. Ein Server, der lediglich auf STUN antwortet, kann zwar einen solchen Kandidaten anzeigen, aber dennoch keine Medien übertragen. Testen Sie die Verbindung über eine Mobilfunkverbindung oder ein Netzwerk außerhalb Ihres LANs und stellen Sie anschließend einen tatsächlichen Anruf zwischen Teilnehmern in verschiedenen Netzwerken her.

Häufige Fehler diagnostizieren

• Es werden keine TURN-Anmeldeinformationen angezeigt: Überprüfen Sie, ob Synapse die richtige Konfiguration geladen hat, erfolgreich neu gestartet wurde und das gemeinsame Geheimnis gesetzt ist. Untersuchen Sie die Anfrageantwort auf /voip/turnServer.
• Anmeldeinformationen werden angezeigt, aber es werden keine Relay-Kandidatenformulare erstellt: Überprüfen Sie TCP/UDP 3478, den beworbenen Hostnamen, die Übereinstimmung des geheimen Schlüssels, Coturn-Protokolle und den UDP-Relay-Bereich durch jede Firewall.
• Anrufe funktionieren in einem LAN, schlagen aber netzwerkübergreifend fehl: Überprüfung external-ip, Portweiterleitung und Rückroute. Coturn muss die öffentliche Adresse bekanntgeben, die Clients erreichen können.
• Anrufe werden nur dann verbunden, wenn TLS deaktiviert ist: Bitte überprüfen Sie die Zertifikatskette, den TLS-Listener, die angegebene turns:URI und die clientseitige Kompatibilität.
• Herkömmliche Anrufe funktionieren, Element Call jedoch nicht: Überprüfen Sie die MatrixRTC/LiveKit-Transportkonfiguration separat. Ein erfolgreicher Coturn-Test verifiziert weder den LiveKit SFU- noch den MatrixRTC-Autorisierungsdienst.

Bei Browserclients kann die WebRTC-Diagnose des Browsers anzeigen, ob die Medien einen Relay-Kandidaten ausgewählt haben. Überprüfen Sie bei MatrixRTC, ob Synapse den Transportendpunkt veröffentlicht und ob die LiveKit-WebSocket- und Autorisierungsrouten erreichbar sind. Testen Sie sowohl den aktuellen Endpunkt als auch alle dokumentierten Discovery-Fallback-Optionen, die von den unterstützten Clients benötigt werden.

Konfigurationsreferenzen

• Synapse: Konfigurieren eines TURN-Servers
• Synapse: Coturn-Installation, Sicherheit, NAT und TLS-Konfiguration
• Synapse-Konfigurationsreferenz für TURN und MatrixRTC
• Das offizielle turnserver.conf-Beispiel von Coturn
• Element Call: MatrixRTC-Selbsthosting-Leitfaden
• LiveKit-Bereitstellung und TURN-Konfiguration
• Matrix.org-Update zur Element Call 0.24-Transporterkennung
• Matrix Client-Server API-Spezifikation, einschließlich des TURN-Anmeldeinformationsendpunkts