turn-howto.rst 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293
  1. How to enable VoIP relaying on your Home Server with TURN
  2. Overview
  3. --------
  4. The synapse Matrix Home Server supports integration with TURN server via the
  5. TURN server REST API
  6. (http://tools.ietf.org/html/draft-uberti-behave-turn-rest-00). This allows
  7. the Home Server to generate credentials that are valid for use on the TURN
  8. server through the use of a secret shared between the Home Server and the
  9. TURN server.
  10. This document described how to install coturn
  11. (https://code.google.com/p/coturn/) which also supports the TURN REST API,
  12. and integrate it with synapse.
  13. coturn Setup
  14. ============
  15. 1. Check out coturn::
  16. svn checkout http://coturn.googlecode.com/svn/trunk/ coturn
  17. cd coturn
  18. 2. Configure it::
  19. ./configure
  20. You may need to install libevent2: if so, you should do so
  21. in the way recommended by your operating system.
  22. You can ignore warnings about lack of database support: a
  23. database is unnecessary for this purpose.
  24. 3. Build and install it::
  25. make
  26. make install
  27. 4. Make a config file in /etc/turnserver.conf. You can customise
  28. a config file from turnserver.conf.default. The relevant
  29. lines, with example values, are::
  30. lt-cred-mech
  31. use-auth-secret
  32. static-auth-secret=[your secret key here]
  33. realm=turn.myserver.org
  34. See turnserver.conf.default for explanations of the options.
  35. One way to generate the static-auth-secret is with pwgen::
  36. pwgen -s 64 1
  37. 5. Ensure youe firewall allows traffic into the TURN server on
  38. the ports you've configured it to listen on (remember to allow
  39. both TCP and UDP if you've enabled both).
  40. 6. If you've configured coturn to support TLS/DTLS, generate or
  41. import your private key and certificate.
  42. 7. Start the turn server::
  43. bin/turnserver -o
  44. synapse Setup
  45. =============
  46. Your home server configuration file needs the following extra keys:
  47. 1. "turn_uris": This needs to be a yaml list
  48. of public-facing URIs for your TURN server to be given out
  49. to your clients. Add separate entries for each transport your
  50. TURN server supports.
  51. 2. "turn_shared_secret": This is the secret shared between your Home
  52. server and your TURN server, so you should set it to the same
  53. string you used in turnserver.conf.
  54. 3. "turn_user_lifetime": This is the amount of time credentials
  55. generated by your Home Server are valid for (in milliseconds).
  56. Shorter times offer less potential for abuse at the expense
  57. of increased traffic between web clients and your home server
  58. to refresh credentials. The TURN REST API specification recommends
  59. one day (86400000).
  60. As an example, here is the relevant section of the config file for
  61. matrix.org::
  62. turn_uris: [ "turn:turn.matrix.org:3478?transport=udp", "turn:turn.matrix.org:3478?transport=tcp" ]
  63. turn_shared_secret: n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons
  64. turn_user_lifetime: 86400000
  65. Now, restart synapse::
  66. cd /where/you/run/synapse
  67. ./synctl restart
  68. ...and your Home Server now supports VoIP relaying!