How to Set Up a Matrix Coturn TURN/STUN Server for Audio and Video Calls

A current Matrix calling change affects discovery, but not Coturn’s TURN credentials or ports. In its August 21, 2026 update, Matrix.org reported that Element Call 0.24 deprecated discovery of MatrixRTC transports through the homeserver’s /.well-known/matrix/client file. Standalone Element Call deployments should support the MatrixRTC transports endpoint; Element Web/Desktop and Element X were keeping the old discovery method as a fallback while clients transition. This is separate from classic TURN setup.

This guide configures Coturn for Synapse’s TURN service, which supplies temporary ICE credentials to clients using traditional WebRTC calls. Current Element Call and MatrixRTC group calls use a LiveKit Selective Forwarding Unit (SFU) and a MatrixRTC authorization service. Coturn alone does not replace those components. If your goal is self-hosted Element Call, use the LiveKit path described in the official Element Call guide; add Coturn only if your chosen media architecture needs a separate TURN service.

Choose the right calling path first

For MatrixRTC on Synapse, the current Element Call self-hosting guide uses matrix_rtc.transports and enables the homeserver transport registry through the documented experimental feature flag. The Matrix.org 2026 notice says this discovery change matters most to standalone Element Call deployments; other admins could prepare the endpoint while supported clients retained a fallback. Check the guide for the clients and Synapse release you actually run.

What Coturn does

STUN lets a WebRTC client discover the public-facing network address it can advertise. TURN relays media when two clients cannot establish a direct connection through their routers or firewalls. Coturn implements both services. Without a reachable relay, a call may ring but stay on “Connecting” when participants are on restrictive or unrelated networks.

A TURN server needs a public IP address, or a NAT gateway with a public IP and correct forwarding rules. A private-only server cannot act as an Internet relay for remote Matrix users. For a small Synapse deployment, you can install Coturn on the homeserver or use a separate public host. A separate host provides clearer firewall boundaries and independent scaling; a same-host install is simpler, but requires careful firewall rules so the relay does not expose private services.

1. Install Coturn and prepare a shared secret

On Debian or Ubuntu, install the distribution package:

sudo apt update
sudo apt install coturn

The package supplies a systemd service and the main configuration file is commonly /etc/turnserver.conf. Other distributions use their own package name, service management, and configuration path.

Generate a strong, private secret. For example:

openssl rand -hex 32

Use the same secret in Coturn and Synapse. Treat it like a password: do not reuse an example value from documentation, commit it to a public repository, or include it in a public bug report. If your Synapse version supports turn_shared_secret_path, you can store the secret in a protected file instead of inline in YAML. Synapse added that setting in version 1.116.0; check your deployed version before using it.

2. Configure Coturn for authenticated relay

Edit /etc/turnserver.conf and set the service name and shared-secret authentication. Replace the domain and secret placeholders:

listening-port=3478
tls-listening-port=5349

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_THE_SAME_RANDOM_SECRET
realm=turn.example.org

min-port=49152
max-port=65535

no-tcp-relay
no-multicast-peers
user-quota=12
total-quota=1200

syslog

use-auth-secret enables the time-limited TURN credential mechanism that Synapse uses. Do not configure anonymous access or expose an open relay. The quota values above are a starting point drawn from Synapse’s Coturn guidance; adjust them to your expected user count and capacity. no-tcp-relay prevents clients from asking the relay to connect to arbitrary TCP destinations; it does not mean you must disable TCP as a client-to-TURN transport.

TURN can be abused as a relay toward internal or sensitive network addresses. Apply the complete denied-peer address ranges in the current Synapse Coturn security example, including ranges relevant to your IPv4 and IPv6 networks. Review the rules before copying them if users legitimately need to reach private network peers. Also keep Coturn patched and monitor its logs and quotas.

Set the public address when Coturn is behind NAT

If the TURN host sits behind a router, add its public address to the configuration so Coturn advertises a reachable relay address:

external-ip=YOUR_PUBLIC_IPV4
listening-ip=YOUR_PRIVATE_IPV4

Replace the sample values with the actual addresses; the listening address is optional if Coturn already binds to the correct interface. Forward the TURN listener and relay range from the router to this server. A mismatched external address is a common cause of calls that work on the same LAN but fail between different networks.

3. Open the listener and relay ports

Allow the ports that match your Coturn configuration in both the host firewall and any cloud firewall or router:

• TCP and UDP 3478 for the usual TURN listener.
• UDP 49152–65535 for the default relay range shown above. If you choose a smaller range, configure the same range in Coturn and the firewall.
• TCP 5349 for TURN over TLS, and UDP 5349 only if you enable and intend to offer DTLS.

