How to Configure an External TURN Server for Jitsi behind NAT

The most important point: an external TURN server should be configured as a fallback for clients that cannot establish a usable WebRTC path because of NAT or restrictive firewalls. It is not a replacement for the Jitsi Videobridge (JVB) in normal multiparty meetings. If your Jitsi server itself is behind NAT, you must still make JVB reachable from the Internet, normally on UDP 10000, or configure the bridge's advertised public address correctly.

For current Jitsi deployments, the cleanest design is usually a publicly reachable coturn host with a DNS name such as turn.example.com, time-limited credentials supplied by Prosody through XEP-0215, and TURN over UDP/TCP plus TURN over TLS for restrictive networks. Jitsi's current TURN documentation explicitly recommends dynamic credentials instead of embedding a permanent username and password in browser configuration. See the official Jitsi TURN setup documentation.

When an external TURN server is the right solution

Use TURN when some participants can open the Jitsi web page but cannot establish reliable media, especially from corporate networks, hotel Wi-Fi, campuses, mobile carriers, VPNs, or other environments that block or heavily filter UDP. TURN is also useful for one-to-one Jitsi calls when peer-to-peer connectivity cannot be established directly.

Do not treat TURN as the first fix for a misconfigured Jitsi Videobridge. The official Jitsi Debian/Ubuntu guide says that when the server is behind NAT, the router must forward the required ports and the bridge may need an explicit local-to-public address mapping. By default, the important Jitsi-facing ports are TCP 443 and UDP 10000. Review the current Jitsi self-hosting guide for Debian/Ubuntu before adding TURN.

Step 1: Prepare a public TURN host and DNS

Die einfachste Topologie besteht aus einer separaten VM oder einem Server mit einer öffentlichen IP-Adresse. Erstellen Sie einen A- oder AAAA-Eintrag, der turn.example.comauf diesen Host verweist. Ein dedizierter Hostname ist besonders nützlich, wenn Sie später TURN over TLS anbieten, da das Zertifikat mit dem Hostnamen der Clients übereinstimmen muss.

Befindet sich der TURN-Host selbst hinter einem NAT-Router, benötigt coturn die öffentliche Adresse, die er bekanntgeben soll. Coturn unterstützt eine external-ipZuordnung, einschließlich öffentlicher/privater Paare wie beispielsweise external-ip=203.0.113.10/192.168.1.10. In der Dokumentation wird außerdem darauf hingewiesen, dass Relay-Ports durch NAT hindurch konsistent zugeordnet werden müssen. Siehe die offizielle coturn-Beispielkonfiguration .

Schritt 2: Installieren Sie coturn

Installieren Sie coturn auf einem unterstützten Debian- oder Ubuntu-System aus dem Distributions-Repository:

sudo apt update
sudo apt install coturn

Die Paketversionen variieren je nach Betriebssystemversion. Kopieren Sie daher keine Versionsnummer von einem Screenshot oder einem anderen Server. Überprüfen Sie nach der Installation, ob die Diensteinheit vorhanden ist und das Paket installiert wurde turnserver.

Schritt 3: Konfigurieren Sie coturn für die Authentifizierung mit gemeinsamem Geheimnis.

Für Jitsi wird in einer praktischen Produktionsumgebung der Shared-Secret-Mechanismus von coturn verwendet, damit Prosody temporäre TURN-Zugangsdaten generieren kann. Verwenden Sie auf beiden Seiten dasselbe Geheimnis. Ein minimaler Ausgangspunkt sieht folgendermaßen aus:

listening-port=3478
tls-listening-port=5349
realm=turn.example.com

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_A_LONG_RANDOM_SECRET

min-port=49160
max-port=49200

no-multicast-peers
no-cli

Befindet sich der TURN-Host hinter einem NAT-Router, fügen Sie die entsprechende external-ipZuordnung hinzu. Wenn Sie TURN über TLS aktivieren, konfigurieren Sie die entsprechenden Einstellungen certmit pkeyeinem vertrauenswürdigen Zertifikat turn.example.com. Die offizielle coturn-Container-Dokumentation erklärt, dass TURN einen Relay-Port-Bereich für Medien verwendet und dass dieser Bereich mit den Parametern `--relay-port-area` min-portund `--relay-port-area` eingeschränkt werden kann max-port. Weitere Informationen zum Relay-Port-Verhalten finden Sie in der offiziellen coturn-Docker-Dokumentation .

Schritt 4: Öffnen Sie die Listener- und Relay-Ports.

