TURN¶

A TURN server makes WebRTC connections more reliable when a direct link between the client and the Reemo agent cannot be established. It acts as a media relay: the audio/video stream and data travel through the server instead of peer to peer.

Reemo’s TURN server is based on coturn, which provides both the STUN and TURN functions: a single service covers both roles. This component is optional and not deployed by default.

What TURN is for¶

A WebRTC connection first tries to establish the most direct path possible between the two peers, using the ICE protocol:

Direct connection: both peers communicate peer to peer, with no intermediary.
STUN: helps each peer discover its public address to traverse a simple NAT.
TURN: relays the entire stream when no direct path is possible.

coturn answers both STUN and TURN requests: the same server covers both steps.

On most networks, STUN is enough. However, some contexts prevent any direct link:

Symmetric NAT on the client side or the agent side.
Corporate firewall blocking UDP traffic or peer-to-peer streams.
Network policies that only allow outbound traffic to standard ports (443).

In these situations, the TURN server provides a fallback path: the WebRTC stream is relayed through the server, which guarantees the session can be established at the cost of bandwidth usage on the relay.

Two ways to use TURN in Reemo¶

TURN server deployed by the reemo-infra role: the role installs and configures coturn (STUN + TURN) in your infrastructure. See TURN server.
TURN servers declared from the interface: you can register existing TURN servers from the Administration area, whether self-hosted by you or provided by a third-party service (for example Cloudflare), then assign them to organizations. See TURN relays.

Important

TURN servers set in the inventory (reemo-infra role or the API_TURN* variables) take precedence over those configured manually in the interface and assigned to organizations. To let organizations choose their TURN from the interface, do not set any TURN in the inventory.

Authentication¶

Whatever the setup, the API hands clients the credentials they need to authenticate against the relay, which then validates those credentials before relaying the stream.

Two authentication modes are available:

secret (recommended): ephemeral, time-limited credentials derived from a shared secret (HMAC). The secret is never sent to the client.
static: fixed credentials made of a username and a password, identical for all clients.

Deployment modes¶

When deployed by the reemo-infra role, the TURN server can be installed in two ways:

Colocated: the relay runs on the same cluster as the INFRA environment. Simple to set up, suitable for small deployments.
Dedicated: the relay runs on dedicated machines (turn_manager inventory group), on a separate Swarm. Recommended when relayed traffic is heavy or must be isolated from the platform core.

Up to two TURN servers can be declared for redundancy.