Comment configurer un serveur TURN externe pour Jitsi derrière un NAT

Point essentiel : un serveur TURN externe doit être configuré comme solution de repli pour les clients ne pouvant établir de connexion WebRTC fonctionnelle en raison d’un NAT ou d’un pare-feu restrictif. Il ne remplace pas le pont vidéo Jitsi (JVB) lors de réunions multipartites classiques. Si votre serveur Jitsi est lui-même situé derrière un NAT, vous devez impérativement rendre le JVB accessible depuis Internet, généralement sur le port UDP 10000, ou configurer correctement son adresse IP publique.

Pour les déploiements Jitsi actuels, la configuration la plus simple consiste généralement en un hôte coturn accessible publiquement avec un nom DNS tel que `example.com` turn.example.com, des identifiants temporaires fournis par Prosody via la XEP-0215, et l'utilisation de TURN sur UDP/TCP ainsi que de TURN sur TLS pour les réseaux à accès restreint. La documentation TURN actuelle de Jitsi recommande explicitement l'utilisation d'identifiants dynamiques plutôt que l'intégration d'un nom d'utilisateur et d'un mot de passe permanents dans la configuration du navigateur. Consultez la documentation officielle de configuration TURN de Jitsi .

Quand un serveur TURN externe est la solution appropriée

Utilisez TURN lorsque certains participants peuvent accéder à la page web Jitsi mais ne peuvent pas établir de connexion média fiable, notamment depuis les réseaux d'entreprise, le Wi-Fi d'hôtel, les campus, les opérateurs mobiles, les VPN ou d'autres environnements bloquant ou filtrant fortement le protocole UDP. TURN est également utile pour les appels Jitsi individuels lorsque la connectivité directe entre pairs est impossible.

N'utilisez pas TURN comme première solution pour corriger une configuration incorrecte de Jitsi Videobridge. Le guide officiel Jitsi pour Debian/Ubuntu indique que lorsque le serveur est derrière un NAT, le routeur doit rediriger les ports nécessaires et le pont peut nécessiter une correspondance explicite entre les adresses IP locales et publiques. Par défaut, les ports importants pour Jitsi sont TCP 443 et UDP 10000. Consultez le guide d'auto-hébergement Jitsi pour Debian/Ubuntu avant d'ajouter TURN.

Étape 1 : Préparer un serveur TURN public et un DNS

La topologie la plus simple consiste en une machine virtuelle ou un serveur dédié doté d'une adresse IP publique. Créez un enregistrement A ou AAAA pointant turn.example.comvers cet hôte. Un nom d'hôte dédié est particulièrement utile si vous proposez ultérieurement le protocole TURN sur TLS, car le certificat doit correspondre au nom d'hôte utilisé par les clients.

Si l'hôte TURN se trouve derrière un NAT, coturn doit connaître l'adresse publique à annoncer. Coturn prend en charge le external-ipmappage, notamment les paires publique/privée external-ip=203.0.113.10/192.168.1.10. Sa documentation précise également que les ports de relais doivent être mappés de manière cohérente à travers le NAT. Consultez l' exemple de configuration officiel de coturn .

Étape 2 : Installer coturn

Sur un système Debian ou Ubuntu compatible, installez coturn depuis le dépôt de la distribution :

sudo apt update
sudo apt install coturn

Les versions des paquets varient selon la version du système d'exploitation ; ne copiez donc pas un numéro de version à partir d'une capture d'écran ou d'un autre serveur. Après l'installation, vérifiez que l'unité de service existe et que le paquet est bien installé turnserver.

Étape 3 : Configurer coturn pour l’authentification par secret partagé

Pour Jitsi, une configuration de production pratique utilise le mécanisme de secret partagé de coturn afin que Prosody puisse générer des identifiants TURN temporaires. Utilisez le même secret des deux côtés. Voici un point de départ minimal :

listening-port=3478
tls-listening-port=5349
realm=turn.example.com

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_A_LONG_RANDOM_SECRET

min-port=49160
max-port=49200

no-multicast-peers
no-cli

