Cum se configurează un server Matrix Coturn TURN/STUN pentru apeluri audio și video

O modificare actuală a apelurilor Matrix afectează descoperirea, dar nu și acreditările sau porturile TURN ale Coturn. În actualizarea din 21 august 2026, Matrix.org a raportat că Element Call 0.24 a depreciat descoperirea transporturilor MatrixRTC prin /.well-known/matrix/clientfișierul serverului principal. Implementările independente Element Call ar trebui să suporte punctul final al transporturilor MatrixRTC; Element Web/Desktop și Element X păstrau vechea metodă de descoperire ca soluție de rezervă în timpul tranziției clienților. Aceasta este separată de configurarea clasică TURN.

Acest ghid configurează Coturn pentru serviciul TURN al Synapse, care furnizează acreditări ICE temporare clienților care utilizează apeluri WebRTC tradiționale. Apelurile Element Call și de grup MatrixRTC curente utilizează o unitate de redirecționare selectivă (SFU) LiveKit și un serviciu de autorizare MatrixRTC. Coturn singur nu înlocuiește aceste componente. Dacă obiectivul dvs. este un apel Element Call auto-găzduit, utilizați calea LiveKit descrisă în ghidul oficial Element Call; adăugați Coturn numai dacă arhitectura media aleasă necesită un serviciu TURN separat.

Alege mai întâi calea de apelare corectă

Pentru MatrixRTC pe Synapse, ghidul actual de auto-găzduire Element Call utilizează matrix_rtc.transportsși activează registrul de transport al serverului de acasă prin intermediul indicatorului de caracteristică experimentală documentat. Notificarea Matrix.org 2026 precizează că această modificare a descoperirii este cea mai importantă pentru implementările independente Element Call; alți administratori ar putea pregăti endpoint-ul, în timp ce clienții acceptați ar păstra o soluție de rezervă. Consultați ghidul pentru clienții și versiunea Synapse pe care o rulați efectiv.

Ce face Coturn

STUN permite unui client WebRTC să descopere adresa de rețea publică pe care o poate promova. TURN retransmite media atunci când doi clienți nu pot stabili o conexiune directă prin routerele sau firewall-urile lor. Coturn implementează ambele servicii. Fără o retransmisie accesibilă, un apel poate suna, dar poate rămâne pe „Conectare” atunci când participanții se află în rețele restrictive sau fără legătură.

Un server TURN are nevoie de o adresă IP publică sau de un gateway NAT cu o adresă IP publică și reguli de redirecționare corecte. Un server exclusiv privat nu poate acționa ca un releu Internet pentru utilizatorii Matrix la distanță. Pentru o implementare Synapse mică, puteți instala Coturn pe serverul de acasă sau puteți utiliza o gazdă publică separată. O gazdă separată oferă limite mai clare ale firewall-ului și scalare independentă; o instalare pe aceeași gazdă este mai simplă, dar necesită reguli de firewall atente, astfel încât releul să nu expună serviciile private.

1. Instalați Coturn și pregătiți un secret partajat

Pe Debian sau Ubuntu, instalați pachetul de distribuție:

sudo apt update
sudo apt install coturn

Pachetul furnizează un serviciu systemd, iar fișierul principal de configurare este de obicei /etc/turnserver.conf. Alte distribuții folosesc propriul nume de pachet, gestionare a serviciilor și cale de configurare.

Generați un secret privat puternic. De exemplu:

openssl rand -hex 32

Folosește același secret în Coturn și Synapse. Tratează-l ca pe o parolă: nu reutilizează o valoare exemplu din documentație, nu o comite într-un depozit public și nu o include într-un raport de eroare public. Dacă versiunea ta de Synapse acceptă turn_shared_secret_path, poți stoca secretul într-un fișier protejat în loc să fie inline în YAML. Synapse a adăugat această setare în versiunea 1.116.0; verifică versiunea implementată înainte de a o utiliza.

2. Configurați Coturn pentru retransmisie autentificată

