Cómo configurar un servidor Matrix Coturn TURN/STUN para llamadas de audio y vídeo

Un cambio reciente en la llamada a Matrix afecta al descubrimiento, pero no a las credenciales ni a los puertos TURN de Coturn. En su actualización del 21 de agosto de 2026, Matrix.org informó que Element Call 0.24 dejó de utilizar el descubrimiento de transportes MatrixRTC a través del /.well-known/matrix/clientarchivo del servidor principal. Las implementaciones independientes de Element Call deberían ser compatibles con el punto final de transportes MatrixRTC; Element Web/Desktop y Element X conservaban el método de descubrimiento anterior como alternativa mientras los clientes realizaban la transición. Esto es independiente de la configuración TURN clásica.

Esta guía configura Coturn para el servicio TURN de Synapse, que proporciona credenciales ICE temporales a los clientes que utilizan llamadas WebRTC tradicionales. Las llamadas grupales actuales de Element Call y MatrixRTC utilizan una unidad de reenvío selectivo (SFU) de LiveKit y un servicio de autorización de MatrixRTC. Coturn por sí solo no reemplaza estos componentes. Si su objetivo es alojar Element Call en su propio servidor, utilice la ruta de LiveKit descrita en la guía oficial de Element Call; agregue Coturn solo si la arquitectura de medios elegida requiere un servicio TURN independiente.

Primero, elige la ruta de llamada correcta.

Para MatrixRTC en Synapse, la guía actual de autoalojamiento de Element Call utiliza matrix_rtc.transportsy habilita el registro de transporte del servidor principal mediante la bandera de características experimentales documentada. El aviso de Matrix.org 2026 indica que este cambio de detección es más relevante para las implementaciones independientes de Element Call; otros administradores podrían preparar el punto final mientras que los clientes compatibles conservan una alternativa. Consulte la guía para conocer los clientes y la versión de Synapse que utiliza.

Lo que hace Coturn

STUN permite que un cliente WebRTC descubra la dirección de red pública que puede anunciar. TURN retransmite el contenido multimedia cuando dos clientes no pueden establecer una conexión directa a través de sus enrutadores o cortafuegos. Coturn implementa ambos servicios. Sin un relé accesible, una llamada puede sonar pero permanecer en estado "Conectando" cuando los participantes se encuentran en redes restrictivas o no relacionadas.

Un servidor TURN necesita una dirección IP pública o una puerta de enlace NAT con una IP pública y las reglas de reenvío correctas. Un servidor exclusivamente privado no puede funcionar como repetidor de Internet para usuarios remotos de Matrix. Para una implementación pequeña de Synapse, puede instalar Coturn en el servidor principal o usar un host público independiente. Un host independiente proporciona límites de firewall más claros y escalabilidad independiente; una instalación en el mismo host es más sencilla, pero requiere reglas de firewall precisas para que el repetidor no exponga servicios privados.

1. Instale Coturn y prepare una clave secreta compartida.

En Debian o Ubuntu, instale el paquete de distribución:

sudo apt update
sudo apt install coturn

El paquete proporciona un servicio systemd y el archivo de configuración principal suele ser /etc/turnserver.conf. Otras distribuciones utilizan su propio nombre de paquete, gestión de servicios y ruta de configuración.

Genera un secreto seguro y privado. Por ejemplo:

openssl rand -hex 32

Utiliza la misma clave secreta en Coturn y Synapse. Trátala como una contraseña: no reutilices un valor de ejemplo de la documentación, no lo publiques en un repositorio público ni lo incluyas en un informe de errores público. Si tu versión de Synapse lo permite turn_shared_secret_path, puedes almacenar la clave secreta en un archivo protegido en lugar de insertarla directamente en YAML. Synapse añadió esta opción en la versión 1.116.0; comprueba la versión que tienes instalada antes de usarla.

2. Configure Coturn para la retransmisión autenticada.

