Pour les appels Matrix qui échouent lorsque les participants se trouvent sur des réseaux différents, déployez coturn sur un hôte disposant d'une adresse IP publique, activez ses identifiants TURN REST à durée de validité limitée et configurez Synapse avec le même secret partagé et les mêmes URI TURN. Autorisez ensuite le protocole d'écoute TURN et le relais UDP à travers chaque pare-feu. STUN peut aider les clients à découvrir les chemins réseau, mais TURN assure le relais des flux multimédias lorsqu'un chemin direct est impossible.
Cette configuration comprend un serveur Synapse auto-hébergé et un hôte TURN Debian ou Ubuntu distinct doté d'une adresse IPv4 publique statique. L'exemple utilise le serveur d'écoute par défaut de coturn sur le port 3478 et la plage de relais UDP par défaut 49152–65535. Remplacez le domaine, le secret et les chemins d'accès de l'exemple par les vôtres. Si coturn se trouve derrière un NAT, consultez la note relative au NAT ci-dessous ; un hôte public directement accessible est plus simple et plus fiable.
1. Indiquez un nom d'hôte TURN au serveur.
Créez un enregistrement DNS de type A turn.example.compointant vers l'adresse IPv4 publique de l'hôte coturn. Utilisez un nom d'hôte dédié afin que ses paramètres réseau et de certificat puissent être gérés indépendamment du service web Matrix. Ne publiez pas d'enregistrement AAAA sauf si coturn dispose d'une connectivité IPv6 fonctionnelle et des règles de pare-feu correspondantes ; une adresse IPv6 inaccessible peut amener certains clients à emprunter un chemin erroné.
La documentation TURN actuelle de Synapse indique que le service TURN nécessite une adresse IP publique. La NAT ne fonctionne que si la passerelle possède une adresse publique et redirige correctement les ports requis. La documentation précise que les configurations TURN peuvent néanmoins présenter des problèmes de fiabilité. Consultez la documentation de configuration TURN de Synapse .
2. Installez coturn et configurez le relais authentifié
Sur Debian ou Ubuntu, installez le paquet de distribution :
sudo apt update
sudo apt install coturn
Ouvrez le fichier /etc/turnserver.confavec un éditeur et configurez les paramètres essentiels ci-dessous. Générez un long mot de passe secret aléatoire à l'aide d'un gestionnaire de mots de passe ou d'un générateur cryptographique sécurisé. Saisissez ce mot de passe exact dans Synapse ultérieurement ; ne réutilisez pas un mot de passe utilisateur de Matrix et ne divulguez pas ce mot de passe dans un dépôt public.
listening-port=3478
fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_A_LONG_RANDOM_SECRET
realm=turn.example.com
server-name=turn.example.com
min-port=49152
max-port=65535
use-auth-secretet static-auth-secretactivez le mécanisme d'authentification REST TURN utilisé par Synapse pour émettre des identifiants temporaires. realmdoit correspondre au nom de domaine de votre service TURN. La plage de ports du relais est indépendante de celle du serveur d'écoute : les clients contactent le port 3478 pour demander une allocation, puis les médias utilisent les ports de relais alloués. La documentation de l'exemple de configuration coturn détaille les options d'écoute, de relais, de TLS et d'adresse IP externe ; les valeurs par défaut et les chemins d'accès du package de distribution peuvent différer.
Activez et démarrez le service, puis vérifiez son état :
sudo systemctl enable --now coturn
sudo systemctl status coturn
Si votre paquet comporte un paramètre d'activation distinct /etc/default/coturn, suivez les instructions de ce fichier avant de démarrer le service. Consultez les journaux sudo journalctl -u coturn -esi le service ne démarre pas.
3. Autoriser le trafic d'écoute et de relais
Autorisez le trafic UDP et TCP entrant sur le port 3478, ainsi que sur les ports UDP entrants 49152 à 65535, dans le pare-feu hôte et tout pare-feu de niveau fournisseur. Par exemple, avec UFW :
sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 49152:65535/udp
sudo ufw status
Limitez la portée du relais au strict minimum supporté par votre déploiement et assurez-vous qu'elle min-portcorresponde max-portà celle du pare-feu. Si vous activez un écouteur TLS, ouvrez également son port configuré et utilisez l' turns:URI et le certificat correspondants. L'utilisation de TLS sur la connexion TURN est optionnelle dans cet exemple simple ; les instructions Synapse précisent que les flux audio et vidéo WebRTC restent chiffrés même lorsque TURN utilise son écouteur UDP/TCP standard, tandis que la sécurité de la signalisation dépend de votre configuration HTTPS Matrix.
Pour un hôte derrière un NAT, configurez le mappage de coturn external-ip=PUBLIC_IP/PRIVATE_IPet redirigez le port 3478 ainsi que toute la plage de ports du relais vers l'hôte coturn, sans modifier les numéros de ports des relais externes. Par exemple, le port public 52000 du relais doit atteindre le port interne 52000. Synapse indique que le NAT peut toujours poser problème ; si vous ne pouvez pas rediriger une large plage UDP, il est généralement plus judicieux d'héberger coturn sur un VPS avec une adresse IP publique.
4. Connectez Synapse à coturn
Ajoutez les paramètres suivants au fichier de configuration Synapse actif, généralement homeserver.yaml. Faites correspondre le nom d'hôte, le port et le secret à la configuration coturn :
turn_uris:
- "turn:turn.example.com:3478?transport=udp"
- "turn:turn.example.com:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_A_LONG_RANDOM_SECRET"
turn_user_lifetime: 86400000
turn_allow_guests: false
La durée de vie est exprimée en millisecondes ; cet exemple demande à Synapse de fournir des identifiants valides pendant 24 heures. Configurez l’accès invité conformément à votre politique d’enregistrement ; il n’est pas nécessaire de l’activer uniquement pour les appels des utilisateurs enregistrés. Conservez une turn_shared_secretconfiguration privée et identique à celle de coturn static-auth-secret. N’ajoutez pas d’ stun:URI en remplacement de TURN : les deux protocoles ont des rôles liés mais distincts.
Redémarrez Synapse après avoir validé la syntaxe YAML :
sudo systemctl restart matrix-synapse.service
sudo systemctl status matrix-synapse.service
Les déploiements de conteneurs doivent mettre à jour la configuration Synapse montée et redémarrer le conteneur Synapse. Les clients peuvent avoir besoin de recharger ou d'actualiser la configuration de leur serveur ; Synapse indique que l'actualisation des paramètres TURN par les clients peut prendre jusqu'à une heure.
Vérifier un candidat au relais
Effectuez le test depuis un navigateur ou un appareil connecté à un réseau différent de celui du serveur TURN, par exemple un téléphone utilisant les données cellulaires. Dans un client Matrix basé sur un navigateur, examinez la requête authentifiée adressée au serveur d'accueil /_matrix/client/v3/voip/turnServer(les clients plus anciens peuvent utiliser l'ancienne /r0/méthode). La réponse doit inclure les URI TURN ainsi que les champs nom d'utilisateur/mot de passe temporaires ; la spécification Matrix définit la réponse d'authentification de ce point de terminaison.
Utilisez ces identifiants dans le test WebRTC Trickle ICE officiel , saisissez un serveur tel que `<serveur>` turn:turn.example.com:3478?transport=udp, et sélectionnez le test de relais si la page propose un filtrage par type de candidat. Un résultat positif inclut un candidat de type `<type>` relay. Enfin, effectuez un appel Matrix entre des appareils situés sur des réseaux distincts. Un appel qui sonne mais reste bloqué sur « Connexion en cours » indique souvent des ports de relais bloqués, une configuration NAT incorrecte ou des identifiants incompatibles ; consultez les journaux coturn et les notes de dépannage TURN de Synapse avant de modifier les paramètres d'appel non liés.
Pour le diagnostic du navigateur, Synapse recommande chrome://webrtc-internals/Chrome et about:webrtcFirefox. Si le relais candidat n'apparaît pas, vérifiez d'abord que le secret correspond exactement, puis contrôlez le port UDP 3478 et la plage complète de relais dans les pare-feu de l'hôte et du fournisseur. Le projet coturn documente les options de port et d'adresse IP externe dans sa documentation turnserver .