From 9bcedf224ef84d14307fc9d192e745f0e42e4127 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 25 Sep 2014 16:58:21 +0100 Subject: add howto for setting up your very own TURN server --- docs/turn-howto.rst | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/turn-howto.rst (limited to 'docs/turn-howto.rst') 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! -- cgit 1.4.1 From 48ea055781baf9be82023e85af18dc05ad5eda67 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 25 Sep 2014 17:01:27 +0100 Subject: fix rst warnings --- docs/turn-howto.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/turn-howto.rst') diff --git a/docs/turn-howto.rst b/docs/turn-howto.rst index dce8d1ebf2..4f097c391e 100644 --- a/docs/turn-howto.rst +++ b/docs/turn-howto.rst @@ -22,6 +22,7 @@ coturn Setup 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 @@ -34,9 +35,11 @@ coturn Setup 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:: -- cgit 1.4.1 From 6e72ee62aed7d4875282ed21b281c3d8223e6f5a Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 25 Sep 2014 17:21:14 +0100 Subject: Add realm to coturn options (it needs it). --- docs/turn-howto.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/turn-howto.rst') diff --git a/docs/turn-howto.rst b/docs/turn-howto.rst index 4f097c391e..2cb0c4170d 100644 --- a/docs/turn-howto.rst +++ b/docs/turn-howto.rst @@ -34,11 +34,12 @@ coturn Setup 4. Make a config file in /etc/turnserver.conf. You can customise a config file from turnserver.conf.default. The relevant - lines are:: + 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.default for explanations of the options. One way to generate the static-auth-secret is with pwgen:: -- cgit 1.4.1 From ec5fb77a66131382a179c349cf239859be7d8f4e Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 25 Sep 2014 19:18:32 +0200 Subject: Just use a yaml list for turn servers --- docs/turn-howto.rst | 4 ++-- synapse/config/voip.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/turn-howto.rst') diff --git a/docs/turn-howto.rst b/docs/turn-howto.rst index 2cb0c4170d..82b59538c8 100644 --- a/docs/turn-howto.rst +++ b/docs/turn-howto.rst @@ -62,8 +62,8 @@ 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 + 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. diff --git a/synapse/config/voip.py b/synapse/config/voip.py index c5131d9bcd..3a51664f46 100644 --- a/synapse/config/voip.py +++ b/synapse/config/voip.py @@ -19,7 +19,7 @@ class VoipConfig(Config): def __init__(self, args): super(VoipConfig, self).__init__(args) - self.turn_uris = args.turn_uris.split(",") if args.turn_uris else None + self.turn_uris = args.turn_uris self.turn_shared_secret = args.turn_shared_secret self.turn_user_lifetime = args.turn_user_lifetime -- cgit 1.4.1