mirrors/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2024-11-23 10:05:55 +03:00
Code Issues Projects Releases Packages Wiki Activity
synapse/v1.47/turn-howto.html

521 lines
31 KiB
HTML
Raw Normal View History

deploy: af784644c3380d0a2ea885abbe748fbe69d3a990
2021-11-09 14:58:04 +03:00
<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js light">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Configuring a Turn Server - Synapse</title>
<!-- Custom HTML head -->
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<link rel="icon" href="favicon.svg">
<link rel="shortcut icon" href="favicon.png">
<link rel="stylesheet" href="css/variables.css">
<link rel="stylesheet" href="css/general.css">
<link rel="stylesheet" href="css/chrome.css">
<link rel="stylesheet" href="css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<link rel="stylesheet" href="docs/website_files/table-of-contents.css">
<link rel="stylesheet" href="docs/website_files/remove-nav-buttons.css">
<link rel="stylesheet" href="docs/website_files/indent-section-headers.css">
</head>
<body>
<!-- Provide site root to javascript -->
<script type="text/javascript">
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
<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 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 "><a href="MSC1711_certificates_FAQ.html">Upgrading from pre-Synapse 1.0</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/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 "><div>Single-Sign On</div></li><li><ol class="section"><li class="chapter-item expanded "><a href="openid.html">OpenID Connect</a></li><li class="chapter-item expanded "><div>SAML</div></li><li class="chapter-item expanded "><div>CAS</div></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></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="development/url_previews.html">URL Previews</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 cal
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky bordered">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<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">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<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">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">Synapse</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/matrix-org/synapse" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
<a href="https://github.com/matrix-org/synapse/edit/develop/docs/turn-howto.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<!-- Page table of contents -->
<div class="sidetoc">
<nav class="pagetoc"></nav>
</div>
<h1 id="overview"><a class="header" href="#overview">Overview</a></h1>
<p>This document explains how to enable VoIP relaying on your Home Server with
TURN.</p>
<p>The synapse Matrix Home Server supports integration with TURN server via the
<a href="https://tools.ietf.org/html/draft-uberti-behave-turn-rest-00">TURN server REST API</a>. 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.</p>
<p>The following sections describe how to install <a href="https://github.com/coturn/coturn">coturn</a> (which implements the TURN REST API) and integrate it with synapse.</p>
<h2 id="requirements"><a class="header" href="#requirements">Requirements</a></h2>
<p>For TURN relaying with <code>coturn</code> to work, it must be hosted on a server/endpoint with a public IP.</p>
<p>Hosting TURN behind a NAT (even with appropriate port forwarding) is known to cause issues
and to often not work.</p>
<h2 id="coturn-setup"><a class="header" href="#coturn-setup"><code>coturn</code> setup</a></h2>
<h3 id="initial-installation"><a class="header" href="#initial-installation">Initial installation</a></h3>
<p>The TURN daemon <code>coturn</code> is available from a variety of sources such as native package managers, or installation from source.</p>
<h4 id="debian-installation"><a class="header" href="#debian-installation">Debian installation</a></h4>
<p>Just install the debian package:</p>
<pre><code class="language-sh">apt install coturn
</code></pre>
<p>This will install and start a systemd service called <code>coturn</code>.</p>
<h4 id="source-installation"><a class="header" href="#source-installation">Source installation</a></h4>
<ol>
<li>
<p>Download the <a href="https://github.com/coturn/coturn/releases/latest">latest release</a> from github. Unpack it and <code>cd</code> into the directory.</p>
</li>
<li>
<p>Configure it:</p>
<pre><code class="language-sh">./configure
</code></pre>
<p>You may need to install <code>libevent2</code>: 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.</p>
</li>
<li>
<p>Build and install it:</p>
<pre><code class="language-sh">make
make install
</code></pre>
</li>
</ol>
<h3 id="configuration"><a class="header" href="#configuration">Configuration</a></h3>
<ol>
<li>
<p>Create or edit the config file in <code>/etc/turnserver.conf</code>. The relevant
lines, with example values, are:</p>
<pre><code>use-auth-secret
static-auth-secret=[your secret key here]
realm=turn.myserver.org
</code></pre>
<p>See <code>turnserver.conf</code> for explanations of the options. One way to generate
the <code>static-auth-secret</code> is with <code>pwgen</code>:</p>
<pre><code class="language-sh">pwgen -s 64 1
</code></pre>
<p>A <code>realm</code> must be specified, but its value is somewhat arbitrary. (It is
sent to clients as part of the authentication flow.) It is conventional to
set it to be your server name.</p>
</li>
<li>
<p>You will most likely want to configure coturn to write logs somewhere. The
easiest way is normally to send them to the syslog:</p>
<pre><code class="language-sh">syslog
</code></pre>
<p>(in which case, the logs will be available via <code>journalctl -u coturn</code> on a
systemd system). Alternatively, coturn can be configured to write to a
logfile - check the example config file supplied with coturn.</p>
</li>
<li>
<p>Consider your security settings. TURN lets users request a relay which will
connect to arbitrary IP addresses and ports. The following configuration is
suggested as a minimum starting point:</p>
<pre><code># VoIP traffic is all UDP. There is no reason to let users connect to arbitrary TCP endpoints via the relay.
no-tcp-relay
# don't let the relay ever try to connect to private IP address ranges within your network (if any)
# given the turn server is likely behind your firewall, remember to include any privileged public IPs too.
denied-peer-ip=10.0.0.0-10.255.255.255
denied-peer-ip=192.168.0.0-192.168.255.255
denied-peer-ip=172.16.0.0-172.31.255.255
# special case the turn server itself so that client-&gt;TURN-&gt;TURN-&gt;client flows work
allowed-peer-ip=10.0.0.1
# consider whether you want to limit the quota of relayed streams per user (or total) to avoid risk of DoS.
user-quota=12 # 4 streams per video call, so 12 streams = 3 simultaneous relayed calls per user.
total-quota=1200
</code></pre>
</li>
<li>
<p>Also consider supporting TLS/DTLS. To do this, add the following settings
to <code>turnserver.conf</code>:</p>
<pre><code># TLS certificates, including intermediate certs.
# For Let's Encrypt certificates, use `fullchain.pem` here.
cert=/path/to/fullchain.pem
# TLS private key file
pkey=/path/to/privkey.pem
</code></pre>
<p>In this case, replace the <code>turn:</code> schemes in the <code>turn_uri</code> settings below
with <code>turns:</code>.</p>
<p>We recommend that you only try to set up TLS/DTLS once you have set up a
basic installation and got it working.</p>
</li>
<li>
<p>Ensure your firewall allows traffic into the TURN server on the ports
you've configured it to listen on (By default: 3478 and 5349 for TURN
traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535
for the UDP relay.)</p>
</li>
<li>
<p>We do not recommend running a TURN server behind NAT, and are not aware of
anyone doing so successfully.</p>
<p>If you want to try it anyway, you will at least need to tell coturn its
external IP address:</p>
<pre><code>external-ip=192.88.99.1
</code></pre>
<p>... and your NAT gateway must forward all of the relayed ports directly
(eg, port 56789 on the external IP must be always be forwarded to port
56789 on the internal IP).</p>
<p>If you get this working, let us know!</p>
</li>
<li>
<p>(Re)start the turn server:</p>
<ul>
<li>
<p>If you used the Debian package (or have set up a systemd unit yourself):</p>
<pre><code class="language-sh">systemctl restart coturn
</code></pre>
</li>
<li>
<p>If you installed from source:</p>
<pre><code class="language-sh">bin/turnserver -o
</code></pre>
</li>
</ul>
</li>
</ol>
<h2 id="synapse-setup"><a class="header" href="#synapse-setup">Synapse setup</a></h2>
<p>Your home server configuration file needs the following extra keys:</p>
<ol>
<li>&quot;<code>turn_uris</code>&quot;: 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.</li>
<li>&quot;<code>turn_shared_secret</code>&quot;: 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.</li>
<li>&quot;<code>turn_user_lifetime</code>&quot;: 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).</li>
<li>&quot;<code>turn_allow_guests</code>&quot;: Whether to allow guest users to use the
TURN server. This is enabled by default, as otherwise VoIP will
not work reliably for guests. However, it does introduce a
security risk as it lets guests connect to arbitrary endpoints
without having gone through a CAPTCHA or similar to register a
real account.</li>
</ol>
<p>As an example, here is the relevant section of the config file for <code>matrix.org</code>. The
<code>turn_uris</code> are appropriate for TURN servers listening on the default ports, with no TLS.</p>
<pre><code>turn_uris: [ &quot;turn:turn.matrix.org?transport=udp&quot;, &quot;turn:turn.matrix.org?transport=tcp&quot; ]
turn_shared_secret: &quot;n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons&quot;
turn_user_lifetime: 86400000
turn_allow_guests: True
</code></pre>
<p>After updating the homeserver configuration, you must restart synapse:</p>
<ul>
<li>If you use synctl:
<pre><code class="language-sh">cd /where/you/run/synapse
./synctl restart
</code></pre>
</li>
<li>If you use systemd:
<pre><code class="language-sh">systemctl restart matrix-synapse.service
</code></pre>
</li>
</ul>
<p>... and then reload any clients (or wait an hour for them to refresh their
settings).</p>
<h2 id="troubleshooting"><a class="header" href="#troubleshooting">Troubleshooting</a></h2>
<p>The normal symptoms of a misconfigured TURN server are that calls between
devices on different networks ring, but get stuck at &quot;call
connecting&quot;. Unfortunately, troubleshooting this can be tricky.</p>
<p>Here are a few things to try:</p>
<ul>
<li>
<p>Check that your TURN server is not behind NAT. As above, we're not aware of
anyone who has successfully set this up.</p>
</li>
<li>
<p>Check that you have opened your firewall to allow TCP and UDP traffic to the
TURN ports (normally 3478 and 5479).</p>
</li>
<li>
<p>Check that you have opened your firewall to allow UDP traffic to the UDP
relay ports (49152-65535 by default).</p>
</li>
<li>
<p>Some WebRTC implementations (notably, that of Google Chrome) appear to get
confused by TURN servers which are reachable over IPv6 (this appears to be
an unexpected side-effect of its handling of multiple IP addresses as
defined by
<a href="https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling-12"><code>draft-ietf-rtcweb-ip-handling</code></a>).</p>
<p>Try removing any AAAA records for your TURN server, so that it is only
reachable over IPv4.</p>
</li>
<li>
<p>Enable more verbose logging in coturn via the <code>verbose</code> setting:</p>
<pre><code>verbose
</code></pre>
<p>... and then see if there are any clues in its logs.</p>
</li>
<li>
<p>If you are using a browser-based client under Chrome, check
<code>chrome://webrtc-internals/</code> for insights into the internals of the
negotiation. On Firefox, check the &quot;Connection Log&quot; on <code>about:webrtc</code>.</p>
<p>(Understanding the output is beyond the scope of this document!)</p>
</li>
<li>
<p>You can test your Matrix homeserver TURN setup with https://test.voip.librepush.net/.
Note that this test is not fully reliable yet, so don't be discouraged if
the test fails.
<a href="https://github.com/matrix-org/voip-tester">Here</a> is the github repo of the
source of the tester, where you can file bug reports.</p>
</li>
<li>
<p>There is a WebRTC test tool at
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. To
use it, you will need a username/password for your TURN server. You can
either:</p>
<ul>
<li>
<p>look for the <code>GET /_matrix/client/r0/voip/turnServer</code> request made by a
matrix client to your homeserver in your browser's network inspector. In
the response you should see <code>username</code> and <code>password</code>. Or:</p>
</li>
<li>
<p>Use the following shell commands:</p>
<pre><code class="language-sh">secret=staticAuthSecretHere
u=$((`date +%s` + 3600)):test
p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64)
echo -e &quot;username: $u\npassword: $p&quot;
</code></pre>
<p>Or:</p>
</li>
<li>
<p>Temporarily configure coturn to accept a static username/password. To do
this, comment out <code>use-auth-secret</code> and <code>static-auth-secret</code> and add the
following:</p>
<pre><code>lt-cred-mech
user=username:password
</code></pre>
<p><strong>Note</strong>: these settings will not take effect unless <code>use-auth-secret</code>
and <code>static-auth-secret</code> are disabled.</p>
<p>Restart coturn after changing the configuration file.</p>
<p>Remember to restore the original settings to go back to testing with
Matrix clients!</p>
</li>
</ul>
<p>If the TURN server is working correctly, you should see at least one <code>relay</code>
entry in the results.</p>
</li>
</ul>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="setup/forward_proxy.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="delegate.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="setup/forward_proxy.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="delegate.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script type="text/javascript">
window.playground_copyable = true;
</script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
<script type="text/javascript" src="docs/website_files/table-of-contents.js"></script>
</body>
</html>
Reference in a new issue Copy permalink