Editați /etc/turnserver.confși setați numele serviciului și autentificarea cu secret partajat. Înlocuiți substituenții pentru domeniu și secret:

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-secretactivează mecanismul de acreditare TURN cu limită de timp utilizat de Synapse. Nu configurați acces anonim și nu expuneți un releu deschis. Valorile cotei de mai sus reprezintă un punct de plecare extras din îndrumările Coturn ale Synapse; ajustați-le la numărul și capacitatea așteptate de utilizatori. no-tcp-relayîmpiedică clienții să solicite releului să se conecteze la destinații TCP arbitrare; nu înseamnă că trebuie să dezactivați TCP ca transport de la client la TURN.

TURN poate fi abuzat ca un releu către adrese de rețea interne sau sensibile. Aplicați intervalele complete de adrese denied-peer în exemplul actual de securitate Synapse Coturn, inclusiv intervalele relevante pentru rețelele IPv4 și IPv6. Revizuiți regulile înainte de a le copia dacă utilizatorii au nevoie în mod legitim să ajungă la colegi din rețeaua privată. De asemenea, mențineți Coturn actualizat și monitorizați jurnalele și cotele sale.

Setați adresa publică când Coturn este în spatele NAT-ului

Dacă gazda TURN se află în spatele unui router, adăugați adresa sa publică la configurație, astfel încât Coturn să anunțe o adresă de retransmisie accesibilă:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Înlocuiți valorile eșantion cu adresele reale; adresa de ascultare este opțională dacă Coturn se leagă deja la interfața corectă. Redirecționați listenerul TURN și intervalul de retransmisie de la router la acest server. O adresă externă nepotrivită este o cauză frecventă a apelurilor care funcționează pe aceeași rețea locală, dar eșuează între rețele diferite.

3. Deschideți porturile de ascultare și de retransmitere

Permiteți porturile care corespund configurației dvs. Coturn atât în ​​firewall-ul gazdă, cât și în orice firewall sau router în cloud:

• TCP și UDP 3478 pentru ascultătorul TURN obișnuit.
• UDP 49152–65535 pentru intervalul implicit de relee afișat mai sus. Dacă alegeți un interval mai mic, configurați același interval în Coturn și în firewall.
• TCP 5349 pentru TURN peste TLS și UDP 5349 numai dacă activați și intenționați să oferiți DTLS.

Pentru UFW, un listener UDP/TCP de bază și un set de reguli de retransmisie UDP pot arăta astfel:

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

Adăugați regulile 5349 numai atunci când listener-ul TLS sau DTLS corespunzător este configurat și anunțat. Verificați și grupul de securitate al furnizorului; o regulă UFW la nivel de gazdă nu poate suprascrie o regulă de intrare blocată în cloud. Nu publicați interfața de control administrativ Coturn pe internet.

4. Configurați Synapse pentru a emite acreditări Coturn

Adăugați următoarele setări TURN la configurația activă Synapse, de obicei homeserver.yaml. Numele gazdei trebuie să fie rezolvat public către gazda TURN:

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

Primele două URI-uri promovează transporturi TURN obișnuite pe portul 3478. Dacă TLS este configurat și testat, puteți face publicitate și unui URI, cum ar fi turns:turn.example.org:5349?transport=tcp. Nu faceți publicitate unui turns:URI decât dacă sunt implementate toate cerințele de compatibilitate cu certificatul, listener-ul, firewall-ul și clientul. Certificatul TLS și cheia privată ale Coturn sunt setate cu certși pkeyîn configurația sa.

Setați turn_allow_guestsconform politicii privind camera și oaspeții. Activarea acesteia poate permite utilizatorilor neautentificați să solicite acreditări TURN, care pot fi necesare pentru apelurile oaspeților, dar pot crește riscul de abuz. Dezactivarea acesteia poate face ca apelurile să fie nesigure pentru oaspeți. Folosiți monitorizarea și cotele în ambele cazuri.

Reporniți Coturn și Synapse după ce le modificați fișierele:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Folosește numele real al unității systemd Synapse dacă acesta este diferit. Reîncarcă sau repornește clienții afectați; setările TURN ale Synapse sunt actualizate periodic, așa că este posibil ca un client să nu vadă imediat o modificare.

Ar trebui să activezi TURN peste TLS?

