This document explains how to enable VoIP relaying on your homeserver with TURN.
The synapse Matrix homeserver supports integration with TURN server via the TURN server REST API. This allows the homeserver to generate credentials that are valid for use on the TURN server through the use of a secret shared between the homeserver and the TURN server.
The following sections describe how to install coturn (which implements the TURN REST API) and integrate it with synapse.
For TURN relaying with
coturn to work, it must be hosted on a server/endpoint with a public IP.
Hosting TURN behind a NAT (even with appropriate port forwarding) is known to cause issues and to often not work.
The TURN daemon
coturn is available from a variety of sources such as native package managers, or installation from source.
Just install the debian package:
apt install coturn
This will install and start a systemd service called
Download the latest release from github. Unpack it and
cdinto the directory.
You may need to install
libevent2: if so, you should do so in the way recommended by your operating system. You can ignore warnings about lack of database support: a database is unnecessary for this purpose.
Build and install it:
make make install
Create or edit the config file in
/etc/turnserver.conf. The relevant lines, with example values, are:
use-auth-secret static-auth-secret=[your secret key here] realm=turn.myserver.org
turnserver.conffor explanations of the options. One way to generate the
pwgen -s 64 1
realmmust be specified, but its value is somewhat arbitrary. (It is sent to clients as part of the authentication flow.) It is conventional to set it to be your server name.
You will most likely want to configure coturn to write logs somewhere. The easiest way is normally to send them to the syslog:
(in which case, the logs will be available via
journalctl -u coturnon a systemd system). Alternatively, coturn can be configured to write to a logfile - check the example config file supplied with coturn.
Consider your security settings. TURN lets users request a relay which will connect to arbitrary IP addresses and ports. The following configuration is suggested as a minimum starting point:
# VoIP traffic is all UDP. There is no reason to let users connect to arbitrary TCP endpoints via the relay. no-tcp-relay # don't let the relay ever try to connect to private IP address ranges within your network (if any) # given the turn server is likely behind your firewall, remember to include any privileged public IPs too. denied-peer-ip=10.0.0.0-10.255.255.255 denied-peer-ip=192.168.0.0-192.168.255.255 denied-peer-ip=172.16.0.0-172.31.255.255 # special case the turn server itself so that client->TURN->TURN->client flows work allowed-peer-ip=10.0.0.1 # consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS. user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user. total-quota=1200
Also consider supporting TLS/DTLS. To do this, add the following settings to
# TLS certificates, including intermediate certs. # For Let's Encrypt certificates, use `fullchain.pem` here. cert=/path/to/fullchain.pem # TLS private key file pkey=/path/to/privkey.pem
In this case, replace the
turn:schemes in the
turn_urisettings below with
We recommend that you only try to set up TLS/DTLS once you have set up a basic installation and got it working.
Ensure your firewall allows traffic into the TURN server on the ports you've configured it to listen on (By default: 3478 and 5349 for TURN traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535 for the UDP relay.)
We do not recommend running a TURN server behind NAT, and are not aware of anyone doing so successfully.
If you want to try it anyway, you will at least need to tell coturn its external IP address:
... and your NAT gateway must forward all of the relayed ports directly (eg, port 56789 on the external IP must be always be forwarded to port 56789 on the internal IP).
If you get this working, let us know!
(Re)start the turn server:
If you used the Debian package (or have set up a systemd unit yourself):
systemctl restart coturn
If you installed from source:
Your homeserver configuration file needs the following extra keys:
turn_uris": This needs to be a yaml list of public-facing URIs for your TURN server to be given out to your clients. Add separate entries for each transport your TURN server supports.
turn_shared_secret": This is the secret shared between your homeserver and your TURN server, so you should set it to the same string you used in turnserver.conf.
turn_user_lifetime": This is the amount of time credentials generated by your homeserver are valid for (in milliseconds). Shorter times offer less potential for abuse at the expense of increased traffic between web clients and your homeserver to refresh credentials. The TURN REST API specification recommends one day (86400000).
turn_allow_guests": Whether to allow guest users to use the TURN server. This is enabled by default, as otherwise VoIP will not work reliably for guests. However, it does introduce a security risk as it lets guests connect to arbitrary endpoints without having gone through a CAPTCHA or similar to register a real account.
As an example, here is the relevant section of the config file for
turn_uris are appropriate for TURN servers listening on the default ports, with no TLS.
turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" turn_user_lifetime: 86400000 turn_allow_guests: True
After updating the homeserver configuration, you must restart synapse:
- If you use synctl:
cd /where/you/run/synapse ./synctl restart
- If you use systemd:
systemctl restart matrix-synapse.service
... and then reload any clients (or wait an hour for them to refresh their settings).
The normal symptoms of a misconfigured TURN server are that calls between devices on different networks ring, but get stuck at "call connecting". Unfortunately, troubleshooting this can be tricky.
Here are a few things to try:
Check that your TURN server is not behind NAT. As above, we're not aware of anyone who has successfully set this up.
Check that you have opened your firewall to allow TCP and UDP traffic to the TURN ports (normally 3478 and 5349).
Check that you have opened your firewall to allow UDP traffic to the UDP relay ports (49152-65535 by default).
Some WebRTC implementations (notably, that of Google Chrome) appear to get confused by TURN servers which are reachable over IPv6 (this appears to be an unexpected side-effect of its handling of multiple IP addresses as defined by
Try removing any AAAA records for your TURN server, so that it is only reachable over IPv4.
Enable more verbose logging in coturn via the
... and then see if there are any clues in its logs.
If you are using a browser-based client under Chrome, check
chrome://webrtc-internals/for insights into the internals of the negotiation. On Firefox, check the "Connection Log" on
(Understanding the output is beyond the scope of this document!)
You can test your Matrix homeserver TURN setup with https://test.voip.librepush.net/. Note that this test is not fully reliable yet, so don't be discouraged if the test fails. Here is the github repo of the source of the tester, where you can file bug reports.
There is a WebRTC test tool at https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. To use it, you will need a username/password for your TURN server. You can either:
look for the
GET /_matrix/client/r0/voip/turnServerrequest made by a matrix client to your homeserver in your browser's network inspector. In the response you should see
Use the following shell commands:
secret=staticAuthSecretHere u=$((`date +%s` + 3600)):test p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64) echo -e "username: $u\npassword: $p"
Temporarily configure coturn to accept a static username/password. To do this, comment out
static-auth-secretand add the following:
Note: these settings will not take effect unless
Restart coturn after changing the configuration file.
Remember to restore the original settings to go back to testing with Matrix clients!
If the TURN server is working correctly, you should see at least one
relayentry in the results.