mirror of
https://git.anonymousland.org/anonymousland/synapse.git
synced 2024-12-25 12:49:22 -05:00
Include additional TURN server example into documentation (#14293)
* Include eturnal TURN server configuration example and moving specific configuration examples into sub folders. * Update docs/turn-howto.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> * Update docs/setup/turn/coturn.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> * Update docs/setup/turn/eturnal.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> * Fix TURN relaying public IP address hint * lint eturnal installation commands * Adjust synapse setup to link to existing documentation ..avoid redundant information. * remove redundant text * include alpine linux package link * Create 14293.doc * Update 14293.doc add missing dot * Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre <olivier@librepush.net> * Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre <olivier@librepush.net> * Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com> * Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com> * Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com> * Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre <olivier@librepush.net> * Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com> * Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com> * Update eturnal.md to link to official documentation ... and to simplify some aspects * Adjust coturn to link to default prefix * Mention eturnalctl location * Update docs/turn-howto.md Co-authored-by: Saarko <sandomir@tutanotal.com> Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> Co-authored-by: reivilibre <olivier@librepush.net> Co-authored-by: Moritz Dietz <moritzdietz@users.noreply.github.com>
This commit is contained in:
sando38
GitHub
parent
36097e88c4
commit
64dd8a9c6e
1
changelog.d/14293.doc
Normal file
1
changelog.d/14293.doc
Normal file
@ -0,0 +1 @@
|
|||||||
|
Add addtional TURN server configuration example based on [eturnal](https://github.com/processone/eturnal) and adjust general TURN server doc structure.
|
||||||
@ -9,6 +9,8 @@
|
|||||||
- [Configuring a Reverse Proxy](reverse_proxy.md)
|
- [Configuring a Reverse Proxy](reverse_proxy.md)
|
||||||
- [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md)
|
- [Configuring a Forward/Outbound Proxy](setup/forward_proxy.md)
|
||||||
- [Configuring a Turn Server](turn-howto.md)
|
- [Configuring a Turn Server](turn-howto.md)
|
||||||
|
- [coturn TURN server](setup/turn/coturn.md)
|
||||||
|
- [eturnal TURN server](setup/turn/eturnal.md)
|
||||||
- [Delegation](delegate.md)
|
- [Delegation](delegate.md)
|
||||||
|
|
||||||
# Upgrading
|
# Upgrading
|
||||||
|
|||||||
188
docs/setup/turn/coturn.md
Normal file
188
docs/setup/turn/coturn.md
Normal file
@ -0,0 +1,188 @@
|
|||||||
|
# coturn TURN server
|
||||||
|
|
||||||
|
The following sections describe how to install [coturn](<https://github.com/coturn/coturn>) (which implements the TURN REST API).
|
||||||
|
|
||||||
|
## `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 and Ubuntu based distributions
|
||||||
|
|
||||||
|
Just install the debian package:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
sudo 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
|
||||||
|
sudo 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
|
||||||
|
sudo systemctl restart coturn
|
||||||
|
```
|
||||||
|
|
||||||
|
* If you built from source:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
/usr/local/bin/turnserver -o
|
||||||
|
```
|
||||||
170
docs/setup/turn/eturnal.md
Normal file
170
docs/setup/turn/eturnal.md
Normal file
@ -0,0 +1,170 @@
|
|||||||
|
# eturnal TURN server
|
||||||
|
|
||||||
|
The following sections describe how to install [eturnal](<https://github.com/processone/eturnal>)
|
||||||
|
(which implements the TURN REST API).
|
||||||
|
|
||||||
|
## `eturnal` setup
|
||||||
|
|
||||||
|
### Initial installation
|
||||||
|
|
||||||
|
The `eturnal` TURN server implementation is available from a variety of sources
|
||||||
|
such as native package managers, binary packages, installation from source or
|
||||||
|
[container image](https://eturnal.net/documentation/code/docker.html). They are
|
||||||
|
all described [here](https://github.com/processone/eturnal#installation).
|
||||||
|
|
||||||
|
Quick-Test instructions in a [Linux Shell](https://github.com/processone/eturnal/blob/master/QUICK-TEST.md)
|
||||||
|
or with [Docker](https://github.com/processone/eturnal/blob/master/docker-k8s/QUICK-TEST.md)
|
||||||
|
are available as well.
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
After installation, `eturnal` usually ships a [default configuration file](https://github.com/processone/eturnal/blob/master/config/eturnal.yml)
|
||||||
|
here: `/etc/eturnal.yml` (and, if not found there, there is a backup file here:
|
||||||
|
`/opt/eturnal/etc/eturnal.yml`). It uses the (indentation-sensitive!) [YAML](https://en.wikipedia.org/wiki/YAML)
|
||||||
|
format. The file contains further explanations.
|
||||||
|
|
||||||
|
Here are some hints how to configure eturnal on your [host machine](https://github.com/processone/eturnal#configuration)
|
||||||
|
or when using e.g. [Docker](https://eturnal.net/documentation/code/docker.html).
|
||||||
|
You may also further deep dive into the [reference documentation](https://eturnal.net/documentation/).
|
||||||
|
|
||||||
|
`eturnal` runs out of the box with the default configuration. To enable TURN and
|
||||||
|
to integrate it with your homeserver, some aspects in `eturnal`'s default configuration file
|
||||||
|
must be edited:
|
||||||
|
|
||||||
|
1. Homeserver's [`turn_shared_secret`](../../usage/configuration/config_documentation.md#turn_shared_secret)
|
||||||
|
and eturnal's shared `secret` for authentication
|
||||||
|
|
||||||
|
Both need to have the same value. Uncomment and adjust this line in `eturnal`'s
|
||||||
|
configuration file:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
secret: "long-and-cryptic" # Shared secret, CHANGE THIS.
|
||||||
|
```
|
||||||
|
|
||||||
|
One way to generate a `secret` is with `pwgen`:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
pwgen -s 64 1
|
||||||
|
```
|
||||||
|
|
||||||
|
1. Public IP address
|
||||||
|
|
||||||
|
If your TURN server is behind NAT, the NAT gateway must have an external,
|
||||||
|
publicly-reachable IP address. `eturnal` tries to autodetect the public IP address,
|
||||||
|
however, it may also be configured by uncommenting and adjusting this line, so
|
||||||
|
`eturnal` advertises that address to connecting clients:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
|
||||||
|
```
|
||||||
|
|
||||||
|
If your NAT gateway is reachable over both IPv4 and IPv6, you may
|
||||||
|
configure `eturnal` to advertise each available address:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
|
||||||
|
relay_ipv6_addr: "2001:db8::4" # The server's public IPv6 address (optional).
|
||||||
|
```
|
||||||
|
|
||||||
|
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. Logging
|
||||||
|
|
||||||
|
If `eturnal` was started by systemd, log files are written into the
|
||||||
|
`/var/log/eturnal` directory by default. In order to log to the [journal](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html)
|
||||||
|
instead, the `log_dir` option can be set to `stdout` in the configuration file.
|
||||||
|
|
||||||
|
1. Security considerations
|
||||||
|
|
||||||
|
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, [see also the official documentation](https://eturnal.net/documentation/#blacklist):
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
## Reject TURN relaying from/to the following addresses/networks:
|
||||||
|
blacklist: # This is the default blacklist.
|
||||||
|
- "127.0.0.0/8" # IPv4 loopback.
|
||||||
|
- "::1" # IPv6 loopback.
|
||||||
|
- recommended # Expands to a number of networks recommended to be
|
||||||
|
# blocked, but includes private networks. Those
|
||||||
|
# would have to be 'whitelist'ed if eturnal serves
|
||||||
|
# local clients/peers within such networks.
|
||||||
|
```
|
||||||
|
|
||||||
|
To whitelist IP addresses or specific (private) networks, you need to **add** a
|
||||||
|
whitelist part into the configuration file, e.g.:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
whitelist:
|
||||||
|
- "192.168.0.0/16"
|
||||||
|
- "203.0.113.113"
|
||||||
|
- "2001:db8::/64"
|
||||||
|
```
|
||||||
|
|
||||||
|
The more specific, the better.
|
||||||
|
|
||||||
|
1. TURNS (TURN via TLS/DTLS)
|
||||||
|
|
||||||
|
Also consider supporting TLS/DTLS. To do this, adjust the following settings
|
||||||
|
in the `eturnal.yml` configuration file (TLS parts should not be commented anymore):
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
listen:
|
||||||
|
- ip: "::"
|
||||||
|
port: 3478
|
||||||
|
transport: udp
|
||||||
|
- ip: "::"
|
||||||
|
port: 3478
|
||||||
|
transport: tcp
|
||||||
|
- ip: "::"
|
||||||
|
port: 5349
|
||||||
|
transport: tls
|
||||||
|
|
||||||
|
## TLS certificate/key files (must be readable by 'eturnal' user!):
|
||||||
|
tls_crt_file: /etc/eturnal/tls/crt.pem
|
||||||
|
tls_key_file: /etc/eturnal/tls/key.pem
|
||||||
|
```
|
||||||
|
|
||||||
|
In this case, replace the `turn:` schemes in homeserver's `turn_uris` settings
|
||||||
|
with `turns:`. More is described [here](../../usage/configuration/config_documentation.md#turn_uris).
|
||||||
|
|
||||||
|
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. Firewall
|
||||||
|
|
||||||
|
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. Reload/ restarting `eturnal`
|
||||||
|
|
||||||
|
Changes in the configuration file require `eturnal` to reload/ restart, this
|
||||||
|
can be achieved by:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
eturnalctl reload
|
||||||
|
```
|
||||||
|
|
||||||
|
`eturnal` performs a configuration check before actually reloading/ restarting
|
||||||
|
and provides hints, if something is not correctly configured.
|
||||||
|
|
||||||
|
### eturnalctl opterations script
|
||||||
|
|
||||||
|
`eturnal` offers a handy [operations script](https://eturnal.net/documentation/#Operation)
|
||||||
|
which can be called e.g. to check, whether the service is up, to restart the service,
|
||||||
|
to query how many active sessions exist, to change logging behaviour and so on.
|
||||||
|
|
||||||
|
Hint: If `eturnalctl` is not part of your `$PATH`, consider either sym-linking it (e.g. ´ln -s /opt/eturnal/bin/eturnalctl /usr/local/bin/eturnalctl´) or call it from the default `eturnal` directory directly: e.g. `/opt/eturnal/bin/eturnalctl info`
|
||||||
@ -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 through the use of a secret shared between the homeserver and the
|
||||||
TURN server.
|
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
|
## 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.
|
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.
|
However, even with appropriate configuration, NAT is known to cause issues and to often not work.
|
||||||
|
|
||||||
## `coturn` setup
|
Afterwards, the homeserver needs some further configuration.
|
||||||
|
|
||||||
### 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
|
|
||||||
```
|
|
||||||
|
|
||||||
## Synapse setup
|
## Synapse setup
|
||||||
|
|
||||||
Your homeserver configuration file needs the following extra keys:
|
Your homeserver configuration file needs the following extra keys:
|
||||||
|
|
||||||
1. "`turn_uris`": This needs to be a yaml list of public-facing URIs
|
1. [`turn_uris`](usage/configuration/config_documentation.md#turn_uris)
|
||||||
for your TURN server to be given out to your clients. Add separate
|
2. [`turn_shared_secret`](usage/configuration/config_documentation.md#turn_shared_secret)
|
||||||
entries for each transport your TURN server supports.
|
3. [`turn_user_lifetime`](usage/configuration/config_documentation.md#turn_user_lifetime)
|
||||||
2. "`turn_shared_secret`": This is the secret shared between your
|
4. [`turn_allow_guests`](usage/configuration/config_documentation.md#turn_allow_guests)
|
||||||
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.
|
|
||||||
|
|
||||||
As an example, here is the relevant section of the config file for `matrix.org`. The
|
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.
|
`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
|
* Check that you have opened your firewall to allow UDP traffic to the UDP
|
||||||
relay ports (49152-65535 by default).
|
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;
|
TCP/UDP listeners. (This will only leave signaling traffic unencrypted;
|
||||||
voice & video WebRTC traffic is always encrypted.)
|
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.
|
* 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
|
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.
|
... and then see if there are any clues in its logs.
|
||||||
|
|
||||||
* If you are using a browser-based client under Chrome, check
|
* 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
|
matrix client to your homeserver in your browser's network inspector. In
|
||||||
the response you should see `username` and `password`. Or:
|
the response you should see `username` and `password`. Or:
|
||||||
|
|
||||||
* Use the following shell commands:
|
* Use the following shell commands for `coturn`:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
secret=staticAuthSecretHere
|
secret=staticAuthSecretHere
|
||||||
@ -327,11 +140,16 @@ Here are a few things to try:
|
|||||||
echo -e "username: $u\npassword: $p"
|
echo -e "username: $u\npassword: $p"
|
||||||
```
|
```
|
||||||
|
|
||||||
Or:
|
or for `eturnal`
|
||||||
|
|
||||||
* Temporarily configure coturn to accept a static username/password. To do
|
```sh
|
||||||
this, comment out `use-auth-secret` and `static-auth-secret` and add the
|
eturnalctl credentials
|
||||||
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
|
lt-cred-mech
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user