mirror of
https://github.com/matrix-org/synapse.git
synced 2025-11-03 17:51:20 +01:00
129 lines
4.6 KiB
ReStructuredText
129 lines
4.6 KiB
ReStructuredText
How to enable VoIP relaying on your Home Server with TURN
|
|
|
|
Overview
|
|
--------
|
|
The synapse Matrix Home Server supports integration with TURN server via the
|
|
TURN server REST API
|
|
(http://tools.ietf.org/html/draft-uberti-behave-turn-rest-00). This allows
|
|
the Home Server to generate credentials that are valid for use on the TURN
|
|
server through the use of a secret shared between the Home Server and the
|
|
TURN server.
|
|
|
|
This document describes how to install coturn
|
|
(https://github.com/coturn/coturn) which also supports the TURN REST API,
|
|
and integrate it with synapse.
|
|
|
|
coturn Setup
|
|
============
|
|
|
|
You may be able to setup coturn via your package manager, or set it up manually using the usual ``configure, make, make install`` process.
|
|
|
|
1. Check out coturn::
|
|
|
|
git clone https://github.com/coturn/coturn.git coturn
|
|
cd coturn
|
|
|
|
2. Configure it::
|
|
|
|
./configure
|
|
|
|
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.
|
|
|
|
3. Build and install it::
|
|
|
|
make
|
|
make install
|
|
|
|
4. Create or edit the config file in ``/etc/turnserver.conf``. The relevant
|
|
lines, with example values, are::
|
|
|
|
lt-cred-mech
|
|
use-auth-secret
|
|
static-auth-secret=[your secret key here]
|
|
realm=turn.myserver.org
|
|
|
|
See turnserver.conf for explanations of the options.
|
|
One way to generate the static-auth-secret is with pwgen::
|
|
|
|
pwgen -s 64 1
|
|
|
|
5. Consider your security settings. TURN lets users request a relay
|
|
which will connect to arbitrary IP addresses and ports. At the least
|
|
we recommend:
|
|
|
|
# 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
|
|
|
|
Ideally coturn should refuse to relay traffic which isn't SRTP;
|
|
see https://github.com/matrix-org/synapse/issues/2009
|
|
|
|
6. Ensure your firewall allows traffic into the TURN server on
|
|
the ports you've configured it to listen on (remember to allow
|
|
both TCP and UDP TURN traffic)
|
|
|
|
7. If you've configured coturn to support TLS/DTLS, generate or
|
|
import your private key and certificate.
|
|
|
|
8. Start the turn server::
|
|
|
|
bin/turnserver -o
|
|
|
|
|
|
synapse Setup
|
|
=============
|
|
|
|
Your home server configuration file needs the following extra keys:
|
|
|
|
1. "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.
|
|
|
|
2. "turn_shared_secret": This is the secret shared between your Home
|
|
server and your TURN server, so you should set it to the same
|
|
string you used in turnserver.conf.
|
|
|
|
3. "turn_user_lifetime": This is the amount of time credentials
|
|
generated by your Home Server are valid for (in milliseconds).
|
|
Shorter times offer less potential for abuse at the expense
|
|
of increased traffic between web clients and your home server
|
|
to refresh credentials. The TURN REST API specification recommends
|
|
one day (86400000).
|
|
|
|
4. "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
|
|
matrix.org::
|
|
|
|
turn_uris: [ "turn:turn.matrix.org:3478?transport=udp", "turn:turn.matrix.org:3478?transport=tcp" ]
|
|
turn_shared_secret: n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons
|
|
turn_user_lifetime: 86400000
|
|
turn_allow_guests: True
|
|
|
|
Now, restart synapse::
|
|
|
|
cd /where/you/run/synapse
|
|
./synctl restart
|
|
|
|
...and your Home Server now supports VoIP relaying!
|