deploy: c500bf37d660b08efb48501b7690dc4448b39eca

1 files changed, 53 insertions, 16 deletions

diff --git a/develop/turn-howto.html b/develop/turn-howto.html
index e3e6255289..d83f010022 100644
--- a/develop/turn-howto.html
+++ b/develop/turn-howto.html
@@ -193,8 +193,8 @@ 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>
+<p>Hosting TURN behind NAT requires port forwaring and for the NAT gateway to have a public IP.
+However, even with appropriate configuration, NAT 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>
@@ -263,7 +263,23 @@ 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-&gt;TURN-&gt;TURN-&gt;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.
@@ -281,7 +297,7 @@ 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
+<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>
@@ -293,16 +309,24 @@ 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
+<p>If your TURN server is behind NAT, the NAT gateway must have an external,
+publicly-reachable IP address. You must configure coturn 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>... 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>
+<p>If your NAT gateway is reachable over both IPv4 and IPv6, you may
+configure coturn 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>
@@ -370,10 +394,6 @@ 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 5349).</p>
 </li>
@@ -391,6 +411,23 @@ defined by
 reachable over IPv4.</p>
 </li>
 <li>
+<p>If your TURN server is behind NAT:</p>
+<ul>
+<li>
+<p>double-check that your NAT gateway is correctly forwarding all TURN
+ports (normally 3478 &amp; 5349 for TCP &amp; UDP TURN traffic, and 49152-65535 for the UDP
+relay) to the NAT-internal address of your TURN server. If advertising
+both IPv4 and IPv6 external addresses via the <code>external-ip</code> option, ensure
+that the NAT is forwarding both IPv4 and IPv6 traffic to the IPv4 and IPv6
+internal addresses of your TURN server. When in doubt, remove AAAA records
+for your TURN server and specify only an IPv4 address as your <code>external-ip</code>.</p>
+</li>
+<li>
+<p>ensure that your TURN server uses the NAT gateway as its default route.</p>
+</li>
+</ul>
+</li>
+<li>
 <p>Enable more verbose logging in coturn via the <code>verbose</code> setting:</p>
 <pre><code>verbose
 </code></pre>