2022-12-13 16:30:19 +03:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > coturn 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" >
2023-12-11 17:55:10 +03:00
< link rel = "stylesheet" href = "../../docs/website_files/version-picker.css" >
2022-12-13 16:30:19 +03:00
< / 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" > Configuring a Turn Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../../setup/turn/coturn.html" class = "active" > 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 = "../
< / 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 >
2023-12-11 17:55:10 +03:00
< div class = "version-picker" >
< div class = "dropdown" >
< div class = "select" >
< span > < / span >
< i class = "fa fa-chevron-down" > < / i >
< / div >
< input type = "hidden" name = "version" >
< ul class = "dropdown-menu" >
<!-- Versions will be added dynamically in version - picker.js -->
< / ul >
< / div >
< / div >
2022-12-13 16:30:19 +03:00
< / 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/setup/turn/coturn.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 = "coturn-turn-server" > < a class = "header" href = "#coturn-turn-server" > coturn TURN server< / a > < / h1 >
< p > The following sections describe how to install < a href = "https://github.com/coturn/coturn" > coturn< / a > (which implements the TURN REST API).< / 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-and-ubuntu-based-distributions" > < a class = "header" href = "#debian-and-ubuntu-based-distributions" > Debian and Ubuntu based distributions< / a > < / h4 >
< p > Just install the debian package:< / p >
< pre > < code class = "language-sh" > sudo 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
sudo 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 < code > coturn< / code > 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, < code > coturn< / code > can be configured to write to a
logfile - check the example config file supplied with < code > coturn< / code > .< / 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
# recommended additional local peers to block, to mitigate external access to internal services.
# https://www.rtcsec.com/article/slack-webrtc-turn-compromise-and-bug-bounty/#how-to-fix-an-open-turn-relay-to-address-this-vulnerability
no-multicast-peers
denied-peer-ip=0.0.0.0-0.255.255.255
denied-peer-ip=100.64.0.0-100.127.255.255
denied-peer-ip=127.0.0.0-127.255.255.255
denied-peer-ip=169.254.0.0-169.254.255.255
denied-peer-ip=192.0.0.0-192.0.0.255
denied-peer-ip=192.0.2.0-192.0.2.255
denied-peer-ip=192.88.99.0-192.88.99.255
denied-peer-ip=198.18.0.0-198.19.255.255
denied-peer-ip=198.51.100.0-198.51.100.255
denied-peer-ip=203.0.113.0-203.0.113.255
denied-peer-ip=240.0.0.0-255.255.255.255
# special case the turn server itself so that client-> TURN-> TURN-> client flows work
# this should be one of the turn server's listening IPs
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
# Ensure the configuration lines that disable TLS/DTLS are commented-out or removed
#no-tls
#no-dtls
< / code > < / pre >
< p > In this case, replace the < code > turn:< / code > schemes in the < code > turn_uris< / 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 >
< p > NB: If your TLS certificate was provided by Let's Encrypt, TLS/DTLS will
not work with any Matrix client that uses Chromium's WebRTC library. This
currently includes Element Android & iOS; for more details, see their
< a href = "https://github.com/vector-im/element-android/issues/1533" > respective< / a >
< a href = "https://github.com/vector-im/element-ios/issues/2712" > issues< / a > as well as the underlying
< a href = "https://bugs.chromium.org/p/webrtc/issues/detail?id=11710" > WebRTC issue< / a > .
Consider using a ZeroSSL certificate for your TURN server as a working alternative.< / 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 > If your TURN server is behind NAT, the NAT gateway must have an external,
publicly-reachable IP address. You must configure < code > coturn< / code > to advertise that
address to connecting clients:< / p >
< pre > < code > external-ip=EXTERNAL_NAT_IPv4_ADDRESS
< / code > < / pre >
< p > You may optionally limit the TURN server to listen only on the local
address that is mapped by NAT to the external address:< / p >
< pre > < code > listening-ip=INTERNAL_TURNSERVER_IPv4_ADDRESS
< / code > < / pre >
< p > If your NAT gateway is reachable over both IPv4 and IPv6, you may
configure < code > coturn< / code > to advertise each available address:< / p >
< pre > < code > external-ip=EXTERNAL_NAT_IPv4_ADDRESS
external-ip=EXTERNAL_NAT_IPv6_ADDRESS
< / code > < / pre >
< p > When advertising an external IPv6 address, ensure that the firewall and
network settings of the system running your TURN server are configured to
accept IPv6 traffic, and that the TURN server is listening on the local
IPv6 address that is mapped by NAT to the external IPv6 address.< / 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" > sudo systemctl restart coturn
< / code > < / pre >
< / li >
< li >
< p > If you built from source:< / p >
< pre > < code class = "language-sh" > /usr/local/bin/turnserver -o
< / code > < / pre >
< / li >
< / ul >
< / li >
< / ol >
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../../turn-howto.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 = "../../setup/turn/eturnal.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 = "../../turn-howto.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 = "../../setup/turn/eturnal.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 >
2023-12-11 17:55:10 +03:00
< script type = "text/javascript" src = "../../docs/website_files/version-picker.js" > < / script >
< script type = "text/javascript" src = "../../docs/website_files/version.js" > < / script >
2022-12-13 16:30:19 +03:00
< / body >
2023-12-11 17:55:10 +03:00
< / html >