Începeți cu UDP/TCP TURN pe 3478 și confirmați că un candidat de retransmisie funcționează. Adăugați TURN peste TLS numai dacă rețelele utilizatorilor dvs. au nevoie de el, cum ar fi firewall-urile corporative care permit trafic de tip TLS, dar blochează UDP-ul normal. TLS extinde conectivitatea, dar adaugă reînnoirea certificatului, un alt listener și verificări de compatibilitate a clienților.

Există o avertizare specifică Matrix: ghidul actual Synapse Coturn avertizează că TLS/DTLS cu certificate Let's Encrypt nu funcționează cu clienții Matrix care utilizează biblioteca WebRTC a Chromium, inclusiv Element Android și iOS, așa cum se menționează în ghidul respectiv. Verificați compatibilitatea pentru versiunile clientului înainte de a publica un URI TLS. Același ghid recomandă configurarea mai întâi a serviciului de bază și adăugarea TLS/DTLS ulterior.

5. Verificați acreditările și testați dintr-o rețea externă

Mai întâi verificați dacă Coturn rulează și examinați jurnalele sale:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Apoi, dintr-o sesiune client Matrix autentificată, inspectați solicitarea către endpoint-ul API Client-Server curent al Synapse /_matrix/client/v3/voip/turnServer. Un răspuns reușit ar trebui să includă un nume de utilizator, o parolă, un time-to-live și URI-urile TURN pe care le-ați configurat. Nu partajați public acest răspuns; acreditările sunt token-uri de acces temporare pentru retransmiterea dvs.

Folosește exemplul oficial WebRTC Trickle ICE pentru a testa cu un nume de utilizator și o parolă returnate de Synapse. Adaugă URI-ul și acreditările TURN, rulează testul de colectare ICE și caută un candidat al cărui tip este relay. Un server care răspunde doar la STUN poate afișa un candidat care reflectă serverul, dar tot nu reușește să transmită media. Testează de pe o conexiune mobilă sau o rețea din afara LAN-ului tău, apoi efectuează un apel real între participanți din rețele diferite.

Diagnosticarea defecțiunilor comune

• Nu apar acreditări TURN: verificați dacă Synapse a încărcat configurația corectă, a repornit cu succes și are setat secretul partajat. Verificați răspunsul la solicitare pentru /voip/turnServer.
• Apar acreditările, dar nu se formează niciun candidat pentru retransmisie: verificați TCP/UDP 3478, numele de gazdă anunțat, potrivirea secretă, jurnalele Coturn și intervalul de retransmisie UDP prin fiecare firewall.
• Apelurile funcționează pe o singură rețea locală, dar eșuează în diferite rețele: inspect external-ip, redirecționarea porturilor și ruta de retur. Coturn trebuie să anunțe ruta publică pe care clienții o pot accesa.
• Apelurile se conectează numai când TLS este dezactivat: confirmați lanțul de certificate, listener-ul TLS, turns:URI-ul anunțat și compatibilitatea specifică clientului.
• Apelurile tradiționale funcționează, dar Element Call nu: verificați separat configurația transportului MatrixRTC/LiveKit. Un test Coturn reușit nu verifică serviciul de autorizare LiveKit SFU sau MatrixRTC.

Pentru clienții de browser, diagnosticarea WebRTC a browserului poate arăta dacă mediul a selectat un candidat de retransmisie. Pentru MatrixRTC, verificați dacă Synapse publică punctul final de transport și dacă LiveKit WebSocket și rutele de autorizare sunt accesibile. Testați atât punctul final curent, cât și orice soluție de descoperire documentată necesară de clienții pe care îi suportați.

Referințe de configurare

• Synapse: Configurarea unui server TURN
• Synapse: Instalare Coturn, securitate, NAT și configurare TLS
• Referință de configurare a sinapselor pentru TURN și MatrixRTC
• Exemplul oficial turnserver.conf al lui Coturn
• Element Call: Ghid de auto-găzduire MatrixRTC
• Implementarea LiveKit și configurarea TURN
• Actualizare Matrix.org privind descoperirea transportului în Element Call 0.24
• Specificația API-ului Matrix Client-Server, inclusiv punctul final al acreditărilor TURN