Screen-Share Relay (TURN)

The built-in WebRTC technician screen-share connects the operator's browser directly to the target machine whenever the network allows it. When the two sides sit behind restrictive NAT or firewalls and a direct path can't be formed, Athena can route the media through a coturn TURN relay — a well-known, firewall-deterministic path that keeps screen-share working. This page covers configuring that relay and standing one up on a managed Linux host with a single click.

How the relay fits in#

When a screen-share session starts, the browser and the target agent attempt to negotiate the most direct media path available. If a relay is configured, the server mints short-lived relay credentials and hands both sides the relay address so media can fall back to the relay when a direct route fails. The relay never sees session content in the clear beyond forwarding the encrypted media stream — it exists to guarantee connectivity, not to inspect traffic.

Running the relay involves two independent pieces:

• Relay settings — the address, port, transport, and shared secret Athena uses to mint relay credentials. These are saved in the console under Settings → Agents → Remotes → WebRTC Screen Share.
• The relay host — a machine running coturn that matches those settings. You can point at an existing coturn deployment, or let Athena provision one onto a managed Linux agent.

Configuring relay settings#

Under Settings → Agents → Remotes → WebRTC Screen Share, enable the integration and fill in the relay endpoint. The individual fields are composed into a single turn:host:port?transport=… URI when you save:

One-click relay provisioning#

Rather than build a relay host by hand, Athena can stand up coturn on a machine you already manage. On the same WebRTC Screen Share settings screen, an Admin-only section lets you pick an online Linux agent and click Configure relay. Athena renders a coturn setup script from your saved relay settings and runs it on the selected agent over the existing secure agent channel — there is no SSH, no extra port to open, and no separate credential to manage.

Before provisioning, make sure that:

• You have saved the relay host and static auth secret — the script is built from these; provisioning is refused if they are blank.
• The target is a Linux agent and is online. Windows agents and offline agents are rejected.
• The agent can reach a package source to install coturn if it isn't already present (relevant in air-gapped environments — see Air-Gapped Operation).

The provisioning run is idempotent and, on the target host, will:

• Install coturn if it isn't already installed, then enable its service flag.
• Write /etc/turnserver.conf with your host and secret, the fixed media port range 49160–49200, and secret-based authentication. This file is overwritten on every run so a settings change takes effect.
• Open the relevant UDP ports in the host firewall only if ufw is already active (it never enables the firewall for you).
• Enable and restart the coturn service so the configuration is live.

Success is confirmed by an explicit health marker the script emits only when the coturn service is actually running — a zero exit code alone is not treated as success. If the marker isn't reported within the provisioning window, the action is reported as failed. When it succeeds, Athena automatically runs a Test Connection against the new relay and shows the result inline.

Verifying with Test Connection#

The Test Connection button on the WebRTC Screen Share settings probes the configured relay and reports whether it is reachable and whether the shared secret is accepted:

REST API#

Provisioning is also available over the REST API for scripted rollouts. The relay host and secret come from the saved settings, so there is no request body:

The response body reports the outcome:

PowerShell#

The Athena PowerShell module exposes provisioning as a single cmdlet so you can stand up (or re-apply) a relay from a script or the pipeline:

# Provision the relay onto a specific Linux agent
Install-AthenaRelay -AgentId "12345678-1234-1234-1234-123456789012"

# Or pipe the target in from Get-AthenaAgent
Get-AthenaAgent -Hostname "relay-host" | Install-AthenaRelay

The cmdlet returns the same result fields as the API (success, marker found, output, and the follow-up Test Connection), and re-running it simply re-applies the current settings — handy after you change the relay host, port, or secret.

Auditing#

Every provisioning action is written to the audit log with the target agent, the initiating user, the relay host and port, whether the success marker was found, and the overall result. The shared secret and the setup script itself are never recorded — only the redacted metadata is stored — so the audit trail is safe to forward to a SIEM.