Ein häufiger Fehler ist, dass nur die Ports 3478 oder 5349 geöffnet werden, während der Relay-Bereich vergessen wird. Der Coturn-Listener akzeptiert die anfängliche TURN-Verbindung, aber weitergeleitete Medien verwenden zugewiesene Relay-Ports. Wenn Sie 49160-49200diesen Bereich ausgewählt haben, geben Sie ihn in der Host-Firewall, der Cloud-Sicherheitsgruppe und allen vorgelagerten NAT-Routern frei.

sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 5349/tcp
sudo ufw allow 49160:49200/udp

Für maximale Kompatibilität mit abgesicherten Unternehmensnetzwerken beschreibt der Jitsi-TURN-Leitfaden die Bereitstellung von TURN über TLS auf TCP-Port 443. Dies kann einen dedizierten TURN-Hostnamen und, falls Web-HTTPS dieselbe öffentliche Adresse verwendet, TLS-SNI-Multiplexing erfordern. Verlegen Sie TURN nicht einfach auf Port 443, ohne genau zu wissen, welcher Dienst diesen Port bereits belegt.

Schritt 5: Konfigurieren Sie Jitsi so, dass der externe TURN-Dienst angekündigt wird.

Bei einer aktuellen Jitsi-Paketbereitstellung unter Debian/Ubuntu verwendet Prosody die Methode `coturn.sec`, mod_external_servicesum STUN/TURN-Informationen an Clients zu veröffentlichen. Das Jitsi-eigene Prosody-Beispiel verwendet eine ` external_service_secretcoturn.sec`- external_servicesTabelle mit secret = trueeinem gemeinsamen Geheimnis, das mit dem von `coturn.sec` übereinstimmen muss static-auth-secret.

external_service_secret = "REPLACE_WITH_THE_SAME_LONG_RANDOM_SECRET";

external_services = {
    { type = "stun", host = "turn.example.com", port = 3478 },
    { type = "turn", host = "turn.example.com", port = 3478,
       transport = "udp", secret = true, ttl = 86400, algorithm = "turn" },
    { type = "turns", host = "turn.example.com", port = 5349,
       transport = "tcp", secret = true, ttl = 86400, algorithm = "turn" }
};

Behalten Sie die vorhandenen Module und standortspezifischen Einstellungen in Ihrer von Jitsi generierten Prosody-Datei bei; ersetzen Sie nicht die gesamte Datei durch den obigen Codeausschnitt. Der genaue Dateiname folgt normalerweise Ihrer Bereitstellungsdomäne /etc/prosody/conf.d/. Ein Beispiel für die Jitsi-Konfiguration finden Sie im offiziellen Jitsi-Repository .

Wenn Sie die offizielle Docker-Bereitstellung verwenden, sollten Sie die dokumentierten Umgebungsvariablen nutzen, anstatt die generierten Prosody-Dateien manuell zu bearbeiten. Die aktuelle Docker-Dokumentation beschreibt die Variablen `<variable1>` TURN_CREDENTIALS, TURN_HOST` <variable2> TURN_PORT`, `<variable3> ` und `<variable4> `. Beachten Sie die aktuelle Anleitung zum Selbsthosting von Jitsi Docker, da sich die Standardwerte der Variablen zwischen den Versionen ändern können.TURN_TRANSPORTTURNS_HOSTTURNS_PORT

Schritt 6: Dienste neu starten und überprüfen

Nach der Änderung von coturn starten Sie es neu und überprüfen Sie seinen Status:

sudo systemctl restart coturn
sudo systemctl status coturn
sudo ss -lntup | grep -E '3478|5349'

Nach der Änderung der Prosody-Konfiguration sollten Sie die Syntax überprüfen, sofern Ihr Prosody-Paket eine entsprechende Funktion bereitstellt. Starten Sie anschließend Prosody neu. Je nachdem, welche Änderungen Sie in Jitsi vorgenommen haben, kann auch ein Neustart der entsprechenden Jitsi-Dienste erforderlich sein.

sudo prosodyctl check config
sudo systemctl restart prosody

Ein sauberer coturn-Dienststatus beweist lediglich, dass der Daemon läuft. Er beweist nicht, dass die Anmeldeinformationen übereinstimmen, der Relay-Bereich erreichbar ist oder ein Browser einen Relay-Kandidaten finden kann.

Schritt 7: Testen Sie, ob TURN tatsächlich Medien weiterleiten kann.

Tests im selben LAN reichen nicht aus. Verwenden Sie mindestens einen Client in einem anderen Netzwerk, idealerweise über eine Mobilfunkverbindung oder ein Netzwerk, das UDP-Datenverkehr einschränkt. Suchen Sie in der WebRTC-Diagnose des Browsers nach einem ICE-Kandidaten vom Typ „Relay“ relay. Ein Relay-Kandidat bedeutet, dass der Browser erfolgreich TURN-Zugangsdaten erhalten und eine TURN-Zuweisung erstellt hat.

