|
@@ -9,222 +9,28 @@ allows the homeserver to generate credentials that are valid for use on the
|
|
|
TURN server through the use of a secret shared between the homeserver and the
|
|
|
TURN server.
|
|
|
|
|
|
-The following sections describe how to install [coturn](<https://github.com/coturn/coturn>) (which implements the TURN REST API) and integrate it with synapse.
|
|
|
+This documentation provides two TURN server configuration examples:
|
|
|
+
|
|
|
+* [coturn](setup/turn/coturn.md)
|
|
|
+* [eturnal](setup/turn/eturnal.md)
|
|
|
|
|
|
## Requirements
|
|
|
|
|
|
-For TURN relaying with `coturn` to work, it must be hosted on a server/endpoint with a public IP.
|
|
|
+For TURN relaying to work, the TURN service must be hosted on a server/endpoint with a public IP.
|
|
|
|
|
|
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.
|
|
|
|
|
|
-## `coturn` setup
|
|
|
-
|
|
|
-### Initial installation
|
|
|
-
|
|
|
-The TURN daemon `coturn` is available from a variety of sources such as native package managers, or installation from source.
|
|
|
-
|
|
|
-#### Debian installation
|
|
|
-
|
|
|
-Just install the debian package:
|
|
|
-
|
|
|
-```sh
|
|
|
-apt install coturn
|
|
|
-```
|
|
|
-
|
|
|
-This will install and start a systemd service called `coturn`.
|
|
|
-
|
|
|
-#### Source installation
|
|
|
-
|
|
|
-1. Download the [latest release](https://github.com/coturn/coturn/releases/latest) from github. Unpack it and `cd` into the directory.
|
|
|
-
|
|
|
-1. Configure it:
|
|
|
-
|
|
|
- ```sh
|
|
|
- ./configure
|
|
|
- ```
|
|
|
-
|
|
|
- You may need to install `libevent2`: 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.
|
|
|
-
|
|
|
-1. Build and install it:
|
|
|
-
|
|
|
- ```sh
|
|
|
- make
|
|
|
- make install
|
|
|
- ```
|
|
|
-
|
|
|
-### Configuration
|
|
|
-
|
|
|
-1. Create or edit the config file in `/etc/turnserver.conf`. The relevant
|
|
|
- lines, with example values, are:
|
|
|
-
|
|
|
- ```
|
|
|
- use-auth-secret
|
|
|
- static-auth-secret=[your secret key here]
|
|
|
- realm=turn.myserver.org
|
|
|
- ```
|
|
|
-
|
|
|
- See `turnserver.conf` for explanations of the options. One way to generate
|
|
|
- the `static-auth-secret` is with `pwgen`:
|
|
|
-
|
|
|
- ```sh
|
|
|
- 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:
|
|
|
-
|
|
|
- ```sh
|
|
|
- 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
|
|
|
- connect to arbitrary IP addresses and ports. The following configuration is
|
|
|
- suggested as a minimum starting point:
|
|
|
-
|
|
|
- ```
|
|
|
- # 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
|
|
|
- ```
|
|
|
-
|
|
|
-1. Also consider supporting TLS/DTLS. To do this, add the following settings
|
|
|
- to `turnserver.conf`:
|
|
|
-
|
|
|
- ```
|
|
|
- # 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
|
|
|
- ```
|
|
|
-
|
|
|
- In this case, replace the `turn:` schemes in the `turn_uris` 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.
|
|
|
-
|
|
|
- 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
|
|
|
- [respective](https://github.com/vector-im/element-android/issues/1533)
|
|
|
- [issues](https://github.com/vector-im/element-ios/issues/2712) as well as the underlying
|
|
|
- [WebRTC issue](https://bugs.chromium.org/p/webrtc/issues/detail?id=11710).
|
|
|
- Consider using a ZeroSSL certificate for your TURN server as a working alternative.
|
|
|
-
|
|
|
-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 TURN
|
|
|
- traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535
|
|
|
- for the UDP relay.)
|
|
|
-
|
|
|
-1. 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:
|
|
|
-
|
|
|
- ```
|
|
|
- external-ip=EXTERNAL_NAT_IPv4_ADDRESS
|
|
|
- ```
|
|
|
-
|
|
|
- You may optionally limit the TURN server to listen only on the local
|
|
|
- address that is mapped by NAT to the external address:
|
|
|
-
|
|
|
- ```
|
|
|
- listening-ip=INTERNAL_TURNSERVER_IPv4_ADDRESS
|
|
|
- ```
|
|
|
-
|
|
|
- If your NAT gateway is reachable over both IPv4 and IPv6, you may
|
|
|
- configure coturn to advertise each available address:
|
|
|
-
|
|
|
- ```
|
|
|
- external-ip=EXTERNAL_NAT_IPv4_ADDRESS
|
|
|
- external-ip=EXTERNAL_NAT_IPv6_ADDRESS
|
|
|
- ```
|
|
|
-
|
|
|
- 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.
|
|
|
-
|
|
|
-1. (Re)start the turn server:
|
|
|
-
|
|
|
- * If you used the Debian package (or have set up a systemd unit yourself):
|
|
|
- ```sh
|
|
|
- systemctl restart coturn
|
|
|
- ```
|
|
|
-
|
|
|
- * If you installed from source:
|
|
|
-
|
|
|
- ```sh
|
|
|
- bin/turnserver -o
|
|
|
- ```
|
|
|
+Afterwards, the homeserver needs some further configuration.
|
|
|
|
|
|
## Synapse setup
|
|
|
|
|
|
Your homeserver configuration file needs the following extra keys:
|
|
|
|
|
|
-1. "`turn_uris`": 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.
|
|
|
-2. "`turn_shared_secret`": This is the secret shared between your
|
|
|
- homeserver and your TURN server, so you should set it to the same
|
|
|
- string you used in turnserver.conf.
|
|
|
-3. "`turn_user_lifetime`": This is the amount of time credentials
|
|
|
- generated by your homeserver are valid for (in milliseconds).
|
|
|
- Shorter times offer less potential for abuse at the expense of
|
|
|
- increased traffic between web clients and your homeserver to
|
|
|
- refresh credentials. The TURN REST API specification recommends
|
|
|
- one day (86400000).
|
|
|
-4. "`turn_allow_guests`": 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.
|
|
|
+1. [`turn_uris`](usage/configuration/config_documentation.md#turn_uris)
|
|
|
+2. [`turn_shared_secret`](usage/configuration/config_documentation.md#turn_shared_secret)
|
|
|
+3. [`turn_user_lifetime`](usage/configuration/config_documentation.md#turn_user_lifetime)
|
|
|
+4. [`turn_allow_guests`](usage/configuration/config_documentation.md#turn_allow_guests)
|
|
|
|
|
|
As an example, here is the relevant section of the config file for `matrix.org`. The
|
|
|
`turn_uris` are appropriate for TURN servers listening on the default ports, with no TLS.
|
|
@@ -263,7 +69,7 @@ Here are a few things to try:
|
|
|
* Check that you have opened your firewall to allow UDP traffic to the UDP
|
|
|
relay ports (49152-65535 by default).
|
|
|
|
|
|
- * Try disabling `coturn`'s TLS/DTLS listeners and enable only its (unencrypted)
|
|
|
+ * Try disabling TLS/DTLS listeners and enable only its (unencrypted)
|
|
|
TCP/UDP listeners. (This will only leave signaling traffic unencrypted;
|
|
|
voice & video WebRTC traffic is always encrypted.)
|
|
|
|
|
@@ -288,12 +94,19 @@ Here are a few things to try:
|
|
|
|
|
|
* ensure that your TURN server uses the NAT gateway as its default route.
|
|
|
|
|
|
- * Enable more verbose logging in coturn via the `verbose` setting:
|
|
|
+ * Enable more verbose logging, in `coturn` via the `verbose` setting:
|
|
|
|
|
|
```
|
|
|
verbose
|
|
|
```
|
|
|
|
|
|
+ or with `eturnal` with the shell command `eturnalctl loglevel debug` or in the configuration file (the service needs to [reload](https://eturnal.net/documentation/#Operation) for it to become effective):
|
|
|
+
|
|
|
+ ```yaml
|
|
|
+ ## Logging configuration:
|
|
|
+ log_level: debug
|
|
|
+ ```
|
|
|
+
|
|
|
... and then see if there are any clues in its logs.
|
|
|
|
|
|
* If you are using a browser-based client under Chrome, check
|
|
@@ -317,7 +130,7 @@ Here are a few things to try:
|
|
|
matrix client to your homeserver in your browser's network inspector. In
|
|
|
the response you should see `username` and `password`. Or:
|
|
|
|
|
|
- * Use the following shell commands:
|
|
|
+ * Use the following shell commands for `coturn`:
|
|
|
|
|
|
```sh
|
|
|
secret=staticAuthSecretHere
|
|
@@ -327,11 +140,16 @@ Here are a few things to try:
|
|
|
echo -e "username: $u\npassword: $p"
|
|
|
```
|
|
|
|
|
|
- Or:
|
|
|
+ or for `eturnal`
|
|
|
+
|
|
|
+ ```sh
|
|
|
+ eturnalctl credentials
|
|
|
+ ```
|
|
|
+
|
|
|
|
|
|
- * 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:
|
|
|
+ * Or (**coturn only**): 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
|