From a09aba1292af305c9eca696d041199516c00043c Mon Sep 17 00:00:00 2001 From: Saarko Date: Tue, 25 Oct 2022 20:40:42 +0200 Subject: [PATCH 01/23] Include eturnal TURN server configuration example and moving specific configuration examples into sub folders. --- docs/SUMMARY.md | 2 + docs/setup/turn/coturn.md | 334 +++++++++++++++++++++++++++++++++++++ docs/setup/turn/eturnal.md | 145 ++++++++++++++++ docs/turn-howto.md | 216 +++--------------------- 4 files changed, 504 insertions(+), 193 deletions(-) create mode 100644 docs/setup/turn/coturn.md create mode 100644 docs/setup/turn/eturnal.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 16720bceb521..8d68719958d6 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -9,6 +9,8 @@ - [Configuring a Reverse Proxy](reverse_proxy.md) - [Configuring a Forward/Outbound Proxy](setup/forward_proxy.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) # Upgrading diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md new file mode 100644 index 000000000000..b3d53e3ad011 --- /dev/null +++ b/docs/setup/turn/coturn.md @@ -0,0 +1,334 @@ +# coturn TURN server + +The following sections describe how to install [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 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 + +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. + +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: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] + turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" + turn_user_lifetime: 86400000 + turn_allow_guests: True + +After updating the homeserver configuration, you must restart synapse: + + * If you use synctl: + ```sh + # Depending on how Synapse is installed, synctl may already be on + # your PATH. If not, you may need to activate a virtual environment. + synctl restart + ``` + * If you use systemd: + ```sh + systemctl restart matrix-synapse.service + ``` +... and then reload any clients (or wait an hour for them to refresh their +settings). + +## 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 you have opened your firewall to allow TCP and UDP traffic to the + TURN ports (normally 3478 and 5349). + + * 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) + TCP/UDP listeners. (This will only leave signaling traffic unencrypted; + voice & video WebRTC traffic is always encrypted.) + + * 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. + + * If your TURN server is behind NAT: + + * double-check that your NAT gateway is correctly forwarding all TURN + ports (normally 3478 & 5349 for TCP & 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 `external-ip` 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 `external-ip`. + + * ensure that your TURN server uses the NAT gateway as its default route. + + * 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. On Firefox, check the "Connection Log" on `about:webrtc`. + + (Understanding the output is beyond the scope of this document!) + + * You can test your Matrix homeserver TURN setup with . + Note that this test is not fully reliable yet, so don't be discouraged if + the test fails. + [Here](https://github.com/matrix-org/voip-tester) is the github repo of the + source of the tester, where you can file bug reports. + + * There is a WebRTC test tool at + . 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: + + * Use the following shell commands: + + ```sh + secret=staticAuthSecretHere + + u=$((`date +%s` + 3600)):test + p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64) + echo -e "username: $u\npassword: $p" + ``` + + 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. diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md new file mode 100644 index 000000000000..70c1ae752b8d --- /dev/null +++ b/docs/setup/turn/eturnal.md @@ -0,0 +1,145 @@ +# eturnal TURN server + +The following sections describe how to install [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). + +On **APT-based** Linux distributions, run: + + sudo apt install extrepo + sudo extrepo enable eturnal + sudo apt update + sudo apt install eturnal + +On **DNF-based** Linux distributions, run: + + sudo dnf config-manager --add-repo https://eturnal.net/eturnal.repo + sudo dnf install eturnal + sudo systemctl --now enable eturnal + +On **YUM-based** Linux distributions, run: + + sudo yum-config-manager --add-repo https://eturnal.net/eturnal.repo + sudo yum install eturnal + sudo systemctl --now enable eturnal + +On SUSE Linux Enterprise and openSUSE systems, [distribution repositories](https://software.opensuse.org/download/?package=eturnal&project=devel:languages:erlang) +can be used instead. On other Linux systems, the binary release can be installed +as [described](https://eturnal.net/documentation/#Installation) in the reference documentation. For Windows, an installer is +[available](https://eturnal.net/windows/). On other platforms, `eturnal` is [built from source](https://github.com/processone/eturnal/blob/master/INSTALL.md). + +### Configuration + +1. Create or edit the config file in `/etc/eturnal.yml`. + See the [example configuration](https://github.com/processone/eturnal/blob/master/config/eturnal.yml) for explanations of the options. + + The relevant lines, with example values, are: + + ```yaml + eturnal: + secret: "long-and-cryptic" # Shared secret, CHANGE THIS. + ``` + + One way to generate the `secret` is with `pwgen`: + + ```sh + pwgen -s 64 1 + ``` + +1. 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, 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. 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. 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 block further recommend address ranges, uncomment the `- recommended` part in the configuration file. + +1. 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 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. (Re)start the turn server: + + ```sh + eturnalctl reload + ``` + +### 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 querrz how many active sessions exist, to change logging behaviour and so on. \ No newline at end of file diff --git a/docs/turn-howto.md b/docs/turn-howto.md index 37a311ad9cc7..7164d0e3f46e 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -9,199 +9,19 @@ 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]() (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 with `eturnal` to work, it 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 @@ -263,7 +83,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 +108,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 +144,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 +154,14 @@ 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 From a9be337d811b21187b432c21a9aba092ef2332a4 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 26 Oct 2022 11:23:59 +0200 Subject: [PATCH 02/23] Update docs/turn-howto.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> --- docs/turn-howto.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/turn-howto.md b/docs/turn-howto.md index 7164d0e3f46e..2bad73b566bd 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -161,7 +161,9 @@ Here are a few things to try: ``` - * 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: + * 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 From 6a903ec97aa9761df5903e1c5bb724b0142b76e5 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 26 Oct 2022 11:24:15 +0200 Subject: [PATCH 03/23] Update docs/setup/turn/coturn.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> --- docs/setup/turn/coturn.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index b3d53e3ad011..0a614ceb7d46 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -213,10 +213,12 @@ Your homeserver configuration file needs the following extra keys: 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: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] - turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" - turn_user_lifetime: 86400000 - turn_allow_guests: True +``` +turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] +turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" +turn_user_lifetime: 86400000 +turn_allow_guests: True +``` After updating the homeserver configuration, you must restart synapse: From ea104f06df08135a022df56c1487cc9f82f10a61 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 26 Oct 2022 11:24:54 +0200 Subject: [PATCH 04/23] Update docs/setup/turn/eturnal.md Co-authored-by: Dirk Klimpel <5740567+dklimpel@users.noreply.github.com> --- docs/setup/turn/eturnal.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 70c1ae752b8d..4e21ecd41984 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -10,10 +10,12 @@ The `eturnal` TURN server implementation is available from a variety of sources On **APT-based** Linux distributions, run: - sudo apt install extrepo - sudo extrepo enable eturnal - sudo apt update - sudo apt install eturnal +```sh +sudo apt install extrepo +sudo extrepo enable eturnal +sudo apt update +sudo apt install eturnal +``` On **DNF-based** Linux distributions, run: From 86bac4eaed331354171dd368c5648105f6ac3569 Mon Sep 17 00:00:00 2001 From: Saarko Date: Wed, 26 Oct 2022 10:47:09 +0200 Subject: [PATCH 05/23] Fix TURN relaying public IP address hint --- docs/turn-howto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/turn-howto.md b/docs/turn-howto.md index 2bad73b566bd..ed002e566503 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -16,7 +16,7 @@ This documentation provides two TURN server configuration examples: ## Requirements -For TURN relaying with `eturnal` to work, it must be hosted on a server/endpoint with a public IP. +For TURN relaying to work, it 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. From 3f3f925f47e43a4f9f0b9fe76085925328868f12 Mon Sep 17 00:00:00 2001 From: Saarko Date: Wed, 26 Oct 2022 11:29:56 +0200 Subject: [PATCH 06/23] lint eturnal installation commands --- docs/setup/turn/eturnal.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 4e21ecd41984..8f8dc49619c6 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -19,15 +19,19 @@ sudo apt install eturnal On **DNF-based** Linux distributions, run: - sudo dnf config-manager --add-repo https://eturnal.net/eturnal.repo - sudo dnf install eturnal - sudo systemctl --now enable eturnal +```sh +sudo dnf config-manager --add-repo https://eturnal.net/eturnal.repo +sudo dnf install eturnal +sudo systemctl --now enable eturnal +``` On **YUM-based** Linux distributions, run: - sudo yum-config-manager --add-repo https://eturnal.net/eturnal.repo - sudo yum install eturnal - sudo systemctl --now enable eturnal +```sh +sudo yum-config-manager --add-repo https://eturnal.net/eturnal.repo +sudo yum install eturnal +sudo systemctl --now enable eturnal +``` On SUSE Linux Enterprise and openSUSE systems, [distribution repositories](https://software.opensuse.org/download/?package=eturnal&project=devel:languages:erlang) can be used instead. On other Linux systems, the binary release can be installed From d804d26e6ce77fe049ee685dd9d19f8db9f7058a Mon Sep 17 00:00:00 2001 From: Saarko Date: Wed, 26 Oct 2022 11:42:47 +0200 Subject: [PATCH 07/23] Adjust synapse setup to link to existing documentation ..avoid redundant information. --- docs/turn-howto.md | 24 +++++------------------- 1 file changed, 5 insertions(+), 19 deletions(-) diff --git a/docs/turn-howto.md b/docs/turn-howto.md index ed002e566503..eaabb7644061 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -16,7 +16,7 @@ This documentation provides two TURN server configuration examples: ## Requirements -For TURN relaying 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. @@ -27,24 +27,10 @@ Afterwards, the homeserver needs some further configuration. 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. From 637c381655ba7123a55a69ac1f49b7f41170de65 Mon Sep 17 00:00:00 2001 From: Saarko Date: Wed, 26 Oct 2022 13:50:14 +0200 Subject: [PATCH 08/23] remove redundant text --- docs/setup/turn/coturn.md | 148 -------------------------------------- 1 file changed, 148 deletions(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index 0a614ceb7d46..fe360bc41ce9 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -186,151 +186,3 @@ This will install and start a systemd service called `coturn`. ```sh bin/turnserver -o ``` - -## 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. - -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: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ] -turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons" -turn_user_lifetime: 86400000 -turn_allow_guests: True -``` - -After updating the homeserver configuration, you must restart synapse: - - * If you use synctl: - ```sh - # Depending on how Synapse is installed, synctl may already be on - # your PATH. If not, you may need to activate a virtual environment. - synctl restart - ``` - * If you use systemd: - ```sh - systemctl restart matrix-synapse.service - ``` -... and then reload any clients (or wait an hour for them to refresh their -settings). - -## 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 you have opened your firewall to allow TCP and UDP traffic to the - TURN ports (normally 3478 and 5349). - - * 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) - TCP/UDP listeners. (This will only leave signaling traffic unencrypted; - voice & video WebRTC traffic is always encrypted.) - - * 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. - - * If your TURN server is behind NAT: - - * double-check that your NAT gateway is correctly forwarding all TURN - ports (normally 3478 & 5349 for TCP & 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 `external-ip` 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 `external-ip`. - - * ensure that your TURN server uses the NAT gateway as its default route. - - * 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. On Firefox, check the "Connection Log" on `about:webrtc`. - - (Understanding the output is beyond the scope of this document!) - - * You can test your Matrix homeserver TURN setup with . - Note that this test is not fully reliable yet, so don't be discouraged if - the test fails. - [Here](https://github.com/matrix-org/voip-tester) is the github repo of the - source of the tester, where you can file bug reports. - - * There is a WebRTC test tool at - . 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: - - * Use the following shell commands: - - ```sh - secret=staticAuthSecretHere - - u=$((`date +%s` + 3600)):test - p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64) - echo -e "username: $u\npassword: $p" - ``` - - 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. From ee5330c3a1ab9fa314b576410bed35fc06cb6eb9 Mon Sep 17 00:00:00 2001 From: Saarko Date: Wed, 26 Oct 2022 14:47:36 +0200 Subject: [PATCH 09/23] include alpine linux package link --- docs/setup/turn/eturnal.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 8f8dc49619c6..795a73155769 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -34,14 +34,16 @@ sudo systemctl --now enable eturnal ``` On SUSE Linux Enterprise and openSUSE systems, [distribution repositories](https://software.opensuse.org/download/?package=eturnal&project=devel:languages:erlang) -can be used instead. On other Linux systems, the binary release can be installed -as [described](https://eturnal.net/documentation/#Installation) in the reference documentation. For Windows, an installer is -[available](https://eturnal.net/windows/). On other platforms, `eturnal` is [built from source](https://github.com/processone/eturnal/blob/master/INSTALL.md). +can be used instead. There is an official [AlpineLinux package](https://pkgs.alpinelinux.org/packages?name=eturnal) +available. On other Linux systems, the binary release can be installed as [described](https://eturnal.net/documentation/#Installation) +in the reference documentation. For Windows, an installer is [available](https://eturnal.net/windows/). +On other platforms, `eturnal` is [built from source](https://github.com/processone/eturnal/blob/master/INSTALL.md). ### Configuration 1. Create or edit the config file in `/etc/eturnal.yml`. - See the [example configuration](https://github.com/processone/eturnal/blob/master/config/eturnal.yml) for explanations of the options. + See the [example configuration](https://github.com/processone/eturnal/blob/master/config/eturnal.yml) + for explanations of the options. The relevant lines, with example values, are: From 863bdf50c7699f73d1eb9be719073eb3d87ce177 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sat, 29 Oct 2022 19:26:04 +0200 Subject: [PATCH 10/23] Create 14293.doc --- changelog.d/14293.doc | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog.d/14293.doc diff --git a/changelog.d/14293.doc b/changelog.d/14293.doc new file mode 100644 index 000000000000..88c6cc2752b1 --- /dev/null +++ b/changelog.d/14293.doc @@ -0,0 +1 @@ +Add addtional TURN server configuration example based on [eturnal](https://github.com/processone/eturnal) and adjust general TURN server doc structure From 40519a04e604e2b7b4d0e488ecba168270efa336 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sat, 29 Oct 2022 19:27:33 +0200 Subject: [PATCH 11/23] Update 14293.doc add missing dot --- changelog.d/14293.doc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog.d/14293.doc b/changelog.d/14293.doc index 88c6cc2752b1..d6410421e713 100644 --- a/changelog.d/14293.doc +++ b/changelog.d/14293.doc @@ -1 +1 @@ -Add addtional TURN server configuration example based on [eturnal](https://github.com/processone/eturnal) and adjust general TURN server doc structure +Add addtional TURN server configuration example based on [eturnal](https://github.com/processone/eturnal) and adjust general TURN server doc structure. From f1e309b1dc49facdd0fe7bb56bdc4c62ef3cfd0e Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Fri, 4 Nov 2022 17:46:33 +0100 Subject: [PATCH 12/23] Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre --- docs/setup/turn/eturnal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 795a73155769..02cbdc2c0b25 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -150,4 +150,4 @@ On other platforms, `eturnal` is [built from source](https://github.com/processo ### 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 querrz how many active sessions exist, to change logging behaviour and so on. \ No newline at end of file +`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. \ No newline at end of file From 55e719ea0d0ddfc307a33e9f1980ba939abd271c Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Fri, 4 Nov 2022 17:58:12 +0100 Subject: [PATCH 13/23] Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre --- docs/setup/turn/eturnal.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 02cbdc2c0b25..f789d2c3ba80 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -105,14 +105,12 @@ On other platforms, `eturnal` is [built from source](https://github.com/processo ```yaml listen: - - - ip: "::" - port: 3478 - transport: udp - - - ip: "::" - port: 3478 - transport: tcp + - ip: "::" + port: 3478 + transport: udp + - ip: "::" + port: 3478 + transport: tcp #- # ip: "::" # port: 5349 From 05744958aa4b8ceb526b94c98bf6b0b48084cf12 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sun, 6 Nov 2022 14:54:16 +0100 Subject: [PATCH 14/23] Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index fe360bc41ce9..4719091a079f 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -37,7 +37,7 @@ This will install and start a systemd service called `coturn`. ```sh make - make install + sudo make install ``` ### Configuration From 3d0e269456598b2e7d8073a35903bd08d39c4cc7 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sun, 6 Nov 2022 14:54:33 +0100 Subject: [PATCH 15/23] Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index 4719091a079f..67db5a64be6c 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -8,7 +8,7 @@ The following sections describe how to install [coturn]( Date: Sun, 6 Nov 2022 14:55:05 +0100 Subject: [PATCH 16/23] Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index 67db5a64be6c..95e09633dbf3 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -13,7 +13,7 @@ The TURN daemon `coturn` is available from a variety of sources such as native p Just install the debian package: ```sh -apt install coturn +sudo apt install coturn ``` This will install and start a systemd service called `coturn`. From 86cdf8af709f7a9f4b594644c995578aef12f279 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sun, 6 Nov 2022 14:55:34 +0100 Subject: [PATCH 17/23] Update docs/setup/turn/eturnal.md Co-authored-by: reivilibre --- docs/setup/turn/eturnal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index f789d2c3ba80..dda02491645e 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -92,7 +92,7 @@ On other platforms, `eturnal` is [built from source](https://github.com/processo 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 + - 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. From 462ba9c256aca8ab5f93ead137a74b2cf3765a91 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sun, 6 Nov 2022 14:55:54 +0100 Subject: [PATCH 18/23] Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index 95e09633dbf3..5a8d08750ea9 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -178,7 +178,7 @@ This will install and start a systemd service called `coturn`. * If you used the Debian package (or have set up a systemd unit yourself): ```sh - systemctl restart coturn + sudo systemctl restart coturn ``` * If you installed from source: From 747c56cdc8982794481547c898fc1aa9d5514f03 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Sun, 6 Nov 2022 14:56:25 +0100 Subject: [PATCH 19/23] Update docs/setup/turn/coturn.md Co-authored-by: Moritz Dietz --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index 5a8d08750ea9..a6d11321a852 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -181,7 +181,7 @@ This will install and start a systemd service called `coturn`. sudo systemctl restart coturn ``` - * If you installed from source: + * If you built from source: ```sh bin/turnserver -o From 91cbad2ad974b85e6ccb56b67bbee4b23fe310c5 Mon Sep 17 00:00:00 2001 From: Saarko Date: Sun, 6 Nov 2022 16:10:56 +0100 Subject: [PATCH 20/23] Update eturnal.md to link to official documentation ... and to simplify some aspects --- docs/setup/turn/eturnal.md | 167 ++++++++++++++++++++----------------- 1 file changed, 92 insertions(+), 75 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index dda02491645e..4de8ff27aed7 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -1,77 +1,69 @@ # eturnal TURN server -The following sections describe how to install [eturnal]() (which implements the TURN REST API). +The following sections describe how to install [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). +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). -On **APT-based** Linux distributions, run: +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. -```sh -sudo apt install extrepo -sudo extrepo enable eturnal -sudo apt update -sudo apt install eturnal -``` - -On **DNF-based** Linux distributions, run: - -```sh -sudo dnf config-manager --add-repo https://eturnal.net/eturnal.repo -sudo dnf install eturnal -sudo systemctl --now enable eturnal -``` +### Configuration -On **YUM-based** Linux distributions, run: +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. -```sh -sudo yum-config-manager --add-repo https://eturnal.net/eturnal.repo -sudo yum install eturnal -sudo systemctl --now enable eturnal -``` +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/). -On SUSE Linux Enterprise and openSUSE systems, [distribution repositories](https://software.opensuse.org/download/?package=eturnal&project=devel:languages:erlang) -can be used instead. There is an official [AlpineLinux package](https://pkgs.alpinelinux.org/packages?name=eturnal) -available. On other Linux systems, the binary release can be installed as [described](https://eturnal.net/documentation/#Installation) -in the reference documentation. For Windows, an installer is [available](https://eturnal.net/windows/). -On other platforms, `eturnal` is [built from source](https://github.com/processone/eturnal/blob/master/INSTALL.md). +`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: -### Configuration +1. Homeserver's [`turn_shared_secret`](../../usage/configuration/config_documentation.md#turn_shared_secret) + and eturnal's shared `secret` for authentication -1. Create or edit the config file in `/etc/eturnal.yml`. - See the [example configuration](https://github.com/processone/eturnal/blob/master/config/eturnal.yml) - for explanations of the options. - - The relevant lines, with example values, are: + Both need to have the same value. Uncomment and adjust this line in `eturnal`'s + configuration file: ```yaml - eturnal: - secret: "long-and-cryptic" # Shared secret, CHANGE THIS. + secret: "long-and-cryptic" # Shared secret, CHANGE THIS. ``` - One way to generate the `secret` is with `pwgen`: + One way to generate a `secret` is with `pwgen`: ```sh pwgen -s 64 1 ``` -1. 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, so `eturnal` advertises that - address to connecting clients: +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. + 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). + 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 @@ -79,50 +71,65 @@ On other platforms, `eturnal` is [built from source](https://github.com/processo 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. If eturnal was started by systemd, log files are written into the +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. Consider your security settings. TURN lets users request a relay which will +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. + ## 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 block further recommend address ranges, uncomment the `- recommended` part in the configuration file. + To whitelist IP addresses or specific (private) networks, you need to **add** a + whitelist part into the configuration file, e.g.: -1. Also consider supporting TLS/DTLS. To do this, adjust the following settings + ```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 + 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 the `turn_uris` settings below - with `turns:`. + 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. @@ -135,17 +142,27 @@ On other platforms, `eturnal` is [built from source](https://github.com/processo [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 +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. (Re)start the turn server: +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. \ No newline at end of file +`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. \ No newline at end of file From 90c93c0424b14f600249d6c8aa3e69e75748502d Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Thu, 10 Nov 2022 09:32:23 +0100 Subject: [PATCH 21/23] Adjust coturn to link to default prefix --- docs/setup/turn/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/setup/turn/coturn.md b/docs/setup/turn/coturn.md index a6d11321a852..a1bb1e934c21 100644 --- a/docs/setup/turn/coturn.md +++ b/docs/setup/turn/coturn.md @@ -184,5 +184,5 @@ This will install and start a systemd service called `coturn`. * If you built from source: ```sh - bin/turnserver -o + /usr/local/bin/turnserver -o ``` From b5c994cbb49664793ca7a66926ecf8f18d8bc28a Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Fri, 11 Nov 2022 17:19:56 +0100 Subject: [PATCH 22/23] Mention eturnalctl location --- docs/setup/turn/eturnal.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/setup/turn/eturnal.md b/docs/setup/turn/eturnal.md index 4de8ff27aed7..2e5a45673ec5 100644 --- a/docs/setup/turn/eturnal.md +++ b/docs/setup/turn/eturnal.md @@ -73,7 +73,7 @@ must be edited: 1. Logging - If eturnal was started by systemd, log files are written into the + 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. @@ -165,4 +165,6 @@ must be edited: `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. \ No newline at end of file +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` From 4509067688d25df2f3f1af5d496ea0d17919aade Mon Sep 17 00:00:00 2001 From: reivilibre Date: Mon, 14 Nov 2022 17:53:13 +0000 Subject: [PATCH 23/23] Update docs/turn-howto.md --- docs/turn-howto.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/turn-howto.md b/docs/turn-howto.md index eaabb7644061..b466cab40c1c 100644 --- a/docs/turn-howto.md +++ b/docs/turn-howto.md @@ -27,10 +27,10 @@ Afterwards, the homeserver needs some further configuration. Your homeserver configuration file needs the following extra keys: -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) +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.