Come configurare un server Matrix Coturn TURN/STUN per chiamate audio e video

Una recente modifica alle chiamate Matrix influisce sul rilevamento, ma non sulle credenziali o sulle porte TURN di Coturn. Nell'aggiornamento del 21 agosto 2026, Matrix.org ha segnalato che Element Call 0.24 ha deprecato il rilevamento dei trasporti MatrixRTC tramite il /.well-known/matrix/clientfile homeserver. Le implementazioni standalone di Element Call dovrebbero supportare l'endpoint dei trasporti MatrixRTC; Element Web/Desktop ed Element X mantenevano il vecchio metodo di rilevamento come soluzione di ripiego durante la transizione dei client. Questa modifica è separata dalla configurazione TURN classica.

Questa guida configura Coturn per il servizio TURN di Synapse, che fornisce credenziali ICE temporanee ai client che utilizzano chiamate WebRTC tradizionali. Le attuali chiamate Element Call e le chiamate di gruppo MatrixRTC utilizzano un'unità di inoltro selettivo (SFU) LiveKit e un servizio di autorizzazione MatrixRTC. Coturn da solo non sostituisce questi componenti. Se il tuo obiettivo è un Element Call self-hosted, segui il percorso LiveKit descritto nella guida ufficiale di Element Call; aggiungi Coturn solo se l'architettura multimediale scelta richiede un servizio TURN separato.

Scegli prima il percorso di chiamata corretto

Per MatrixRTC su Synapse, l'attuale guida all'hosting autonomo di Element Call utilizza matrix_rtc.transportse abilita il registro di trasporto del server domestico tramite il flag di funzionalità sperimentale documentato. L'avviso di Matrix.org 2026 afferma che questa modifica di rilevamento è rilevante soprattutto per le implementazioni standalone di Element Call; altri amministratori possono preparare l'endpoint mentre i client supportati mantengono un fallback. Consultare la guida per i client e la versione di Synapse effettivamente in uso.

Cosa fa Coturn

STUN permette a un client WebRTC di scoprire l'indirizzo di rete pubblico che può pubblicizzare. TURN inoltra i flussi multimediali quando due client non riescono a stabilire una connessione diretta attraverso i loro router o firewall. Coturn implementa entrambi i servizi. Senza un relay raggiungibile, una chiamata potrebbe squillare ma rimanere su "Connessione in corso" se i partecipanti si trovano su reti con restrizioni o non correlate.

Un server TURN necessita di un indirizzo IP pubblico o di un gateway NAT con un IP pubblico e regole di inoltro corrette. Un server con solo indirizzo IP privato non può fungere da relay Internet per gli utenti Matrix remoti. Per una piccola implementazione di Synapse, è possibile installare Coturn sul server principale o utilizzare un host pubblico separato. Un host separato offre confini del firewall più chiari e scalabilità indipendente; un'installazione sullo stesso host è più semplice, ma richiede regole del firewall precise affinché il relay non esponga servizi privati.

1. Installa Coturn e prepara un segreto condiviso

Su Debian o Ubuntu, installa il pacchetto di distribuzione:

sudo apt update
sudo apt install coturn

Il pacchetto fornisce un servizio systemd e il file di configurazione principale è comunemente /etc/turnserver.conf. Altre distribuzioni utilizzano un proprio nome di pacchetto, gestione dei servizi e percorso di configurazione.

Genera un segreto forte e privato. Ad esempio:

openssl rand -hex 32

Utilizza lo stesso segreto in Coturn e Synapse. Trattalo come una password: non riutilizzare un valore di esempio dalla documentazione, non caricarlo in un repository pubblico e non includerlo in una segnalazione di bug pubblica. Se la tua versione di Synapse lo supporta turn_shared_secret_path, puoi memorizzare il segreto in un file protetto anziché inserirlo direttamente nel file YAML. Synapse ha aggiunto questa impostazione nella versione 1.116.0; verifica la versione installata prima di utilizzarla.

2. Configurare Coturn per il relay autenticato