Si l'hôte TURN se trouve derrière un NAT, ajoutez le external-ipmappage approprié. Si vous activez TURN sur TLS, configurez- certle pkeyavec un certificat de confiance turn.example.com. La documentation officielle du conteneur coturn explique que TURN utilise une plage de ports de relais pour les médias et que cette plage peut être réduite avec les options `--relay-port` min-portet `--relay-port`. max-portConsultez la documentation officielle de coturn pour Docker afin de comprendre le même comportement des ports de relais.

Étape 4 : Ouvrez les ports d'écoute et de relais

Une erreur fréquente consiste à n'ouvrir que les ports 3478 ou 5349 sans tenir compte de la plage de relais. Le serveur Coturn accepte la connexion TURN initiale, mais les médias relayés utilisent des ports de relais dédiés. Si vous avez choisi cette option 49160-49200, autorisez cette même plage à travers le pare-feu hôte, le groupe de sécurité cloud et tout NAT en amont.

sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 5349/tcp
sudo ufw allow 49160:49200/udp

Pour une compatibilité maximale avec les réseaux d'entreprise sécurisés, le guide TURN de Jitsi décrit la configuration de TURN via TLS sur le port TCP 443. Cela peut nécessiter un nom d'hôte TURN dédié et, lorsque le HTTPS partage la même adresse IP publique, un multiplexage SNI TLS. Ne déplacez pas TURN vers le port 443 sans savoir quel service l'utilise déjà.

Étape 5 : Configurer Jitsi pour annoncer le service TURN externe

Sur un déploiement actuel du paquet Jitsi Debian/Ubuntu, Prosody utilise un système de fichiers mod_external_servicespour publier les informations STUN/TURN aux clients. L'exemple Prosody fourni par Jitsi utilise un external_service_secretsystème de fichiers et une external_servicestable avec des paramètres spécifiques secret = true. Le secret partagé doit correspondre à celui de coturn static-auth-secret.

external_service_secret = "REPLACE_WITH_THE_SAME_LONG_RANDOM_SECRET";

external_services = {
    { type = "stun", host = "turn.example.com", port = 3478 },
    { type = "turn", host = "turn.example.com", port = 3478,
       transport = "udp", secret = true, ttl = 86400, algorithm = "turn" },
    { type = "turns", host = "turn.example.com", port = 5349,
       transport = "tcp", secret = true, ttl = 86400, algorithm = "turn" }
};

Conservez les modules existants et les paramètres spécifiques au site dans votre fichier Prosody généré par Jitsi ; ne remplacez pas l’intégralité du fichier par l’extrait ci-dessus. Le nom exact du fichier suit généralement votre domaine de déploiement sous `<nom_domaine>` /etc/prosody/conf.d/. L’exemple de configuration Jitsi d’origine est disponible dans le dépôt Jitsi officiel .

Si vous utilisez le déploiement Docker officiel, privilégiez l'utilisation des variables d'environnement documentées plutôt que la modification manuelle des fichiers Prosody générés. La documentation Docker actuelle expose les variables suivantes : TURN_CREDENTIALS` TURN_HOST< input type=" TURN_PORTfile ">` TURN_TRANSPORT, TURNS_HOST...TURNS_PORT

Étape 6 : Redémarrez et validez les services

Après avoir modifié le coturn, redémarrez-le et vérifiez son état :

sudo systemctl restart coturn
sudo systemctl status coturn
sudo ss -lntup | grep -E '3478|5349'

Après avoir modifié la configuration de Prosody, vérifiez sa syntaxe si votre package Prosody inclut un outil de vérification, puis redémarrez Prosody. Selon les modifications apportées à Jitsi, il peut également être nécessaire de redémarrer les services Jitsi concernés.

sudo prosodyctl check config
sudo systemctl restart prosody

Un statut de service coturn clair indique seulement que le démon est en cours d'exécution. Cela ne prouve pas que les identifiants correspondent, que la portée du relais est accessible ou qu'un navigateur peut obtenir un relais candidat.

Étape 7 : Vérifier que TURN peut effectivement relayer les médias

