1
0

turn-howto.rst 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128
  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 describes how to install coturn
  11. (https://github.com/coturn/coturn) which also supports the TURN REST API,
  12. and integrate it with synapse.
  13. coturn Setup
  14. ============
  15. You may be able to setup coturn via your package manager, or set it up manually using the usual ``configure, make, make install`` process.
  16. 1. Check out coturn::
  17. git clone https://github.com/coturn/coturn.git coturn
  18. cd coturn
  19. 2. Configure it::
  20. ./configure
  21. You may need to install ``libevent2``: if so, you should do so
  22. in the way recommended by your operating system.
  23. You can ignore warnings about lack of database support: a
  24. database is unnecessary for this purpose.
  25. 3. Build and install it::
  26. make
  27. make install
  28. 4. Create or edit the config file in ``/etc/turnserver.conf``. 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 for explanations of the options.
  35. One way to generate the static-auth-secret is with pwgen::
  36. pwgen -s 64 1
  37. 5. Consider your security settings. TURN lets users request a relay
  38. which will connect to arbitrary IP addresses and ports. At the least
  39. we recommend:
  40. # VoIP traffic is all UDP. There is no reason to let users connect to arbitrary TCP endpoints via the relay.
  41. no-tcp-relay
  42. # don't let the relay ever try to connect to private IP address ranges within your network (if any)
  43. # given the turn server is likely behind your firewall, remember to include any privileged public IPs too.
  44. denied-peer-ip=10.0.0.0-10.255.255.255
  45. denied-peer-ip=192.168.0.0-192.168.255.255
  46. denied-peer-ip=172.16.0.0-172.31.255.255
  47. # special case the turn server itself so that client->TURN->TURN->client flows work
  48. allowed-peer-ip=10.0.0.1
  49. # consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS.
  50. user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
  51. total-quota=1200
  52. Ideally coturn should refuse to relay traffic which isn't SRTP;
  53. see https://github.com/matrix-org/synapse/issues/2009
  54. 6. Ensure your firewall allows traffic into the TURN server on
  55. the ports you've configured it to listen on (remember to allow
  56. both TCP and UDP TURN traffic)
  57. 7. If you've configured coturn to support TLS/DTLS, generate or
  58. import your private key and certificate.
  59. 8. Start the turn server::
  60. bin/turnserver -o
  61. synapse Setup
  62. =============
  63. Your home server configuration file needs the following extra keys:
  64. 1. "turn_uris": This needs to be a yaml list
  65. of public-facing URIs for your TURN server to be given out
  66. to your clients. Add separate entries for each transport your
  67. TURN server supports.
  68. 2. "turn_shared_secret": This is the secret shared between your Home
  69. server and your TURN server, so you should set it to the same
  70. string you used in turnserver.conf.
  71. 3. "turn_user_lifetime": This is the amount of time credentials
  72. generated by your Home Server are valid for (in milliseconds).
  73. Shorter times offer less potential for abuse at the expense
  74. of increased traffic between web clients and your home server
  75. to refresh credentials. The TURN REST API specification recommends
  76. one day (86400000).
  77. 4. "turn_allow_guests": Whether to allow guest users to use the TURN
  78. server. This is enabled by default, as otherwise VoIP will not
  79. work reliably for guests. However, it does introduce a security risk
  80. as it lets guests connect to arbitrary endpoints without having gone
  81. through a CAPTCHA or similar to register a real account.
  82. As an example, here is the relevant section of the config file for
  83. matrix.org::
  84. turn_uris: [ "turn:turn.matrix.org:3478?transport=udp", "turn:turn.matrix.org:3478?transport=tcp" ]
  85. turn_shared_secret: n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons
  86. turn_user_lifetime: 86400000
  87. turn_allow_guests: True
  88. Now, restart synapse::
  89. cd /where/you/run/synapse
  90. ./synctl restart
  91. ...and your Home Server now supports VoIP relaying!