summary refs log tree commit diff
path: root/docs/turn-howto.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/turn-howto.rst')
-rw-r--r--docs/turn-howto.rst127
1 files changed, 0 insertions, 127 deletions
diff --git a/docs/turn-howto.rst b/docs/turn-howto.rst
deleted file mode 100644
index a2fc5c8820..0000000000
--- a/docs/turn-howto.rst
+++ /dev/null
@@ -1,127 +0,0 @@
-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::
-
-      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!