TURN server

The reemo-infra role can deploy a TURN server (based on coturn) that relays WebRTC connections when a direct link between the client and the agent cannot be established. coturn provides both the STUN and TURN functions. This service is not deployed by default.

See also

TURN concept — Purpose of the TURN relay and use cases.

Enabling

To enable the TURN server, set both options to true:

TURN_ENABLED: true
TURN_OVERRIDE: true

  • TURN_ENABLED: deploys the coturn service (false by default).

  • TURN_OVERRIDE: enables TURN usage on the API side, which then hands TURN credentials to WebRTC clients. Technically, this option sets API_TURN_ENABLED (false by default). Despite its name, it is not an “override” but the switch that turns TURN on for the API.

Optional settings

These options are not required for a default setup:

  • TURN_PORT: TCP and UDP listening port of the relay (58200 by default).

  • TURN_REALM: coturn realm used for authentication; falls back to reemo.io on the container side when left empty.

Server placement

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

  • TURN1_NODE / TURN1_IP: Swarm node and public IP address of the first TURN server. When left empty, the single Swarm node and its address are detected automatically.

  • TURN2_NODE / TURN2_IP: second TURN server, optional, for redundancy.

TURN1_NODE and TURN1_IP must be set together (same for TURN2).

Dedicated servers

For a dedicated deployment, place the machines in the turn_manager inventory group: the relay then runs on a Swarm separate from the INFRA environment. In that case, TURN1_IP and the authentication secret must be set in the inventory (see Authentication).

The TURN_DEDICATED variable reflects this mode: it is computed automatically (true as soon as the turn_manager group is non-empty) and therefore does not need to be set. The role uses it to place secret management on the right side, make inventory values mandatory, and disable TURN node auto-detection.

Authentication

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

  • TURN_AUTH_MODE: secret (default, ephemeral credentials derived from an HMAC secret) or static (fixed credentials).

  • TURN_SECRET: HMAC secret shared between the API and the TURN server (secret mode).

  • TURN_USERNAME / TURN_PASSWORD: fixed credentials (static mode).

In all-in-one mode (infra_manager group, a single Swarm), TURN_SECRET and TURN_PASSWORD left empty are generated on the first deployment.

Important

In a split architecture (api_manager / portal_manager groups on separate Swarms) or in dedicated mode (turn_manager), the secret must be identical across all environments. You must therefore set TURN_SECRET (secret mode) or TURN_PASSWORD (static mode) in the inventory, otherwise the deployment fails. Auto-generation would produce different values from one Swarm to another.

Point to an external TURN server

Instead of deploying coturn, you can point the API at an existing TURN server: one the customer hosts themselves, or a third-party service such as Cloudflare. In that case, do not set TURN_ENABLED (no coturn is installed) and set the API-side variables directly:

API_TURN_ENABLED: true
API_TURN1_SERVER: "turn.example.com"
API_TURN1_PORT: "443"
API_TURN1_USER: "user"
API_TURN2_SERVER: "turn.example.com"
API_TURN2_PORT: "443"
API_TURN2_USER: "user"
TURN_PASSWORD: "password"

  • API_TURN_ENABLED: enables the API handing TURN credentials to clients.

  • API_TURN1_SERVER / API_TURN1_PORT / API_TURN1_USER: host, port, and user of the external TURN server (same with API_TURN2_* for a second server).

  • TURN_PASSWORD: shared password; it is stored as a Docker secret and read by the API.

Note

The API_ prefix is not decorative: these variables are injected as-is into the API container, the micro-service that hands TURN credentials to clients. Keep it for API_TURN1_SERVER / API_TURN1_PORT / API_TURN1_USER. The password is the exception: set TURN_PASSWORD (no prefix), because it travels through a Docker secret — API_TURN1_PASSWORD is overridden with the path to that secret anyway.

Important

A TURN set here (in the inventory) takes precedence over TURN servers configured manually in the interface and assigned to organizations. To leave that choice to organizations, do not set any TURN in the inventory. See TURN concept.

Secret rotation

You can rotate the TURN secret without reinstalling the service. Rotation creates a new value, applies it to both the TURN server and the API, then restarts the affected services.

TURN_SECRET_ROTATE: false
TURN_PASSWORD_ROTATE: false

  • TURN_SECRET_ROTATE: set this option to true for a single deployment to rotate the HMAC secret (secret mode).

  • TURN_PASSWORD_ROTATE: same principle for the password (static mode).

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

In a split or dedicated architecture, set the new value in the inventory first: rotation reuses that value, identical across all environments. In all-in-one mode, a new value is generated automatically. Set the option back to false once rotation is done.