turn-howto.html 30 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361
  1. <!DOCTYPE HTML>
  2. <html lang="en" class="sidebar-visible no-js light">
  3. <head>
  4. <!-- Book generated using mdBook -->
  5. <meta charset="UTF-8">
  6. <title>Configuring a Turn Server - Synapse</title>
  7. <!-- Custom HTML head -->
  8. <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  9. <meta name="description" content="">
  10. <meta name="viewport" content="width=device-width, initial-scale=1">
  11. <meta name="theme-color" content="#ffffff" />
  12. <link rel="icon" href="favicon.svg">
  13. <link rel="shortcut icon" href="favicon.png">
  14. <link rel="stylesheet" href="css/variables.css">
  15. <link rel="stylesheet" href="css/general.css">
  16. <link rel="stylesheet" href="css/chrome.css">
  17. <link rel="stylesheet" href="css/print.css" media="print">
  18. <!-- Fonts -->
  19. <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
  20. <link rel="stylesheet" href="fonts/fonts.css">
  21. <!-- Highlight.js Stylesheets -->
  22. <link rel="stylesheet" href="highlight.css">
  23. <link rel="stylesheet" href="tomorrow-night.css">
  24. <link rel="stylesheet" href="ayu-highlight.css">
  25. <!-- Custom theme stylesheets -->
  26. <link rel="stylesheet" href="docs/website_files/table-of-contents.css">
  27. <link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css">
  28. <link rel="stylesheet" href="docs/website_files/indent-section-headers.css">
  29. <link rel="stylesheet" href="docs/website_files/version-picker.css">
  30. </head>
  31. <body>
  32. <!-- Provide site root to javascript -->
  33. <script type="text/javascript">
  34. var path_to_root = "";
  35. var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
  36. </script>
  37. <!-- Work around some values being stored in localStorage wrapped in quotes -->
  38. <script type="text/javascript">
  39. try {
  40. var theme = localStorage.getItem('mdbook-theme');
  41. var sidebar = localStorage.getItem('mdbook-sidebar');
  42. if (theme.startsWith('"') && theme.endsWith('"')) {
  43. localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
  44. }
  45. if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
  46. localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
  47. }
  48. } catch (e) { }
  49. </script>
  50. <!-- Set the theme before any content is loaded, prevents flash -->
  51. <script type="text/javascript">
  52. var theme;
  53. try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
  54. if (theme === null || theme === undefined) { theme = default_theme; }
  55. var html = document.querySelector('html');
  56. html.classList.remove('no-js')
  57. html.classList.remove('light')
  58. html.classList.add(theme);
  59. html.classList.add('js');
  60. </script>
  61. <!-- Hide / unhide sidebar before it is displayed -->
  62. <script type="text/javascript">
  63. var html = document.querySelector('html');
  64. var sidebar = 'hidden';
  65. if (document.body.clientWidth >= 1080) {
  66. try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
  67. sidebar = sidebar || 'visible';
  68. }
  69. html.classList.remove('sidebar-visible');
  70. html.classList.add("sidebar-" + sidebar);
  71. </script>
  72. <nav id="sidebar" class="sidebar" aria-label="Table of contents">
  73. <div class="sidebar-scrollbox">
  74. <ol class="chapter"><li class="chapter-item expanded affix "><li class="part-title">Introduction</li><li class="chapter-item expanded "><a href="welcome_and_overview.html">Welcome and Overview</a></li><li class="chapter-item expanded affix "><li class="part-title">Setup</li><li class="chapter-item expanded "><a href="setup/installation.html">Installation</a></li><li class="chapter-item expanded "><a href="postgres.html">Using Postgres</a></li><li class="chapter-item expanded "><a href="reverse_proxy.html">Configuring a Reverse Proxy</a></li><li class="chapter-item expanded "><a href="setup/forward_proxy.html">Configuring a Forward/Outbound Proxy</a></li><li class="chapter-item expanded "><a href="turn-howto.html" class="active">Configuring a Turn Server</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="setup/turn/coturn.html">coturn TURN server</a></li><li class="chapter-item expanded "><a href="setup/turn/eturnal.html">eturnal TURN server</a></li></ol></li><li class="chapter-item expanded "><a href="delegate.html">Delegation</a></li><li class="chapter-item expanded affix "><li class="part-title">Upgrading</li><li class="chapter-item expanded "><a href="upgrade.html">Upgrading between Synapse Versions</a></li><li class="chapter-item expanded affix "><li class="part-title">Usage</li><li class="chapter-item expanded "><a href="federate.html">Federation</a></li><li class="chapter-item expanded "><a href="usage/configuration/index.html">Configuration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/config_documentation.html">Configuration Manual</a></li><li class="chapter-item expanded "><a href="usage/configuration/homeserver_sample_config.html">Homeserver Sample Config File</a></li><li class="chapter-item expanded "><a href="usage/configuration/logging_sample_config.html">Logging Sample Config File</a></li><li class="chapter-item expanded "><a href="structured_logging.html">Structured Logging</a></li><li class="chapter-item expanded "><a href="templates.html">Templates</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/index.html">User Authentication</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/index.html">Single-Sign On</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/single_sign_on/cas.html">CAS</a></li><li class="chapter-item expanded "><a href="sso_mapping_providers.html">SSO Mapping Providers</a></li></ol></li><li class="chapter-item expanded "><a href="password_auth_providers.html">Password Auth Providers</a></li><li class="chapter-item expanded "><a href="jwt.html">JSON Web Tokens</a></li><li class="chapter-item expanded "><a href="usage/configuration/user_authentication/refresh_tokens.html">Refresh Tokens</a></li></ol></li><li class="chapter-item expanded "><a href="CAPTCHA_SETUP.html">Registration Captcha</a></li><li class="chapter-item expanded "><a href="application_services.html">Application Services</a></li><li class="chapter-item expanded "><a href="server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="consent_tracking.html">Consent Tracking</a></li><li class="chapter-item expanded "><a href="user_directory.html">User Directory</a></li><li class="chapter-item expanded "><a href="message_retention_policies.html">Message Retention Policies</a></li><li class="chapter-item expanded "><a href="modules/index.html">Pluggable Modules</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/writing_a_module.html">Writing a module</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="modules/spam_checker_callbacks.html">Spam checker callbacks</a></li><li class="chapter-item expanded "><a href="modules/third_party_rules_callbacks.html">Third-party rules callbacks</a></li><li class="chapter-item expanded "><a href="modules/presence_router_callbacks.html">Presence router callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_validity_callbacks.html">Account validity callbacks</a></li><li class="chapter-item expanded "><a href="modules/password_auth_provider_callbacks.html">Password auth provider callbacks</a></li><li class="chapter-item expanded "><a href="modules/background_update_controller_callbacks.html">Background update controller callbacks</a></li><li class="chapter-item expanded "><a href="modules/account_data_callbacks.html">Account data callbacks</a></li><li class="chapter-item expanded "><a href="modules/porting_legacy_module.html">Porting a legacy module to the new interface</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="workers.html">Workers</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="synctl_workers.html">Using synctl with Workers</a></li><li class="chapter-item expanded "><a href="systemd-with-workers/index.html">Systemd</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/index.html">Administration</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/admin_api/index.html">Admin API</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="admin_api/account_validity.html">Account Validity</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/background_updates.html">Background Updates</a></li><li class="chapter-item expanded "><a href="admin_api/event_reports.html">Event Reports</a></li><li class="chapter-item expanded "><a href="admin_api/experimental_features.html">Experimental Features</a></li><li class="chapter-item expanded "><a href="admin_api/media_admin_api.html">Media</a></li><li class="chapter-item expanded "><a href="admin_api/purge_history_api.html">Purge History</a></li><li class="chapter-item expanded "><a href="admin_api/register_api.html">Register Users</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/registration_tokens.html">Registration Tokens</a></li><li class="chapter-item expanded "><a href="admin_api/room_membership.html">Manipulate Room Membership</a></li><li class="chapter-item expanded "><a href="admin_api/rooms.html">Rooms</a></li><li class="chapter-item expanded "><a href="admin_api/server_notices.html">Server Notices</a></li><li class="chapter-item expanded "><a href="admin_api/statistics.html">Statistics</a></li><li class="chapter-item expanded "><a href="admin_api/user_admin_api.html">Users</a></li><li class="chapter-item expanded "><a href="admin_api/version_api.html">Server Version</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_api/federation.html">Federation</a></li></ol></li><li class="chapter-item expanded "><a href="manhole.html">Manhole</a></li><li class="chapter-item expanded "><a href="metrics-howto.html">Monitoring</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="usage/administration/monitoring/reporting_homeserver_usage_statistics.html">Reporting Homeserver Usage Statistics</a></li></ol></li><li class="chapter-item expanded "><a href="usage/administration/monthly_active_users.html">Monthly Active Users</a></li><li class="chapter-item expanded "><a href="usage/administration/understanding_synapse_through_grafana_graphs.html">Understanding Synapse Through Grafana Graphs</a></li><li class="chapter-item expanded "><a href="usage/administration/useful_sql_for_admins.html">Useful SQL for Admins</a></li><li class="chapter-item expanded "><a href="usage/administration/database_maintenance_tools.html">Database Maintenance Tools</a></li><li class="chapter-item expanded "><a href="usage/administration/state_groups.html">State Groups</a></li><li class="chapter-item expanded "><a href="usage/administration/request_log.html">Request log format</a></li><li class="chapter-item expanded "><a href="usage/administration/admin_faq.html">Admin FAQ</a></li><li class="chapter-item expanded "><div>Scripts</div></li></ol></li><li class="chapter-item expanded "><li class="part-title">Development</li><li class="chapter-item expanded "><a href="development/contributing_guide.html">Contributing Guide</a></li><li class="chapter-item expanded "><a href="code_style.html">Code Style</a></li><li class="chapter-item expanded "><a href="development/reviews.html">Reviewing Code</a></li><li class="chapter-item expanded "><a href="development/releases.html">Release Cycle</a></li><li class="chapter-item expanded "><a href="development/git.html">Git Usage</a></li><li class="chapter-item expanded "><div>Testing</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/demo.html">Demo scripts</a></li></ol></li><li class="chapter-item expanded "><a href="opentracing.html">OpenTracing</a></li><li class="chapter-item expanded "><a href="development/database_schema.html">Database Schemas</a></li><li class="chapter-item expanded "><a href="development/experimental_features.html">Experimental features</a></li><li class="chapter-item expanded "><a href="development/dependencies.html">Dependency management</a></li><li class="chapter-item expanded "><div>Synapse Architecture</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/synapse_architecture/cancellation.html">Cancellation</a></li><li class="chapter-item expanded "><a href="log_contexts.html">Log Contexts</a></li><li class="chapter-item expanded "><a href="replication.html">Replication</a></li><li class="chapter-item expanded "><a href="tcp_replication.html">TCP Replication</a></li><li class="chapter-item expanded "><a href="development/synapse_architecture/faster_joins.html">Faster remote joins</a></li></ol></li><li class="chapter-item expanded "><a href="development/internal_documentation/index.html">Internal Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><div>Single Sign-On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="development/saml.html">SAML</a></li><li class="chapter-item expanded "><a href="development/cas.html">CAS</a></li></ol></li><li class="chapter-item expanded "><a href="development/room-dag-concepts.html">Room DAG concepts</a></li><li class="chapter-item expanded "><div>State Resolution</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="auth_chain_difference_algorithm.html">The Auth Chain Difference Algorithm</a></li></ol></li><li class="chapter-item expanded "><a href="media_repository.html">Media Repository</a></li><li class="chapter-item expanded "><a href="room_and_user_statistics.html">Room and User Statistics</a></li></ol></li><li class="chapter-item expanded "><div>Scripts</div></li><li class="chapter-item expanded affix "><li class="part-title">Other</li><li class="chapter-item expanded "><a href="deprecation_policy.html">Dependency Deprecation Policy</a></li><li class="chapter-item expanded "><a href="other/running_synapse_on_single_board_computers.html">Running Synapse on a Single-Board Computer</a></li></ol>
  75. </div>
  76. <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
  77. </nav>
  78. <div id="page-wrapper" class="page-wrapper">
  79. <div class="page">
  80. <div id="menu-bar-hover-placeholder"></div>
  81. <div id="menu-bar" class="menu-bar sticky bordered">
  82. <div class="left-buttons">
  83. <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
  84. <i class="fa fa-bars"></i>
  85. </button>
  86. <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
  87. <i class="fa fa-paint-brush"></i>
  88. </button>
  89. <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
  90. <li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
  91. <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
  92. <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
  93. <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
  94. <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
  95. </ul>
  96. <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
  97. <i class="fa fa-search"></i>
  98. </button>
  99. <div class="version-picker">
  100. <div class="dropdown">
  101. <div class="select">
  102. <span></span>
  103. <i class="fa fa-chevron-down"></i>
  104. </div>
  105. <input type="hidden" name="version">
  106. <ul class="dropdown-menu">
  107. <!-- Versions will be added dynamically in version-picker.js -->
  108. </ul>
  109. </div>
  110. </div>
  111. </div>
  112. <h1 class="menu-title">Synapse</h1>
  113. <div class="right-buttons">
  114. <a href="print.html" title="Print this book" aria-label="Print this book">
  115. <i id="print-button" class="fa fa-print"></i>
  116. </a>
  117. <a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
  118. <i id="git-repository-button" class="fa fa-github"></i>
  119. </a>
  120. <a href="https://github.com/matrix-org/synapse/edit/develop/docs/turn-howto.md" title="Suggest an edit" aria-label="Suggest an edit">
  121. <i id="git-edit-button" class="fa fa-edit"></i>
  122. </a>
  123. </div>
  124. </div>
  125. <div id="search-wrapper" class="hidden">
  126. <form id="searchbar-outer" class="searchbar-outer">
  127. <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
  128. </form>
  129. <div id="searchresults-outer" class="searchresults-outer hidden">
  130. <div id="searchresults-header" class="searchresults-header"></div>
  131. <ul id="searchresults">
  132. </ul>
  133. </div>
  134. </div>
  135. <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
  136. <script type="text/javascript">
  137. document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
  138. document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
  139. Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
  140. link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
  141. });
  142. </script>
  143. <div id="content" class="content">
  144. <main>
  145. <!-- Page table of contents -->
  146. <div class="sidetoc">
  147. <nav class="pagetoc"></nav>
  148. </div>
  149. <h1 id="overview"><a class="header" href="#overview">Overview</a></h1>
  150. <p>This document explains how to enable VoIP relaying on your homeserver with
  151. TURN.</p>
  152. <p>The synapse Matrix homeserver supports integration with TURN server via the
  153. <a href="https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00">TURN server REST API</a>. This
  154. allows the homeserver to generate credentials that are valid for use on the
  155. TURN server through the use of a secret shared between the homeserver and the
  156. TURN server.</p>
  157. <p>This documentation provides two TURN server configuration examples:</p>
  158. <ul>
  159. <li><a href="setup/turn/coturn.html">coturn</a></li>
  160. <li><a href="setup/turn/eturnal.html">eturnal</a></li>
  161. </ul>
  162. <h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
  163. <p>For TURN relaying to work, the TURN service must be hosted on a server/endpoint with a public IP.</p>
  164. <p>Hosting TURN behind NAT requires port forwaring and for the NAT gateway to have a public IP.
  165. However, even with appropriate configuration, NAT is known to cause issues and to often not work.</p>
  166. <p>Afterwards, the homeserver needs some further configuration.</p>
  167. <h2 id="synapse-setup"><a class="header" href="#synapse-setup">Synapse setup</a></h2>
  168. <p>Your homeserver configuration file needs the following extra keys:</p>
  169. <ol>
  170. <li><a href="usage/configuration/config_documentation.html#turn_uris"><code>turn_uris</code></a></li>
  171. <li><a href="usage/configuration/config_documentation.html#turn_shared_secret"><code>turn_shared_secret</code></a></li>
  172. <li><a href="usage/configuration/config_documentation.html#turn_user_lifetime"><code>turn_user_lifetime</code></a></li>
  173. <li><a href="usage/configuration/config_documentation.html#turn_allow_guests"><code>turn_allow_guests</code></a></li>
  174. </ol>
  175. <p>As an example, here is the relevant section of the config file for <code>matrix.org</code>. The
  176. <code>turn_uris</code> are appropriate for TURN servers listening on the default ports, with no TLS.</p>
  177. <pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ]
  178. turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot;
  179. turn_user_lifetime: 86400000
  180. turn_allow_guests: true
  181. </code></pre>
  182. <p>After updating the homeserver configuration, you must restart synapse:</p>
  183. <ul>
  184. <li>If you use synctl:
  185. <pre><code class="language-sh"># Depending on how Synapse is installed, synctl may already be on
  186. # your PATH. If not, you may need to activate a virtual environment.
  187. synctl restart
  188. </code></pre>
  189. </li>
  190. <li>If you use systemd:
  191. <pre><code class="language-sh">systemctl restart matrix-synapse.service
  192. </code></pre>
  193. </li>
  194. </ul>
  195. <p>... and then reload any clients (or wait an hour for them to refresh their
  196. settings).</p>
  197. <h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
  198. <p>The normal symptoms of a misconfigured TURN server are that calls between
  199. devices on different networks ring, but get stuck at &quot;call
  200. connecting&quot;. Unfortunately, troubleshooting this can be tricky.</p>
  201. <p>Here are a few things to try:</p>
  202. <ul>
  203. <li>
  204. <p>Check that you have opened your firewall to allow TCP and UDP traffic to the
  205. TURN ports (normally 3478 and 5349).</p>
  206. </li>
  207. <li>
  208. <p>Check that you have opened your firewall to allow UDP traffic to the UDP
  209. relay ports (49152-65535 by default).</p>
  210. </li>
  211. <li>
  212. <p>Try disabling TLS/DTLS listeners and enable only its (unencrypted)
  213. TCP/UDP listeners. (This will only leave signaling traffic unencrypted;
  214. voice &amp; video WebRTC traffic is always encrypted.)</p>
  215. </li>
  216. <li>
  217. <p>Some WebRTC implementations (notably, that of Google Chrome) appear to get
  218. confused by TURN servers which are reachable over IPv6 (this appears to be
  219. an unexpected side-effect of its handling of multiple IP addresses as
  220. defined by
  221. <a href="https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling-12"><code>draft-ietf-rtcweb-ip-handling</code></a>).</p>
  222. <p>Try removing any AAAA records for your TURN server, so that it is only
  223. reachable over IPv4.</p>
  224. </li>
  225. <li>
  226. <p>If your TURN server is behind NAT:</p>
  227. <ul>
  228. <li>
  229. <p>double-check that your NAT gateway is correctly forwarding all TURN
  230. ports (normally 3478 &amp; 5349 for TCP &amp; UDP TURN traffic, and 49152-65535 for the UDP
  231. relay) to the NAT-internal address of your TURN server. If advertising
  232. both IPv4 and IPv6 external addresses via the <code>external-ip</code> option, ensure
  233. that the NAT is forwarding both IPv4 and IPv6 traffic to the IPv4 and IPv6
  234. internal addresses of your TURN server. When in doubt, remove AAAA records
  235. for your TURN server and specify only an IPv4 address as your <code>external-ip</code>.</p>
  236. </li>
  237. <li>
  238. <p>ensure that your TURN server uses the NAT gateway as its default route.</p>
  239. </li>
  240. </ul>
  241. </li>
  242. <li>
  243. <p>Enable more verbose logging, in <code>coturn</code> via the <code>verbose</code> setting:</p>
  244. <pre><code>verbose
  245. </code></pre>
  246. <p>or with <code>eturnal</code> with the shell command <code>eturnalctl loglevel debug</code> or in the configuration file (the service needs to <a href="https://eturnal.net/documentation/#Operation">reload</a> for it to become effective):</p>
  247. <pre><code class="language-yaml"> ## Logging configuration:
  248. log_level: debug
  249. </code></pre>
  250. <p>... and then see if there are any clues in its logs.</p>
  251. </li>
  252. <li>
  253. <p>If you are using a browser-based client under Chrome, check
  254. <code>chrome://webrtc-internals/</code> for insights into the internals of the
  255. negotiation. On Firefox, check the &quot;Connection Log&quot; on <code>about:webrtc</code>.</p>
  256. <p>(Understanding the output is beyond the scope of this document!)</p>
  257. </li>
  258. <li>
  259. <p>You can test your Matrix homeserver TURN setup with <a href="https://test.voip.librepush.net/">https://test.voip.librepush.net/</a>.
  260. Note that this test is not fully reliable yet, so don't be discouraged if
  261. the test fails.
  262. <a href="https://github.com/matrix-org/voip-tester">Here</a> is the github repo of the
  263. source of the tester, where you can file bug reports.</p>
  264. </li>
  265. <li>
  266. <p>There is a WebRTC test tool at
  267. <a href="https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/">https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/</a>. To
  268. use it, you will need a username/password for your TURN server. You can
  269. either:</p>
  270. <ul>
  271. <li>
  272. <p>look for the <code>GET /_matrix/client/r0/voip/turnServer</code> request made by a
  273. matrix client to your homeserver in your browser's network inspector. In
  274. the response you should see <code>username</code> and <code>password</code>. Or:</p>
  275. </li>
  276. <li>
  277. <p>Use the following shell commands for <code>coturn</code>:</p>
  278. <pre><code class="language-sh">secret=staticAuthSecretHere
  279. u=$((`date +%s` + 3600)):test
  280. p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64)
  281. echo -e &quot;username: $u\npassword: $p&quot;
  282. </code></pre>
  283. <p>or for <code>eturnal</code></p>
  284. <pre><code class="language-sh">eturnalctl credentials
  285. </code></pre>
  286. </li>
  287. <li>
  288. <p>Or (<strong>coturn only</strong>): Temporarily configure <code>coturn</code> to accept a static
  289. username/password. To do this, comment out <code>use-auth-secret</code> and
  290. <code>static-auth-secret</code> and add the following:</p>
  291. <pre><code>lt-cred-mech
  292. user=username:password
  293. </code></pre>
  294. <p><strong>Note</strong>: these settings will not take effect unless <code>use-auth-secret</code>
  295. and <code>static-auth-secret</code> are disabled.</p>
  296. <p>Restart coturn after changing the configuration file.</p>
  297. <p>Remember to restore the original settings to go back to testing with
  298. Matrix clients!</p>
  299. </li>
  300. </ul>
  301. <p>If the TURN server is working correctly, you should see at least one <code>relay</code>
  302. entry in the results.</p>
  303. </li>
  304. </ul>
  305. </main>
  306. <nav class="nav-wrapper" aria-label="Page navigation">
  307. <!-- Mobile navigation buttons -->
  308. <a rel="prev" href="setup/forward_proxy.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  309. <i class="fa fa-angle-left"></i>
  310. </a>
  311. <a rel="next" href="setup/turn/coturn.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  312. <i class="fa fa-angle-right"></i>
  313. </a>
  314. <div style="clear: both"></div>
  315. </nav>
  316. </div>
  317. </div>
  318. <nav class="nav-wide-wrapper" aria-label="Page navigation">
  319. <a rel="prev" href="setup/forward_proxy.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
  320. <i class="fa fa-angle-left"></i>
  321. </a>
  322. <a rel="next" href="setup/turn/coturn.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
  323. <i class="fa fa-angle-right"></i>
  324. </a>
  325. </nav>
  326. </div>
  327. <script type="text/javascript">
  328. window.playground_copyable = true;
  329. </script>
  330. <script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
  331. <script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
  332. <script src="searcher.js" type="text/javascript" charset="utf-8"></script>
  333. <script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
  334. <script src="highlight.js" type="text/javascript" charset="utf-8"></script>
  335. <script src="book.js" type="text/javascript" charset="utf-8"></script>
  336. <!-- Custom JS scripts -->
  337. <script type="text/javascript" src="docs/website_files/table-of-contents.js"></script>
  338. <script type="text/javascript" src="docs/website_files/version-picker.js"></script>
  339. <script type="text/javascript" src="docs/website_files/version.js"></script>
  340. </body>
  341. </html>