Serveur TURN

Le rôle reemo-infra peut déployer un serveur TURN (basé sur coturn) qui relaie les connexions WebRTC lorsque la liaison directe entre le client et l’agent ne peut pas s’établir. coturn assure à la fois les fonctions STUN et TURN. Ce service n’est pas déployé par défaut.

Voir aussi

Concept TURN — Rôle du relais TURN et cas d’usage.

Activation

Pour activer le serveur TURN, passez les deux options à true :

TURN_ENABLED: true
TURN_OVERRIDE: true

  • TURN_ENABLED : déploie le service coturn (false par défaut).

  • TURN_OVERRIDE : active l’utilisation de TURN au niveau de l’API, qui distribue alors les identifiants TURN aux clients WebRTC. Techniquement, cette option définit API_TURN_ENABLED (false par défaut). Malgré son nom, il ne s’agit pas d’un « écrasement » mais bien de l’activation de TURN côté API.

Réglages optionnels

Ces options ne sont pas nécessaires pour un fonctionnement par défaut :

  • TURN_PORT : port d’écoute TCP et UDP du relais (58200 par défaut).

  • TURN_REALM : realm coturn utilisé pour l’authentification ; repli sur reemo.io côté conteneur si la valeur est vide.

Placement des serveurs

TURN1_NODE: ""
TURN1_IP: ""
TURN2_NODE: ""
TURN2_IP: ""

  • TURN1_NODE / TURN1_IP : nœud Swarm et adresse IP publique du premier serveur TURN. Laissés vides, le nœud unique du Swarm et son adresse sont déduits automatiquement.

  • TURN2_NODE / TURN2_IP : second serveur TURN, optionnel, pour la redondance.

TURN1_NODE et TURN1_IP se renseignent ensemble (idem pour TURN2).

Serveurs dédiés

Pour un déploiement dédié, placez les machines dans le groupe d’inventaire turn_manager : le relais tourne alors sur un Swarm distinct de l’environnement INFRA. Dans ce cas, TURN1_IP et le secret d’authentification doivent être renseignés dans l’inventaire (voir Authentification).

La variable TURN_DEDICATED traduit ce mode : elle est calculée automatiquement (true dès que le groupe turn_manager est non vide) et n’a donc pas à être renseignée. Le rôle s’en sert pour placer la gestion du secret du bon côté, rendre les valeurs d’inventaire obligatoires et désactiver l’auto-détection du nœud TURN.

Authentification

TURN_AUTH_MODE: "secret"
TURN_SECRET: ""
TURN_USERNAME: "reemo"
TURN_PASSWORD: ""

  • TURN_AUTH_MODE : secret (par défaut, identifiants éphémères dérivés d’un secret HMAC) ou static (identifiants fixes).

  • TURN_SECRET : secret HMAC partagé entre l’API et le serveur TURN (mode secret).

  • TURN_USERNAME / TURN_PASSWORD : identifiants fixes (mode static).

En mode tout-en-un (groupe infra_manager, un seul Swarm), TURN_SECRET et TURN_PASSWORD laissés vides sont générés au premier déploiement.

Important

En architecture séparée (groupes api_manager / portal_manager sur des Swarms distincts) ou en mode dédié (turn_manager), le secret doit être identique dans tous les environnements. Vous devez donc renseigner TURN_SECRET (mode secret) ou TURN_PASSWORD (mode static) dans l’inventaire, sinon le déploiement échoue. L’auto-génération produirait des valeurs différentes d’un Swarm à l’autre.

Pointer vers un serveur TURN externe

Au lieu de déployer coturn, vous pouvez diriger l’API vers un serveur TURN existant : celui que le client héberge lui-même, ou un service tiers comme Cloudflare. Dans ce cas, ne définissez pas TURN_ENABLED (aucun coturn n’est installé) et renseignez directement les variables côté API :

API_TURN_ENABLED: true
API_TURN1_SERVER: "turn.exemple.com"
API_TURN1_PORT: "443"
API_TURN1_USER: "utilisateur"
API_TURN2_SERVER: "turn.exemple.com"
API_TURN2_PORT: "443"
API_TURN2_USER: "utilisateur"
TURN_PASSWORD: "mot-de-passe"

  • API_TURN_ENABLED : active la distribution des identifiants TURN aux clients par l’API.

  • API_TURN1_SERVER / API_TURN1_PORT / API_TURN1_USER : hôte, port et utilisateur du serveur TURN externe (idem API_TURN2_* pour un second serveur).

  • TURN_PASSWORD : mot de passe partagé ; il est stocké en secret Docker et lu par l’API.

Note

Le préfixe API_ n’est pas décoratif : ces variables sont injectées telles quelles dans le conteneur API, le micro-service qui transmet les identifiants TURN aux clients. Conservez-le pour API_TURN1_SERVER / API_TURN1_PORT / API_TURN1_USER. Le mot de passe fait exception : renseignez TURN_PASSWORD (sans préfixe), car il transite par un secret Docker — API_TURN1_PASSWORD est de toute façon remplacé par le chemin de ce secret.

Important

Un TURN renseigné ici (dans l’inventaire) prévaut sur les serveurs TURN configurés manuellement dans l’interface et assignés aux organisations. Pour laisser ce choix aux organisations, ne renseignez pas de TURN dans l’inventaire. Voir Concept TURN.

Rotation des secrets

Vous pouvez faire tourner le secret TURN sans réinstaller le service. La rotation crée une nouvelle valeur, l’applique au serveur TURN et à l’API, puis redémarre les services concernés.

TURN_SECRET_ROTATE: false
TURN_PASSWORD_ROTATE: false

  • TURN_SECRET_ROTATE : passez cette option à true le temps d’un déploiement pour faire tourner le secret HMAC (mode secret).

  • TURN_PASSWORD_ROTATE : même principe pour le mot de passe (mode static).

ansible-playbook -i inventory.yml playbooks/reemo-infra.yml --tags secrets_turn,turn,api --extra-vars "TURN_SECRET_ROTATE=true"

En architecture séparée ou dédiée, renseignez d’abord la nouvelle valeur dans l’inventaire : la rotation réutilise cette valeur, identique dans tous les environnements. En mode tout-en-un, une nouvelle valeur est générée automatiquement. Repassez l’option à false une fois la rotation effectuée.