Hoe configureert u een Matrix Coturn TURN/STUN-server voor audio- en videogesprekken?

Een recente wijziging in Matrix Call heeft gevolgen voor de ontdekking, maar niet voor de TURN-referenties of -poorten van Coturn. In de update van 21 augustus 2026 meldde Matrix.org dat Element Call 0.24 de ontdekking van MatrixRTC-transporten via het /.well-known/matrix/clientconfiguratiebestand van de homeserver heeft afgeschaft. Standalone Element Call-implementaties zouden het MatrixRTC-transporteindpunt moeten ondersteunen; Element Web/Desktop en Element X behielden de oude ontdekkingsmethode als terugvaloptie tijdens de overgangsperiode voor clients. Dit staat los van de klassieke TURN-configuratie.

Deze handleiding configureert Coturn voor de TURN-service van Synapse, die tijdelijke ICE-referenties levert aan clients die gebruikmaken van traditionele WebRTC-gesprekken. De huidige Element Call- en MatrixRTC-groepsgesprekken maken gebruik van een LiveKit Selective Forwarding Unit (SFU) en een MatrixRTC-autorisatieservice. Coturn vervangt deze componenten niet. Als u Element Call zelf wilt hosten, volg dan de LiveKit-route die wordt beschreven in de officiële Element Call-handleiding; voeg Coturn alleen toe als uw gekozen media-architectuur een aparte TURN-service vereist.

Kies eerst het juiste aanroeppad.

Voor MatrixRTC op Synapse maakt de huidige handleiding voor zelfhosting van Element Call gebruik van matrix_rtc.transportsen activeert het transportregister van de homeserver via de gedocumenteerde experimentele functievlag. De Matrix.org-melding van 2026 stelt dat deze wijziging in de detectie vooral van belang is voor standalone Element Call-implementaties; andere beheerders kunnen het eindpunt voorbereiden, terwijl ondersteunde clients een fallback behouden. Raadpleeg de handleiding voor de clients en de Synapse-release die u daadwerkelijk gebruikt.

Wat Coturn doet

STUN stelt een WebRTC-client in staat het openbare netwerkadres te ontdekken dat het kan adverteren. TURN fungeert als doorgeefluik voor media wanneer twee clients geen directe verbinding kunnen maken via hun routers of firewalls. Coturn implementeert beide services. Zonder een bereikbaar doorgeefluik kan een gesprek wel overgaan, maar op "Verbinden" blijven staan ​​wanneer de deelnemers zich op beperkende of niet-gerelateerde netwerken bevinden.

Een TURN-server heeft een openbaar IP-adres nodig, of een NAT-gateway met een openbaar IP-adres en de juiste doorstuurregels. Een server die alleen voor privédoeleinden is bedoeld, kan niet fungeren als internetrelais voor externe Matrix-gebruikers. Voor een kleine Synapse-implementatie kunt u Coturn installeren op de thuisserver of een aparte openbare host gebruiken. Een aparte host biedt duidelijkere firewallgrenzen en onafhankelijke schaalbaarheid; een installatie op dezelfde host is eenvoudiger, maar vereist zorgvuldige firewallregels zodat het relais geen privédiensten blootlegt.

1. Installeer Coturn en maak een gedeeld geheim aan.

Installeer op Debian of Ubuntu het distributiepakket:

sudo apt update
sudo apt install coturn

Het pakket levert een systemd-service en het belangrijkste configuratiebestand is doorgaans /etc/turnserver.conf. Andere distributies gebruiken hun eigen pakketnaam, servicebeheer en configuratiepad.

Genereer een sterk, privégeheim. Bijvoorbeeld:

openssl rand -hex 32

Gebruik hetzelfde geheim in Coturn en Synapse. Behandel het als een wachtwoord: hergebruik geen voorbeeldwaarde uit de documentatie, voeg het niet toe aan een openbare repository en neem het niet op in een openbaar bugrapport. Als uw Synapse-versie dit ondersteunt turn_shared_secret_path, kunt u het geheim opslaan in een beveiligd bestand in plaats van direct in het YAML-bestand. Synapse heeft deze instelling toegevoegd in versie 1.116.0; controleer uw geïmplementeerde versie voordat u deze gebruikt.

2. Configureer Coturn voor geauthenticeerde relay

