Merge branch 'develop' into rav/fix_attribute_mapping

1 files changed, 123 insertions, 0 deletions

diff --git a/docs/turn-howto.md b/docs/turn-howto.md
new file mode 100644
index 0000000000..4a983621e5
--- /dev/null
+++ b/docs/turn-howto.md
@@ -0,0 +1,123 @@
+# Overview
+
+This document explains how to enable VoIP relaying on your Home Server with
+TURN.
+
+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.
+
+The following sections describe how to install [coturn](<https://github.com/coturn/coturn>) (which implements the TURN REST API) and integrate it with synapse.
+
+## `coturn` Setup
+
+### Initial installation
+
+The TURN daemon `coturn` is available from a variety of sources such as native package managers, or installation from source.
+
+#### Debian installation
+
+    # apt install coturn
+
+#### Source installation
+
+1. Download the [latest release](https://github.com/coturn/coturn/releases/latest) from github.  Unpack it and `cd` into the directory.
+
+1.  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.
+
+1.  Build and install it:
+
+        make
+        make install
+
+1.  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
+
+1.  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
+
+    Ideally coturn should refuse to relay traffic which isn't SRTP; see
+    <https://github.com/matrix-org/synapse/issues/2009>
+
+1.  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)
+
+1.  If you've configured coturn to support TLS/DTLS, generate or import your
+    private key and certificate.
+
+1.  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
+
+After updating the homeserver configuration, you must restart synapse:
+
+    cd /where/you/run/synapse
+    ./synctl restart
+
+..and your Home Server now supports VoIP relaying!