Edite /etc/turnserver.confy configure el nombre del servicio y la autenticación de clave compartida. Reemplace los marcadores de posición de dominio y clave secreta:

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-secretHabilita el mecanismo de credenciales TURN con límite de tiempo que utiliza Synapse. No configure el acceso anónimo ni exponga un relé abierto. Los valores de cuota anteriores son un punto de partida basado en la guía Coturn de Synapse; ajústelos según la cantidad de usuarios y la capacidad previstas. no-tcp-relayImpide que los clientes soliciten al relé que se conecte a destinos TCP arbitrarios; esto no significa que deba deshabilitar TCP como transporte de cliente a TURN.

TURN puede utilizarse indebidamente como repetidor hacia direcciones de red internas o sensibles. Aplique los rangos completos de direcciones de pares denegados en el ejemplo de seguridad actual de Synapse Coturn, incluidos los rangos relevantes para sus redes IPv4 e IPv6. Revise las reglas antes de copiarlas si los usuarios necesitan legítimamente acceder a pares de la red privada. Mantenga Coturn actualizado y supervise sus registros y cuotas.

Configura el sistema de megafonía cuando Coturn esté detrás de NAT.

Si el host TURN se encuentra detrás de un enrutador, agregue su dirección pública a la configuración para que Coturn anuncie una dirección de relé accesible:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Sustituya los valores de ejemplo por las direcciones reales; la dirección de escucha es opcional si Coturn ya está vinculado a la interfaz correcta. Reenvíe el rango de escucha y retransmisión de TURN desde el enrutador a este servidor. Una dirección externa incorrecta es una causa común de llamadas que funcionan en la misma LAN pero fallan entre redes diferentes.

3. Abra los puertos de escucha y retransmisión.

Permita los puertos que coincidan con su configuración de Coturn tanto en el firewall del host como en cualquier firewall o enrutador en la nube:

• TCP y UDP 3478 para el oyente TURN habitual.
• UDP 49152–65535 para el rango de retransmisión predeterminado que se muestra arriba. Si elige un rango menor, configure el mismo rango en Coturn y en el firewall.
• TCP 5349 para TURN sobre TLS, y UDP 5349 solo si habilita y tiene la intención de ofrecer DTLS.

Para UFW, un conjunto básico de reglas para un oyente UDP/TCP y un relé UDP puede tener este aspecto:

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

Agregue las reglas 5349 solo cuando el receptor TLS o DTLS correspondiente esté configurado y anunciado. Verifique también el grupo de seguridad de su proveedor; una regla UFW a nivel de host no puede anular una regla de entrada a la nube bloqueada. No publique la interfaz de control administrativo de Coturn en Internet.

4. Configure Synapse para emitir credenciales de Coturn.

Agregue la siguiente configuración de TURN a la configuración activa de Synapse, generalmente homeserver.yaml. El nombre de host debe resolverse públicamente al 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

Las dos primeras URI anuncian transportes TURN ordinarios en el puerto 3478. Si TLS está configurado y probado, también puede anunciar una URI como turns:turn.example.org:5349?transport=tcp. No anuncie una turns:URI a menos que el certificado, el oyente, el cortafuegos y la compatibilidad del cliente estén en su lugar. El certificado TLS y la clave privada de Coturn se establecen con certy pkeyen su configuración.

Configúralo turn_allow_guestssegún la política de tu habitación y de los huéspedes. Habilitarlo puede permitir que usuarios no autenticados soliciten credenciales TURN, necesarias para las llamadas de los huéspedes, pero que pueden aumentar el riesgo de abuso. Deshabilitarlo puede hacer que las llamadas de los huéspedes sean poco fiables. En cualquier caso, utiliza la monitorización y las cuotas.

Reinicia Coturn y Synapse después de modificar sus archivos:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Si el nombre de la unidad systemd de Synapse es diferente, utilícelo. Recargue o reinicie los clientes afectados; la configuración TURN de Synapse se actualiza periódicamente, por lo que es posible que el cliente no vea el cambio de inmediato.

¿Debería habilitar TURN sobre TLS?