For UFW, a basic UDP/TCP listener and UDP relay rule set can look like this:

sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 49152:65535/udp

Add the 5349 rules only when the corresponding TLS or DTLS listener is configured and advertised. Check your provider’s security group too; a host-level UFW rule cannot override a blocked cloud ingress rule. Do not publish the Coturn administrative control interface to the Internet.

4. Configure Synapse to issue Coturn credentials

Add the following TURN settings to the active Synapse configuration, usually homeserver.yaml. The hostname must resolve publicly to the TURN host:

turn_uris:
  - "turn:turn.example.org:3478?transport=udp"
  - "turn:turn.example.org:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_THE_SAME_RANDOM_SECRET"
turn_user_lifetime: 1h
turn_allow_guests: true

The first two URIs advertise ordinary TURN transports on port 3478. If TLS is configured and tested, you can also advertise a URI such as turns:turn.example.org:5349?transport=tcp. Do not advertise a turns: URI unless the certificate, listener, firewall, and client compatibility are all in place. Coturn’s TLS certificate and private key are set with cert and pkey in its config.

Set turn_allow_guests according to your room and guest policy. Enabling it can allow unauthenticated guest users to request TURN credentials, which may be necessary for guest calls but can increase abuse risk. Disabling it may make calls unreliable for guests. Use monitoring and quotas either way.

Restart Coturn and Synapse after changing their files:

sudo systemctl restart coturn
sudo systemctl restart matrix-synapse

Use your actual Synapse systemd unit name if it differs. Reload or restart affected clients; Synapse’s TURN settings are refreshed periodically, so a client may not see a change immediately.

Should you enable TURN over TLS?

Start with UDP/TCP TURN on 3478 and confirm that a relay candidate works. Add TURN over TLS only if your users’ networks need it, such as corporate firewalls that allow TLS-like traffic but block normal UDP. TLS broadens connectivity, but it adds certificate renewal, another listener, and client compatibility checks.

There is a Matrix-specific caveat: the current Synapse Coturn guide warns that TLS/DTLS with Let’s Encrypt certificates does not work with Matrix clients using Chromium’s WebRTC library, including Element Android and iOS as stated in that guide. Verify compatibility for your client versions before publishing a TLS URI. The same guide recommends setting up the basic service first and adding TLS/DTLS afterward.

5. Verify credentials and test from an outside network

First check that Coturn is running and review its logs:

sudo systemctl status coturn
sudo journalctl -u coturn -f

Then, from an authenticated Matrix client session, inspect the request to Synapse’s current Client-Server API endpoint, /_matrix/client/v3/voip/turnServer. A successful response should include a username, password, time-to-live, and the TURN URIs you configured. Do not share that response publicly; the credentials are temporary access tokens for your relay.

Use the official WebRTC Trickle ICE sample to test with a username and password returned by Synapse. Add your TURN URI and credentials, run the ICE gathering test, and look for a candidate whose type is relay. A server that merely responds to STUN may show a server-reflexive candidate but still fail to relay media. Test from a mobile connection or a network outside your LAN, then place an actual call between participants on different networks.

Diagnose common failures

• No TURN credentials appear: check that Synapse loaded the right configuration, restarted successfully, and has the shared secret set. Inspect the request response for /voip/turnServer.
• Credentials appear but no relay candidate forms: verify TCP/UDP 3478, the advertised hostname, the secret match, Coturn logs, and the UDP relay range through every firewall.
• Calls work on one LAN but fail across networks: inspect external-ip, port forwarding, and the return route. Coturn must advertise the public address clients can reach.
• Calls connect only when TLS is disabled: confirm the certificate chain, TLS listener, advertised turns: URI, and client-specific compatibility.
• Traditional calls work but Element Call does not: check the MatrixRTC/LiveKit transport setup separately. A successful Coturn test does not verify the LiveKit SFU or MatrixRTC authorization service.

For browser clients, the browser’s WebRTC diagnostics can show whether media selected a relay candidate. For MatrixRTC, verify that Synapse publishes the transport endpoint and that the LiveKit WebSocket and authorization routes are reachable. Test both the current endpoint and any documented discovery fallback required by the clients you support.

Configuration references

• Synapse: Configuring a TURN server
• Synapse: Coturn installation, security, NAT, and TLS configuration
• Synapse configuration reference for TURN and MatrixRTC
• Coturn’s official turnserver.conf example
• Element Call: MatrixRTC self-hosting guide
• LiveKit deployment and TURN configuration
• Matrix.org update on Element Call 0.24 transport discovery
• Matrix Client-Server API specification, including the TURN credentials endpoint