Beobachten Sie außerdem die coturn-Protokolle, während sich der Testbenutzer anmeldet. Sie sollten authentifizierte Zuweisungen und Relay-Datenverkehr sehen, wenn TURN ausgewählt ist. Falls Authentifizierungsfehler auftreten, vergleichen Sie die coturn-Protokolle static-auth-secretmit dem Prosody- oder Docker-TURN-Credential-Secret. Wenn die Zuweisungen erfolgreich sind, die Medienübertragung aber weiterhin fehlschlägt, überprüfen Sie die Firewall des Relay-Ports und die NAT-Zuordnung.

Erzwingen Sie TURN nicht nur, um die Existenz des Servers nachzuweisen, es sei denn, Sie haben einen triftigen Testgrund. Unter normalen Bedingungen wählt ICE den optimalen Pfad. Eine erfolgreiche Bereitstellung kann daher viele Meetings umfassen, die ohne TURN auskommen.

Schritt 8: Die JVB-NAT-Konfiguration sollte von der TURN-Fehlerbehebung getrennt gehalten werden.

Hier lässt sich der größte Zeitaufwand für die Fehlersuche vermeiden. Ein Jitsi-Server hinter NAT benötigt weiterhin eine korrekt konfigurierte öffentliche Erreichbarkeit der Bridge. Laut der aktuellen Jitsi-Schnellstartanleitung konfiguriert sich die Bridge normalerweise automatisch. Sollten jedoch größere Anfragen fehlschlagen, kann eine statische Zuordnung unter „ ice4j.harvest.mappingin“ hinzugefügt werden /etc/jitsi/videobridge/jvb.conf.

ice4j {
  harvest {
    mapping {
      static-mappings = [
        {
          local-address = "192.168.1.20"
          public-address = "203.0.113.20"
        }
      ]
    }
  }
}

Leiten Sie UDP-Port 10000 vom öffentlichen Netzwerkrand zum JVB-Host weiter und stellen Sie sicher, dass die öffentliche Adresse diejenige ist, die entfernte Clients tatsächlich erreichen können. TURN kann Clients in restriktiven Netzwerken helfen, sollte aber nicht verwendet werden, um eine fehlerhafte JVB-NAT-Zuordnung zu verschleiern.

Checkliste zur schnellen Fehlerbehebung

• Der TURN-Hostname kann nicht aufgelöst werden: DNS-Probleme vor dem Testen von Jitsi beheben.
• 3478/5349 hören lokal, aber nicht remote: Überprüfen Sie die Host-Firewall, die Cloud-Firewall, das Router-NAT und die Provider-Filterung.
• Anmeldeinformationen fehlgeschlagen: Überprüfen Sie, ob das gemeinsame Geheimnis in coturn und der Jitsi/Prosody-Konfiguration identisch ist.
• Relay-Kandidat erscheint, aber Medienverbindung schlägt fehl: Überprüfen Sie, ob der konfigurierte Relay-Port-Bereich durchgängig offen ist.
• Nur Mehrparteienanrufe schlagen fehl: Überprüfen Sie JVB UDP 10000 und JVB Public-Address Advertisement.
• Nur Unternehmensnetzwerke scheitern: TURN over TLS hinzufügen oder überprüfen, oft auf TCP 443, wo angebracht.
• Docker-Änderungen gehen nach einem Neustart verloren: Konfigurieren Sie die unterstützten .envVariablen, anstatt die generierten Dateien innerhalb der Container zu bearbeiten.

So sieht ein korrektes Ergebnis aus

Eine einwandfreie Konfiguration zeichnet sich durch drei beobachtbare Verhaltensweisen aus. Erstens können normale Benutzer die Jitsi Videobridge direkt ohne TURN erreichen, sofern ihre Netzwerke dies zulassen. Zweitens können Benutzer in restriktiven Netzwerken temporäre TURN-Zugangsdaten erhalten und einen relayICE-Kandidaten beziehen. Drittens zeigt coturn authentifizierte Zuweisungen nur bei Bedarf an, anstatt standardmäßig jedes Meeting zu übertragen.

Diese Kombination bietet eine nützliche Ausweichlösung, ohne den TURN-Server zu einem unnötigen Bandbreitenengpass zu machen. Außerdem bleibt die Fehlersuche übersichtlich: JVB-NAT-Probleme bleiben JVB-Probleme, während TURN das spezifischere Problem der WebRTC-Konnektivität löst, wenn direkte Routen blockiert sind.