Update turn-howto

pull/8779/head
Richard van der Hoff 2020-11-18 23:46:41 +00:00
parent f737368a26
commit 2bcf56c8e5
2 changed files with 109 additions and 9 deletions

1
changelog.d/8779.doc Normal file
View File

@ -0,0 +1 @@
Update `turn-howto.md` with troubleshooting notes.

View File

@ -42,10 +42,10 @@ This will install and start a systemd service called `coturn`.
./configure ./configure
> You may need to install `libevent2`: if so, you should do so in You may need to install `libevent2`: if so, you should do so in
> the way recommended by your operating system. You can ignore the way recommended by your operating system. You can ignore
> warnings about lack of database support: a database is unnecessary warnings about lack of database support: a database is unnecessary
> for this purpose. for this purpose.
1. Build and install it: 1. Build and install it:
@ -66,6 +66,19 @@ This will install and start a systemd service called `coturn`.
pwgen -s 64 1 pwgen -s 64 1
A `realm` 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.
1. You will most likely want to configure coturn to write logs somewhere. The
easiest way is normally to send them to the syslog:
syslog
(in which case, the logs will be available via `journalctl -u coturn` on a
systemd system). Alternatively, coturn can be configured to write to a
logfile - check the example config file supplied with coturn.
1. Consider your security settings. TURN lets users request a relay which will 1. Consider your security settings. TURN lets users request a relay which will
connect to arbitrary IP addresses and ports. The following configuration is connect to arbitrary IP addresses and ports. The following configuration is
suggested as a minimum starting point: suggested as a minimum starting point:
@ -96,10 +109,28 @@ This will install and start a systemd service called `coturn`.
# TLS private key file # TLS private key file
pkey=/path/to/privkey.pem pkey=/path/to/privkey.pem
In this case, replace the `turn:` schemes in the `turn_uri` settings below
with `turns:`.
We recommend that you only try to set up TLS/DTLS once you have set up a
basic installation and got it working.
1. Ensure your firewall allows traffic into the TURN server on the ports 1. 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 the TURN(s) you've configured it to listen on (By default: 3478 for TURN and 5349 for
traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535 TURNs traffic (remember to allow both TCP and UDP traffic), and ports
for the UDP relay.) 49152-65535 for the UDP relay.)
1. If your TURN server is behind NAT, you will need to tell it its external IP
address:
external-ip=192.88.99.1
For this to work, your NAT gateway must forward all of the relayed ports
directly (relayed port 12345 must be always mapped to the same 'external'
port 12345).
We are not aware of anyone who has successfully configured a TURN server
behind NAT. If you get it working, let us know!
1. (Re)start the turn server: 1. (Re)start the turn server:
@ -139,7 +170,7 @@ Your home server configuration file needs the following extra keys:
As an example, here is the relevant section of the config file for matrix.org: As an example, here is the relevant section of the config file for matrix.org:
turn_uris: [ "turn:turn.matrix.org:3478?transport=udp", "turn:turn.matrix.org:3478?transport=tcp" ] turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
turn_user_lifetime: 86400000 turn_user_lifetime: 86400000
turn_allow_guests: True turn_allow_guests: True
@ -155,5 +186,73 @@ After updating the homeserver configuration, you must restart synapse:
``` ```
systemctl restart synapse.service systemctl restart synapse.service
``` ```
... and then reload any clients (or wait an hour for them to refresh their
settings).
..and your Home Server now supports VoIP relaying! ## Troubleshooting
The normal symptoms of a misconfigured TURN server are that calls between
devices on different networks ring, but get stuck at "call
connecting". Unfortunately, troubleshooting this can be tricky.
Here are a few things to try:
* Check that your TURN server is not behind NAT. As above, we're not aware of
anyone who has successfully set this up.
* Check that you have opened your firewall to allow TCP and UDP traffic to the
TURN ports (normally 3478 and 5479).
* Check that you have opened your firewall to allow UDP traffic to the UDP
relay ports (49152-65535 by default).
* 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
[`draft-ietf-rtcweb-ip-handling`](https://tools.ietf.org/html/draft-ietf-rtcweb-ip-handling-12)).
Try removing any AAAA records for your TURN server, so that it is only
reachable over IPv4.
* Enable more verbose logging in coturn via the `verbose` setting:
```
verbose
```
... and then see if there are any clues in its logs.
* If you are using a browser-based client under Chrome, check
`chrome://webrtc-internals/` for insights into the internals of the
negotiation. (Understanding the output is beyond the scope of this
document!)
* 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:
* look for the `GET /_matrix/client/r0/voip/turnServer` request made by a
matrix client to your homeserver in your browser's network inspector. In
the response you should see `username` and `password`. Or:
* Temporarily configure coturn to accept a static username/password. To do
this, comment out `use-auth-secret` and `static-auth-secret` and add the
following:
```
lt-cred-mech
user=username:password
```
**Note**: these settings will not take effect unless `use-auth-secret`
and `static-auth-secret` are disabled.
Restart coturn after changing the configuration file.
Remember to restore the original settings to go back to testing with
Matrix clients!
If the TURN server is working correctly, you should see at least one `relay`
entry in the results.