Modifica /etc/turnserver.confe imposta il nome del servizio e l'autenticazione tramite chiave segreta condivisa. Sostituisci i segnaposto di dominio e chiave segreta:

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-secretAbilita il meccanismo di credenziali TURN a tempo limitato utilizzato da Synapse. Non configurare l'accesso anonimo né esporre un relay aperto. I valori di quota sopra indicati sono un punto di partenza tratto dalle linee guida Coturn di Synapse; adattali al numero di utenti e alla capacità previsti. no-tcp-relayImpedisce ai client di chiedere al relay di connettersi a destinazioni TCP arbitrarie; ciò non significa che sia necessario disabilitare TCP come trasporto client-TURN.

TURN può essere utilizzato impropriamente come relay verso indirizzi di rete interni o sensibili. Applicare gli intervalli di indirizzi dei peer bloccati presenti nell'esempio di sicurezza di Synapse Coturn, inclusi gli intervalli rilevanti per le reti IPv4 e IPv6. Prima di copiare le regole, si consiglia di esaminarle attentamente qualora gli utenti abbiano effettivamente bisogno di raggiungere peer di reti private. È inoltre fondamentale mantenere Coturn aggiornato e monitorare i relativi log e le quote.

Imposta l'indirizzo pubblico quando Coturn si trova dietro un NAT

Se l'host TURN si trova dietro un router, aggiungi il suo indirizzo pubblico alla configurazione in modo che Coturn pubblicizzi un indirizzo di inoltro raggiungibile:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Sostituisci i valori di esempio con gli indirizzi effettivi; l'indirizzo di ascolto è facoltativo se Coturn è già associato all'interfaccia corretta. Inoltra l'intervallo di ascolto e inoltro di TURN dal router a questo server. Un indirizzo esterno non corrispondente è una causa comune di chiamate che funzionano sulla stessa LAN ma falliscono tra reti diverse.

3. Aprire le porte listener e relay.

Consenti le porte corrispondenti alla configurazione di Coturn sia nel firewall host che in qualsiasi firewall o router cloud:

• Porta TCP e UDP 3478 per il listener TURN standard.
• UDP 49152–65535 per l'intervallo di inoltro predefinito mostrato sopra. Se si sceglie un intervallo più piccolo, configurare lo stesso intervallo in Coturn e nel firewall.
• TCP 5349 per TURN su TLS e UDP 5349 solo se si abilita e si intende offrire DTLS.

Per UFW, un set di regole di base per l'ascolto UDP/TCP e l'inoltro UDP potrebbe essere simile a questo:

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

Aggiungi le regole 5349 solo quando il listener TLS o DTLS corrispondente è configurato e pubblicizzato. Verifica anche il gruppo di sicurezza del tuo provider; una regola UFW a livello host non può sovrascrivere una regola di ingresso cloud bloccata. Non pubblicare l'interfaccia di controllo amministrativo di Coturn su Internet.

4. Configurare Synapse per emettere le credenziali di Coturn

Aggiungere le seguenti impostazioni TURN alla configurazione Synapse attiva, solitamente homeserver.yaml. Il nome host deve risolversi pubblicamente nell'host 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

I primi due URI pubblicizzano i normali trasporti TURN sulla porta 3478. Se TLS è configurato e testato, è possibile pubblicizzare anche un URI come turns:turn.example.org:5349?transport=tcp. Non pubblicizzare un turns:URI a meno che il certificato, il listener, il firewall e la compatibilità del client non siano tutti presenti. Il certificato TLS e la chiave privata di Coturn sono impostati con certe pkeynella sua configurazione.

Imposta questa opzione turn_allow_guestsin base alle policy della tua camera e degli ospiti. L'attivazione potrebbe consentire agli ospiti non autenticati di richiedere le credenziali TURN, necessarie per le chiamate degli ospiti ma che potrebbero aumentare il rischio di abusi. La disattivazione potrebbe rendere le chiamate degli ospiti inaffidabili. In entrambi i casi, è consigliabile utilizzare il monitoraggio e le quote.

Riavvia Coturn e Synapse dopo aver modificato i relativi file:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Se diverso, utilizza il nome effettivo dell'unità systemd di Synapse. Ricarica o riavvia i client interessati; le impostazioni TURN di Synapse vengono aggiornate periodicamente, quindi un client potrebbe non visualizzare immediatamente la modifica.

È consigliabile abilitare TURN su TLS?