Bewerk /etc/turnserver.confen stel de servicenaam en de authenticatie met gedeeld geheim in. Vervang de placeholders voor domein en geheim:

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-secretHiermee wordt het tijdsgebonden TURN-referentiemechanisme ingeschakeld dat Synapse gebruikt. Configureer geen anonieme toegang en stel geen open relay beschikbaar. De bovenstaande quotawaarden zijn een uitgangspunt, gebaseerd op de Coturn-richtlijnen van Synapse; pas ze aan aan het verwachte aantal gebruikers en de capaciteit. no-tcp-relayDit voorkomt dat clients de relay vragen om verbinding te maken met willekeurige TCP-bestemmingen; dit betekent niet dat u TCP als client-naar-TURN-transport moet uitschakelen.

TURN kan worden misbruikt als doorgeefluik naar interne of gevoelige netwerkadressen. Pas de volledige reeksen geblokkeerde peer-adressen toe in het huidige Synapse Coturn-beveiligingsvoorbeeld, inclusief de reeksen die relevant zijn voor uw IPv4- en IPv6-netwerken. Controleer de regels voordat u ze kopieert als gebruikers legitiem toegang moeten hebben tot peers op een privénetwerk. Zorg er ook voor dat Coturn up-to-date is en controleer de logboeken en quota's.

Stel het openbare adres in wanneer Coturn zich achter NAT bevindt.

Als de TURN-host zich achter een router bevindt, voeg dan het openbare adres van die router toe aan de configuratie, zodat Coturn een bereikbaar relay-adres adverteert:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Vervang de voorbeeldwaarden door de werkelijke adressen; het luisteradres is optioneel als Coturn al is gekoppeld aan de juiste interface. Stuur het TURN-luister- en relaybereik van de router door naar deze server. Een niet-overeenkomend extern adres is een veelvoorkomende oorzaak van gesprekken die wel werken binnen hetzelfde LAN, maar niet tussen verschillende netwerken.

3. Open de luister- en doorstuurpoorten

Sta de poorten toe die overeenkomen met uw Coturn-configuratie in zowel de hostfirewall als in elke cloudfirewall of -router:

• TCP- en UDP-poort 3478 voor de gebruikelijke TURN-listener.
• UDP 49152–65535 voor het standaard relay-bereik zoals hierboven weergegeven. Als u een kleiner bereik kiest, configureert u hetzelfde bereik in Coturn en de firewall.
• TCP-poort 5349 voor TURN over TLS, en UDP-poort 5349 alleen als u DTLS inschakelt en wilt aanbieden.

Voor UFW kan een basisset met UDP/TCP-listener- en UDP-relayregels er als volgt uitzien:

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

Voeg de 5349-regels alleen toe wanneer de bijbehorende TLS- of DTLS-listener is geconfigureerd en geadverteerd. Controleer ook de beveiligingsgroep van uw provider; een UFW-regel op hostniveau kan een geblokkeerde cloud-ingress-regel niet overschrijven. Publiceer de Coturn-beheerinterface niet op het internet.

4. Configureer Synapse om Coturn-referenties uit te geven.

Voeg de volgende TURN-instellingen toe aan de actieve Synapse-configuratie, meestal homeserver.yaml. De hostnaam moet publiekelijk verwijzen naar de TURN-host:

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

De eerste twee URI's adverteren gewone TURN-transporten op poort 3478. Als TLS is geconfigureerd en getest, kunt u ook een URI adverteren zoals turns:turn.example.org:5349?transport=tcp. Adverteer geen turns:URI tenzij het certificaat, de listener, de firewall en de clientcompatibiliteit allemaal correct zijn ingesteld. Het TLS-certificaat en de privésleutel van Coturn worden ingesteld met certen pkeyin de configuratie.

Stel dit in turn_allow_guestsvolgens uw kamer- en gastbeleid. Als u deze functie inschakelt, kunnen niet-geauthenticeerde gastgebruikers TURN-gegevens aanvragen, wat nodig kan zijn voor gastgesprekken, maar het risico op misbruik kan vergroten. Als u deze functie uitschakelt, kunnen gesprekken voor gasten onbetrouwbaar worden. Gebruik in beide gevallen monitoring en quota.

Start Coturn en Synapse opnieuw op nadat je hun bestanden hebt gewijzigd:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Gebruik de daadwerkelijke naam van uw Synapse systemd-eenheid als deze afwijkt. Herlaad of herstart de betreffende clients; de TURN-instellingen van Synapse worden periodiek vernieuwd, dus een client ziet mogelijk niet direct een wijziging.

Moet u TURN via TLS inschakelen?

