Set Up coturn for Reliable Matrix Voice and Video Calls
Configure coturn and Synapse with matching TURN credentials, open the required relay ports, and verify that Matrix clients can obtain relay candidates.
For Matrix calls that fail when participants are on different networks, deploy coturn on a host with a public IP, enable its time-limited TURN REST credentials, and configure Synapse with the same shared secret and TURN URIs. Then allow the TURN listener and UDP relay range through every firewall. STUN can help clients discover network paths, but TURN is the relay that carries media when a direct path cannot be established.
This setup fits a self-hosted Synapse homeserver and a separate Debian or Ubuntu TURN host with a static public IPv4 address. The example uses coturn's default listener on port 3478 and the default UDP relay range 49152–65535. Replace the example domain, secret, and paths with your own. If coturn is behind NAT, see the NAT note below; a directly reachable public host is simpler and more reliable.
Create a DNS A record such as turn.example.com that points to the coturn host's public IPv4 address. Use a dedicated hostname so that its network and certificate settings can be managed independently from the Matrix web service. Do not publish an AAAA record unless coturn has working IPv6 connectivity and the corresponding firewall rules; an unreachable IPv6 address can cause some clients to choose a path that fails.
Synapse's current TURN documentation says the TURN service needs a public IP endpoint. NAT can work only when the gateway has a public address and forwards the required ports correctly, and the documentation warns that NAT setups can still be unreliable. See the Synapse TURN setup documentation.
On Debian or Ubuntu, install the distribution package:
sudo apt update
sudo apt install coturn
Open /etc/turnserver.conf with an editor and configure the essential settings below. Generate a long random secret with a password manager or a cryptographically secure generator. Put that exact secret in Synapse later; do not reuse a Matrix user password or expose the secret in a public repository.
listening-port=3478
fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_A_LONG_RANDOM_SECRET
realm=turn.example.com
server-name=turn.example.com
min-port=49152
max-port=65535
use-auth-secret and static-auth-secret enable the TURN REST credential mechanism that Synapse uses to issue temporary credentials. realm should be a domain name for your TURN service. The relay port range is separate from the listener: clients contact port 3478 to request an allocation, then media uses allocated relay ports. The coturn example configuration documents listener, relay, TLS, and external-IP options; distribution package defaults and paths can differ.
Enable and start the service, then inspect its status:
sudo systemctl enable --now coturn
sudo systemctl status coturn
If your package has a separate enable flag in /etc/default/coturn, follow that file's instructions before starting the service. Check logs with sudo journalctl -u coturn -e if it does not start.
Allow inbound UDP and TCP on port 3478, plus inbound UDP ports 49152–65535, in the host firewall and any provider-level firewall. For example, with UFW:
sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 49152:65535/udp
sudo ufw status
Keep the relay range as narrow as your deployment can support, and make coturn's min-port and max-port match the firewall range. If you enable a TLS listener, open its configured port as well and use the matching turns: URI and certificate settings. TLS on the TURN connection is optional for this basic example; the Synapse instructions note that WebRTC voice and video media remains encrypted even when TURN uses its plain UDP/TCP listener, while signaling security depends on your Matrix HTTPS setup.
For a host behind NAT, configure coturn's external-ip=PUBLIC_IP/PRIVATE_IP mapping and forward both port 3478 and the entire relay range to the coturn host without changing the external relay port numbers. For example, a public relay port 52000 must reach internal port 52000. Synapse's guidance says NAT may still cause problems; if you cannot forward a broad UDP range, placing coturn on a public-IP VPS is usually a more practical choice.
Add the following settings to the active Synapse configuration file, usually homeserver.yaml. Match the hostname, port, and secret to the coturn configuration:
turn_uris:
- "turn:turn.example.com:3478?transport=udp"
- "turn:turn.example.com:3478?transport=tcp"
turn_shared_secret: "REPLACE_WITH_A_LONG_RANDOM_SECRET"
turn_user_lifetime: 86400000
turn_allow_guests: false
The lifetime value is in milliseconds; this example asks Synapse to issue credentials valid for 24 hours. Set guest access according to your registration policy; it is not required simply to enable calls for registered users. Keep turn_shared_secret private and identical to coturn's static-auth-secret. Do not add a stun: URI as a substitute for TURN: the two protocols serve related but different roles.
Restart Synapse after validating the YAML syntax:
sudo systemctl restart matrix-synapse.service
sudo systemctl status matrix-synapse.service
Container deployments must update the mounted Synapse configuration and restart the Synapse container instead. Clients may need to reload or refresh their server configuration; Synapse notes that clients can also take up to about an hour to refresh TURN settings.
Test from a browser or device on a different network from the TURN server, such as a phone using cellular data. In a browser-based Matrix client, inspect the authenticated homeserver request to /_matrix/client/v3/voip/turnServer (older clients may use the legacy /r0/ path). The response should include TURN URIs and temporary username/password fields; the Matrix specification defines this endpoint's credential response.
Use those credentials in the official WebRTC Trickle ICE test, enter a server such as turn:turn.example.com:3478?transport=udp, and select relay testing if the page offers candidate type filtering. A successful result includes a candidate whose type is relay. Finally, place a Matrix call between devices on separate networks. A call that rings but remains at “connecting” often points to blocked relay ports, a wrong NAT mapping, or mismatched credentials; check coturn logs and Synapse's TURN troubleshooting notes before changing unrelated call settings.
For browser diagnostics, Synapse recommends chrome://webrtc-internals/ in Chrome and about:webrtc in Firefox. If the relay candidate does not appear, first confirm the secret matches exactly, then verify UDP 3478 and the full relay range in both host and provider firewalls. The coturn project documents the port and external-IP options in its turnserver reference.
Configure coturn and Synapse with matching TURN credentials, open the required relay ports, and verify that Matrix clients can obtain relay candidates.
Set up a persistent Synapse homeserver with Docker Compose, PostgreSQL, a private config, and checks before exposing it through HTTPS.
Set a branded name, custom colors, and login assets for your Element Web deployment while understanding which parts remain Element-branded.
Diagnose whether Synapse hit its per-process open-file cap, set a systemd drop-in for the right service or worker, and verify the live limit.
Find out whether the error is limited to one browser or one event, then use Element’s recovery key or a trusted device without risking your remaining encrypted history.
Use Synapse’s history and media purge APIs or retention settings to remove stale data safely, then verify completion and disk-space recovery.
Install the current library, connect a dedicated Matrix account, and run a small !echo bot with safer credential handling and a clear test.
Set up three mautrix bridges with separate registrations, logins, and tests—and avoid Docker networking, account-policy, and sync surprises.
Find what is filling Synapse storage, set safe media retention, and purge remote cache without deleting files directly from disk.
Review device activity, deactivate confirmed inactive Synapse accounts through the Admin API, and learn what the optional erase flag actually removes.