diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/turn-howto.rst | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/turn-howto.rst b/docs/turn-howto.rst new file mode 100644 index 0000000000..dce8d1ebf2 --- /dev/null +++ b/docs/turn-howto.rst @@ -0,0 +1,89 @@ +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 described how to install coturn +(https://code.google.com/p/coturn/) which also supports the TURN REST API, +and integrate it with synapse. + +coturn Setup +============ + + 1. Check out coturn:: + svn checkout http://coturn.googlecode.com/svn/trunk/ 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. Make a config file in /etc/turnserver.conf. You can customise + a config file from turnserver.conf.default. The relevant + lines are:: + lt-cred-mech + use-auth-secret + static-auth-secret=[your secret key here] + See turnserver.conf.default for explanations of the options. + One way to generate the static-auth-secret is with pwgen:: + + pwgen -s 64 1 + + 5. Ensure youe firewall allows traffic into the TURN server on + the ports you've configured it to listen on (remember to allow + both TCP and UDP if you've enabled both). + + 6. If you've configured coturn to support TLS/DTLS, generate or + import your private key and certificate. + + 7. 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 comma-separated + 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). + +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 + +Now, restart synapse:: + + cd /where/you/run/synapse + ./synctl restart + +...and your Home Server now supports VoIP relaying! |