Begin met UDP/TCP TURN op poort 3478 en controleer of een relay-kandidaat werkt. Voeg TURN via TLS alleen toe als de netwerken van uw gebruikers dit vereisen, bijvoorbeeld bedrijfsfirewalls die TLS-achtig verkeer toestaan ​​maar normaal UDP blokkeren. TLS vergroot de connectiviteit, maar voegt certificaatvernieuwing, een extra listener en clientcompatibiliteitscontroles toe.

Er is een Matrix-specifieke kanttekening: de huidige Synapse Coturn-handleiding waarschuwt dat TLS/DTLS met Let's Encrypt-certificaten niet werkt met Matrix-clients die de WebRTC-bibliotheek van Chromium gebruiken, waaronder Element Android en iOS, zoals in die handleiding wordt vermeld. Controleer de compatibiliteit met uw clientversies voordat u een TLS-URI publiceert. Dezelfde handleiding adviseert om eerst de basisservice in te stellen en TLS/DTLS daarna toe te voegen.

5. Controleer de inloggegevens en test vanaf een extern netwerk.

Controleer eerst of Coturn actief is en bekijk de logbestanden:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Inspecteer vervolgens vanuit een geauthenticeerde Matrix-clientsessie het verzoek aan het huidige Client-Server API-eindpunt van Synapse /_matrix/client/v3/voip/turnServer. Een succesvol antwoord moet een gebruikersnaam, wachtwoord, time-to-live en de door u geconfigureerde TURN-URI's bevatten. Deel dit antwoord niet openbaar; de inloggegevens zijn tijdelijke toegangstokens voor uw relay.

Gebruik de officiële WebRTC Trickle ICE-voorbeeldapplicatie om te testen met een gebruikersnaam en wachtwoord die door Synapse worden geretourneerd. Voeg uw TURN URI en inloggegevens toe, voer de ICE-verzameltest uit en zoek naar een kandidaat waarvan het type is relay. Een server die alleen reageert op STUN kan een server-reflexieve kandidaat weergeven, maar toch geen media doorgeven. Test vanaf een mobiele verbinding of een netwerk buiten uw LAN en plaats vervolgens een daadwerkelijk gesprek tussen deelnemers op verschillende netwerken.

Veelvoorkomende storingen diagnosticeren

• Er worden geen TURN-gegevens weergegeven: controleer of Synapse de juiste configuratie heeft geladen, succesvol opnieuw is opgestart en of het gedeelde geheim is ingesteld. Inspecteer het antwoord op het verzoek op /voip/turnServer.
• De inloggegevens verschijnen wel, maar er worden geen relay-kandidaten gevonden: controleer TCP/UDP 3478, de geadverteerde hostnaam, of het geheim overeenkomt, raadpleeg Coturn-logboeken en controleer het UDP-relaybereik via elke firewall.
• Oproepen werken binnen één LAN, maar mislukken tussen netwerken: inspectie external-ip, poortdoorsturing en de retourroute. Coturn moet het openbare IP-adres dat clients kunnen bereiken, bekendmaken.
• Gesprekken komen alleen tot stand wanneer TLS is uitgeschakeld: controleer de certificaatketen, de TLS-listener, de geadverteerde turns:URI en de clientspecifieke compatibiliteit.
• Traditionele gesprekken werken wel, maar Element Call niet: controleer de MatrixRTC/LiveKit-transportconfiguratie afzonderlijk. Een succesvolle Coturn-test verifieert de LiveKit SFU of de MatrixRTC-autorisatieservice niet.

Voor browserclients kunnen de WebRTC-diagnostiek van de browser aantonen of media een relay-kandidaat heeft geselecteerd. Controleer voor MatrixRTC of Synapse het transport-eindpunt publiceert en of de LiveKit WebSocket- en autorisatieroutes bereikbaar zijn. Test zowel het huidige eindpunt als eventuele gedocumenteerde fallback-mogelijkheden voor ontdekking die vereist zijn door de clients die u ondersteunt.

Configuratiereferenties

• Synapse: Een TURN-server configureren
• Synapse: Installatie, beveiliging, NAT en TLS-configuratie van Coturn
• Synapse-configuratiehandleiding voor TURN en MatrixRTC
• Het officiële turnserver.conf-voorbeeld van Coturn
• Element Call: Handleiding voor zelfhosting van MatrixRTC
• LiveKit-implementatie en TURN-configuratie
• Update van Matrix.org over de ontdekking van transportmechanismen in Element Call 0.24.
• Specificatie van de Matrix Client-Server API, inclusief het TURN-referentie-eindpunt.