Iniziate con UDP/TCP TURN sulla porta 3478 e verificate che un server di inoltro funzioni correttamente. Aggiungete TURN su TLS solo se le reti dei vostri utenti lo richiedono, ad esempio in presenza di firewall aziendali che consentono il traffico di tipo TLS ma bloccano il normale UDP. TLS amplia la connettività, ma introduce il rinnovo dei certificati, un ulteriore listener e controlli di compatibilità del client.

Esiste un'avvertenza specifica per Matrix: la guida attuale di Synapse Coturn avverte che TLS/DTLS con certificati Let's Encrypt non funziona con i client Matrix che utilizzano la libreria WebRTC di Chromium, inclusi Element per Android e iOS, come indicato nella guida stessa. Verificare la compatibilità con le versioni del client prima di pubblicare un URI TLS. La stessa guida raccomanda di configurare prima il servizio di base e di aggiungere TLS/DTLS in seguito.

5. Verifica le credenziali ed esegui il test da una rete esterna

Innanzitutto, verifica che Coturn sia in esecuzione e controlla i relativi log:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Successivamente, da una sessione client Matrix autenticata, esamina la richiesta all'endpoint API Client-Server corrente di Synapse /_matrix/client/v3/voip/turnServer. Una risposta positiva dovrebbe includere nome utente, password, time-to-live e gli URI TURN che hai configurato. Non condividere pubblicamente tale risposta; le credenziali sono token di accesso temporanei per il tuo relay.

Utilizza l'esempio ufficiale WebRTC Trickle ICE per eseguire il test con un nome utente e una password restituiti da Synapse. Aggiungi il tuo URI TURN e le credenziali, esegui il test di raccolta ICE e cerca un candidato il cui tipo sia relay. Un server che risponde semplicemente a STUN potrebbe mostrare un candidato server-reflexive ma non riuscire comunque a inoltrare i media. Esegui il test da una connessione mobile o da una rete esterna alla tua LAN, quindi effettua una chiamata reale tra partecipanti su reti diverse.

Diagnosticare i guasti più comuni

• Non vengono visualizzate credenziali TURN: verificare che Synapse abbia caricato la configurazione corretta, sia stato riavviato correttamente e che il segreto condiviso sia impostato. Esaminare la risposta alla richiesta per /voip/turnServer.
• Le credenziali sono presenti ma non compaiono i moduli candidati per il relay: verificare TCP/UDP 3478, il nome host pubblicizzato, la corrispondenza del segreto, i log di Coturn e l'intervallo di relay UDP attraverso ogni firewall.
• Le chiamate funzionano su una LAN ma falliscono tra reti diverse: ispezionare external-ip, inoltrare le porte e instradare il ritorno. Coturn deve pubblicizzare l'indirizzo pubblico raggiungibile dai client.
• Le chiamate vengono stabilite solo quando TLS è disabilitato: verificare la catena di certificati, il listener TLS, turns:l'URI pubblicizzato e la compatibilità specifica del client.
• Le chiamate tradizionali funzionano, ma Element Call no: verificare separatamente la configurazione del trasporto MatrixRTC/LiveKit. Un test Coturn riuscito non verifica il servizio SFU di LiveKit o il servizio di autorizzazione MatrixRTC.

Per i client browser, la diagnostica WebRTC del browser può mostrare se il supporto multimediale ha selezionato un candidato per l'inoltro. Per MatrixRTC, verificare che Synapse pubblichi l'endpoint di trasporto e che i percorsi WebSocket e di autorizzazione di LiveKit siano raggiungibili. Testare sia l'endpoint corrente sia qualsiasi fallback di rilevamento documentato richiesto dai client supportati.

Riferimenti di configurazione

• Synapse: Configurazione di un server TURN
• Synapse: installazione di Coturn, configurazione di sicurezza, NAT e TLS.
• Riferimento di configurazione Synapse per TURN e MatrixRTC
• Esempio ufficiale di turnserver.conf di Coturn
• Element Call: Guida all'hosting autonomo di MatrixRTC
• Distribuzione di LiveKit e configurazione di TURN
• Aggiornamento di Matrix.org sulla scoperta del trasporto Element Call 0.24
• Specifiche dell'API client-server di Matrix, incluso l'endpoint delle credenziali TURN.