Comience con UDP/TCP TURN en el puerto 3478 y confirme que un servidor de retransmisión funcione. Agregue TURN sobre TLS solo si las redes de sus usuarios lo requieren, como por ejemplo, en el caso de firewalls corporativos que permiten tráfico similar a TLS pero bloquean el UDP normal. TLS amplía la conectividad, pero también implica la renovación del certificado, un oyente adicional y comprobaciones de compatibilidad del cliente.

Existe una advertencia específica para Matrix: la guía actual de Synapse Coturn advierte que TLS/DTLS con certificados Let's Encrypt no funciona con los clientes de Matrix que utilizan la biblioteca WebRTC de Chromium, incluidos Element Android e iOS, como se indica en dicha guía. Verifique la compatibilidad con sus versiones de cliente antes de publicar una URI TLS. La misma guía recomienda configurar primero el servicio básico y agregar TLS/DTLS posteriormente.

5. Verifique las credenciales y realice la prueba desde una red externa.

Primero, compruebe que Coturn se está ejecutando y revise sus registros:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Luego, desde una sesión de cliente Matrix autenticada, inspeccione la solicitud al punto final de la API cliente-servidor actual de Synapse /_matrix/client/v3/voip/turnServer. Una respuesta exitosa debería incluir un nombre de usuario, contraseña, tiempo de vida y las URI TURN que configuró. No comparta esa respuesta públicamente; las credenciales son tokens de acceso temporales para su relé.

Utilice el ejemplo oficial de WebRTC Trickle ICE para realizar pruebas con un nombre de usuario y una contraseña proporcionados por Synapse. Añada su URI TURN y sus credenciales, ejecute la prueba de recopilación de ICE y busque un candidato cuyo tipo sea relay. Un servidor que simplemente responde a STUN puede mostrar un candidato reflexivo del servidor, pero aun así no lograr retransmitir el contenido multimedia. Realice la prueba desde una conexión móvil o una red fuera de su LAN y, a continuación, establezca una llamada real entre participantes en redes diferentes.

Diagnosticar fallos comunes

• No aparecen credenciales TURN: compruebe que Synapse haya cargado la configuración correcta, se haya reiniciado correctamente y tenga el secreto compartido configurado. Inspeccione la respuesta de la solicitud para /voip/turnServer.
• Aparecen las credenciales, pero no se forma ningún candidato de retransmisión: verifique TCP/UDP 3478, el nombre de host anunciado, la coincidencia de la clave secreta, los registros de Coturn y el rango de retransmisión UDP a través de cada firewall.
• Las llamadas funcionan en una LAN pero fallan entre redes: inspección external-ip, reenvío de puertos y ruta de retorno. Coturn debe anunciar la dirección pública a la que los clientes pueden acceder.
• Las llamadas solo se conectan cuando TLS está deshabilitado: confirme la cadena de certificados, el oyente TLS, turns:el URI anunciado y la compatibilidad específica del cliente.
• Las llamadas tradicionales funcionan, pero Element Call no: compruebe la configuración de transporte de MatrixRTC/LiveKit por separado. Una prueba Coturn exitosa no verifica el servicio de autorización SFU de LiveKit ni el de MatrixRTC.

Para clientes de navegador, el diagnóstico WebRTC del navegador puede mostrar si el medio seleccionó un candidato de retransmisión. Para MatrixRTC, verifique que Synapse publique el punto final de transporte y que las rutas de autorización y WebSocket de LiveKit sean accesibles. Pruebe tanto el punto final actual como cualquier método de detección alternativo documentado que requieran los clientes compatibles.

Referencias de configuración

• Synapse: Configuración de un servidor TURN
• Synapse: Instalación de Coturn, seguridad, NAT y configuración TLS
• Referencia de configuración de Synapse para TURN y MatrixRTC
• Ejemplo oficial de turnserver.conf de Coturn
• Llamada a elementos: Guía de autoalojamiento de MatrixRTC
• Implementación de LiveKit y configuración de TURN
• Actualización de Matrix.org sobre el descubrimiento de transporte de Element Call 0.24
• Especificación de la API cliente-servidor de Matrix, incluido el punto final de credenciales TURN.