Un test effectué depuis le même réseau local ne suffit pas. Utilisez au moins un client sur un réseau différent, idéalement une connexion mobile ou un réseau connu pour restreindre le protocole UDP. Dans les diagnostics WebRTC du navigateur, recherchez un candidat ICE de type « relais » relay. Un candidat relais indique que le navigateur a obtenu avec succès des informations d'identification TURN et créé une allocation TURN.

Surveillez également les journaux coturn pendant que l'utilisateur de test se connecte. Vous devriez observer des allocations authentifiées et du trafic de relais lorsque TURN est sélectionné. En cas d'échec d'authentification, comparez les journaux coturn static-auth-secretavec le secret d'identification TURN de Prosody ou de Docker. Si les allocations réussissent mais que le transfert média échoue toujours, vérifiez le pare-feu du port de relais et le mappage NAT.

N'utilisez pas TURN uniquement pour prouver l'existence du serveur, sauf si vous avez un objectif de test précis. En conditions normales, ICE choisit le chemin optimal. Un déploiement réussi peut donc comporter de nombreuses réunions qui n'ont jamais besoin de TURN.

Étape 8 : Séparer la configuration NAT JVB du dépannage TURN

C’est à ce stade que l’on évite le plus de temps perdu en dépannage. Un serveur Jitsi derrière un NAT nécessite toujours que l’accessibilité publique du pont soit correctement configurée. Le guide de démarrage rapide de Jitsi indique que le pont se configure normalement automatiquement, mais si les appels importants échouent, vous pouvez ajouter un mappage statique ice4j.harvest.mappingsous/etc/jitsi/videobridge/jvb.conf :

ice4j {
  harvest {
    mapping {
      static-mappings = [
        {
          local-address = "192.168.1.20"
          public-address = "203.0.113.20"
        }
      ]
    }
  }
}

Redirigez le port UDP 10000 depuis le réseau public vers l'hôte JVB et assurez-vous que l'adresse publique est bien accessible aux clients distants. TURN peut être utile aux clients sur les réseaux restrictifs, mais ne doit pas servir à masquer une configuration NAT JVB défectueuse.

Liste de vérification pour le dépannage rapide

• Le nom d'hôte TURN ne se résout pas : corrigez le DNS avant de tester Jitsi.
• 3478/5349 écoutent localement mais pas à distance : inspectez le pare-feu hôte, le pare-feu cloud, le NAT du routeur et le filtrage du fournisseur.
• Échec de l'authentification : vérifiez que le secret partagé est identique dans coturn et dans la configuration Jitsi/Prosody.
• Un candidat relais apparaît mais le média échoue : vérifiez que la plage de ports relais configurée est ouverte de bout en bout.
• Seuls les appels multipartites échouent : vérifiez JVB UDP 10000 et la publicité d’adresse publique JVB.
• Seuls les réseaux d'entreprise échouent : ajoutez ou vérifiez TURN sur TLS, souvent sur TCP 443 le cas échéant.
• Les modifications apportées à Docker disparaissent après un redémarrage : configurez les .envvariables prises en charge plutôt que de modifier les fichiers générés à l’intérieur des conteneurs.

Voici à quoi ressemble un résultat correct

Une configuration fonctionnelle présente trois comportements observables. Premièrement, les utilisateurs ordinaires peuvent accéder directement au pont vidéo Jitsi sans TURN lorsque leur réseau le permet. Deuxièmement, les utilisateurs sur des réseaux restrictifs peuvent recevoir des identifiants TURN temporaires et obtenir un relaycandidat ICE. Troisièmement, coturn n'affiche les allocations authentifiées qu'en cas de besoin, au lieu de les diffuser systématiquement lors de chaque réunion.

Cette combinaison offre une solution de repli efficace sans transformer le serveur TURN en un goulot d'étranglement inutile en bande passante. Elle simplifie également le dépannage : les problèmes de NAT JVB restent des problèmes JVB, tandis que TURN résout le problème plus spécifique de la connectivité WebRTC lorsque les routes directes sont bloquées.