From f95d0157a5ff389540808be586c8d6ce8f3ea0f9 Mon Sep 17 00:00:00 2001 From: sando38 Date: Wed, 21 Jun 2023 12:22:45 +0200 Subject: [PATCH 1/5] Documentation: Add eturnal as a second TURN server example Also create additonal documents accordingly. Signed-off-by: sando38 --- docs/TURN.md | 163 +++++------------------------------------------- docs/coturn.md | 153 +++++++++++++++++++++++++++++++++++++++++++++ docs/eturnal.md | 147 +++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 +- mkdocs.yml | 5 +- 5 files changed, 322 insertions(+), 150 deletions(-) create mode 100644 docs/coturn.md create mode 100644 docs/eturnal.md diff --git a/docs/TURN.md b/docs/TURN.md index 5ea5ab40b8b..cf538a3642a 100644 --- a/docs/TURN.md +++ b/docs/TURN.md @@ -1,4 +1,4 @@ -# CoTURN configuration +# TURN server configuration ### Background The configuration of Nextcloud Talk mainly depends on your desired usage: @@ -19,153 +19,14 @@ The High Performance Backend uses a certain range of ports for WebRTC media conn For maximum compatibility the TURN server should be configured to listen on port 443. Therefore, when both a TURN server and the High Performance Backend are used each one should run in its own server, or in the same server but each one with its own IP address, as the High Performance Backend will need to bind to port 443 too. -## Install and setup _coTURN_ as TURN server +## Install and setup your TURN server -It is recommended to install the latest _coTURN_ version; at the very minimum _coTURN_ 4.5.0.8 should be used. In previous versions there is a bug that causes [the IPv6 UDP sockets created by coTURN not to be freed](https://github.com/coturn/coturn/issues/217). Due to this the _turn_ process ends not being able to open new ports and thus not being able to serve new connections. Moreover, when that happens, even if there are no connections a high CPU load will be caused by the _turn_ process. Therefore, if you can not install _coTURN_ 4.5.0.8 or a later version you should restart the _turn_ process periodically to work around that issue. +This documentation provides two examples for TURN server implementations: -#### 1. Download and install +* [coturn](coturn.md) +* [eturnal](eturnal.md) -- On **Debian and Ubuntu** there are official repository packages available: - ``` - sudo apt install coturn - ``` -- For many **other Linux derivatives and UNIX-likes** packages can be found on [https://pkgs.org/download/coturn](https://pkgs.org/download/coturn) -- For all **other** cases check out the [Downloads in the wiki of coTURN](https://github.com/coturn/coturn/wiki/Downloads) - - -#### 2. Make coturn run as daemon on startup - -- On **Debian and Ubuntu** you just need to enable the deployed sysvinit service by adjusting the related environment variable: - ``` - sudo sed -i '/TURNSERVER_ENABLED/c\TURNSERVER_ENABLED=1' /etc/default/coturn - ``` - -- Since **Debian Buster** and **Ubuntu disco** the package ships a systemd unit, which does not use `/etc/default/coturn` but is enabled automatically on installation. To check whether a systemd unit is available: - ``` - ls -l /lib/systemd/system/coturn.service - ``` - -- If you installed coTURN manually, you may want to create a sysvinit service or systemd unit, or use another method to run the following during boot: - ``` - /path/to/turnserver -c /path/to/turnserver.conf -o - ``` - -- `-o` starts the server in daemon mode, `-c` defines the path to the config file. -- There is also an official example available at [https://github.com/coturn/coturn/blob/master/examples/etc/coturn.service](https://github.com/coturn/coturn/blob/master/examples/etc/coturn.service) - -##### Running coTURN on privileged ports - -On some GNU/Linux distributions (for example, **Ubuntu Focal and later**) when _coTURN_ is installed from the official package the _coturn_ service is executed as an unprivileged user like _turnserver_. Due to this by default _coTURN_ can not use privileged ports, like port 443. - -Depending on the system configuration Linux kernel capabilities could be used to overcome this limitation. Capabilities can be associated with executable files using _setcap_, so you could allow the _/usr/bin/turnserver_ executable to bind sockets to privileged ports with: -``` -setcap cap_net_bind_service=+ep /usr/bin/turnserver -``` - -Alternatively, if the system configuration does not allow to set the capability, or if the coturn process needs to access files only readable by root like an SSL certificate for TLS connections, you could configure the _coturn_ service to be executed by root instead of the unprivileged user by executing: -``` -systemctl edit coturn -``` -and then setting the following configuration, which will override the default one: -``` -[Service] -User=root -Group=root -``` - -#### 3. Configure `turnserver.conf` for usage with Nextcloud Talk - -- Next you need to adjust the coTURN configuration file to work with Nextcloud Talk. -- Choose the listening port (default is _3478_) and an authentication secret, where a random hex is recommended - ``` - openssl rand -hex 32 - ``` - -- Then uncomment/edit the following settings accordingly: - -``` -listening-port= -fingerprint -lt-cred-mech # Only on coTURN below v4.5.0.8! -use-auth-secret -static-auth-secret= -realm=your.domain.org -total-quota=0 -bps-capacity=0 -stale-nonce -no-loopback-peers # Only on coTURN below v4.5.1.0! -no-multicast-peers -``` - -- Support for TLS connections to the TURN server has been added in Talk 11. In some cases clients can be behind very restrictive firewalls that only allow TLS connections; in those cases the clients would be able to connect with other clients or the High Performance Backend only through a TURN server and a TLS connection. However, please note that TLS connections do not provide any additional security, as media streams are always end-to-end* encrypted in WebRTC; enabling TLS is just a matter of providing the maximum compatibility. - - * When the High Performance Backend is used the High Performance Backend is one of the ends; in that case the media streams are not end-to-end encrypted between the participants but only between participants and the High Performance Backend. - - Also note that even with TURN over TLS a client may not be able to connect with the TURN server if the firewall performs deep packet inspection and drops packets to port 443 that are not really HTTPS packets. This would be a corner case, though, as given that the connection is encrypted in order to inspect the packets that means that the firewall acts as a man-in-the-middle and the connection is not actually encrypted end-to-end. There is nothing that can be done in that case, but it should be rather uncommon. - - In order to use TLS connections to the TURN server the TURN server requires an SSL certificate and, therefore, a domain. The path to the certificate file must be set in the [`cert` parameter](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L442-L446), and the private key file must be set in the [`pkey` file](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L448-L452). Besides that in [Talk settings](#4-configure-nextcloud-talk-to-use-your-turn-server) you must set the TURN server scheme as `turns:` or `turn: and turns:`. - - Note that, even if TLS provides the maximum compatibility, using a domain can cause problems with Firefox on a very specific scenario: [currently Firefox does not perform DNS requests through HTTP tunnels](https://bugzilla.mozilla.org/show_bug.cgi?id=1239006), so even if the WebRTC connection would work through the TURN server the TURN server may not be reachable. - -- The recommended listening port is port 443, even if only _turn:_ but not _turns:_ is used. In some cases firewalls restrict connections only to port 443, but they do not actually check whether the connection is a TLS connection or not. Nevertheless, as mentioned above using both _turn:_ and _turns:_ is recommended for maximum compatibility. - -- The `total-quota` parameter limits the number of allowed simultaneous connections to the TURN server. Along with [`max-bps` and `bps-capacity`](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L414-L423) it can be used to limit the effects of a [DoS attack against the TURN server](https://tools.ietf.org/html/rfc8656#section-21.3.1). The value of _0_ shown above means _unlimited_; if a connection limit is desired it should be adjusted depending on your specific setup. - - Please note that the number of allowed simultaneous connections limited by `total-quota` are not only fully established connections, but also the connections being tested during the negotiation phase used to establish the actual connection. During the negotiation phase each peer generates several candidates (an IP address and port) that can be used to establish a connection with that peer. Then the peers try to establish a connection between them with different candidate combinations until a valid one is found. If there is a TURN server, then the client will connect to the TURN server too, and it will generate additional candidates with the IP address of the TURN server (the so-called "relay" candidates). Each of those relay candidates will try to connect to the candidates of the other peer, and each of those connection attempts allocates a slot in the available quota of the TURN server. If there are no more available slots "Allocation Quota Reached" message is written to coTURN logs. - - In most cases the candidates that will be generated, and thus the connections to the TURN server during the negotiation phase, can not be known beforehand. When Janus is used the number of candidate combinations is reduced, as the Janus candidates can be known, but the number of relay candidates that will be generated by the client may still be unknown. For example, it seems that browsers generate one relay candidate for each host candidate. Host candidates are those with the IP address known to the client, so typically there will be one for each network device in the system; in the case of Firefox host candidates are also generated for the IP addresses of local bridge network devices. - - You should take all that into account if you intend to set a specific value to the `total-quota` parameter, but for maximum availability an unlimited quota is recommended. - -- If your TURN server is running **not behind a NAT**, but with direct www connection and **static public IP**, than you can limit the IPs it listens at and answers with, by setting those as `listening-ip` and `relay-ip`. On larger deployments it is recommended to run your TURN server on a dedicated machine that is directly accessible from the internet. - -- The following settings can be used to adjust the **logging behaviour**. On SBCs with SDcards you may want to adjust this, as by default coTURN logs very verbose. The config file explains everything very well: - -``` -no-stdout-log -log-file=... -syslog -simple-log -``` - -- `sudo systemctl restart coturn` or corresponding restart method - -##### Disabling UDP or TCP protocols - -Unless you have some special need, you should always enable both UDP and TCP protocols in your TURN server, as that provides the maximum compatibility. However, if you must limit the connections from clients to the TURN server through UDP or TCP protocols you can do that by enabling one the following settings, depending on the case: -``` -no-udp -no-tcp -``` - -Please note that those settings only limit the protocols from the client to the TURN server. The relayed protocol from the TURN server to the other end (Janus if the High Performance Backend is being used, another client or TURN server if it is not) must be UDP; _coTURN_ provides the setting `no-udp-relay` to disable the UDP protocol for the relayed connection, but enabling it would cause the TURN server to be unusable in a WebRTC context. - -Also keep in mind that disabling the UDP protocol from clients to the TURN server with `no-udp` in practice disables STUN on that server, as neither Janus nor the clients currently support STUN over TCP. - -##### TURN server and internal networks - -If your TURN server has access to an internal network you should prevent access to the local/internal IPs from the TURN server, except those that are actually needed (like the High Performance Backend if you are using it) by setting the [`denied-peer-ip` and `allowed-peer-ip` parameters](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L523-L537). For example: -``` -allowed-peer-ip={IP_ADDRESS_OF_THE_HIGH_PERFORMANCE_BACKEND} -denied-peer-ip=0.0.0.0-0.255.255.255 -denied-peer-ip=10.0.0.0-10.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=172.16.0.0-172.31.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=192.168.0.0-192.168.255.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 -``` - -Otherwise, [a malicious user could access services in that internal network through your TURN server](https://www.rtcsec.com/2020/04/01-slack-webrtc-turn-compromise/). - -Alternatively you could of course prevent access to that internal network from the TURN server by means of a firewall. +After you have setup the server part above, continue here on this page with the following steps. #### 4. Configure Nextcloud Talk to use your TURN server @@ -188,9 +49,9 @@ If you need to retain the previous behaviour you should now do it by external me #### 5. Port opening/forwarding -- The TURN server on `` needs to be accessible for all Talk participants, so you need to open it to the web and if your TURN server is running **behind a NAT**, forward it to the related machine. Also make sure to set the [`--external-ip` option](https://github.com/coturn/coturn/wiki/turnserver#options) when your TURN server is in a private network. +- The TURN server on `` needs to be accessible for all Talk participants, so you need to open it to the web and if your TURN server is running **behind a NAT**, forward it to the related machine. Also make sure to set coturn's [`--external-ip` option](https://github.com/coturn/coturn/wiki/turnserver#options) or eturnal's [`relay_ipv4_addr` configuration item](https://eturnal.net/documentation/#relay_ipv4_addr) when your TURN server is in a private network. -- If the High Performance Backend is used the TURN server and the High Performance Backend must be able to reach each other. If set, the `external-ip` option defines the IP address of the TURN server that the High Performance Backend will try to connect to. Therefore, if both the TURN server and the High Performance Backend are in the same private network they may be able to reach each other using their local IP addresses, and thus it may not be needed to set the `external-ip` option. Moreover, when both servers are behind a firewall, in some cases (depending on the firewall configuration) setting the external IP can even cause the TURN server and the High Performance Backend to fail to reach each other (for example, if the firewall is not able to "loop" a packet from an internal address to an external one which then should go back to another internal address). +- If the High Performance Backend is used the TURN server and the High Performance Backend must be able to reach each other. If set, the `external-ip` option/`relay_ipv4_addr` parameter defines the IP address of the TURN server that the High Performance Backend will try to connect to. Therefore, if both the TURN server and the High Performance Backend are in the same private network they may be able to reach each other using their local IP addresses, and thus it may not be needed to set the `external-ip` option/`relay_ipv4_addr` parameter. Moreover, when both servers are behind a firewall, in some cases (depending on the firewall configuration) setting the external IP can even cause the TURN server and the High Performance Backend to fail to reach each other (for example, if the firewall is not able to "loop" a packet from an internal address to an external one which then should go back to another internal address). * Note that in some cases additional addresses can be found during the negotiation of the connection, the so-called peer reflexive candidates. Due to this even if the external IP of the TURN server is not reachable by the High Performance Backend the connection may still work, but this should not be relied on. @@ -198,7 +59,9 @@ If you need to retain the previous behaviour you should now do it by external me ##### Test if the TURN server is accessible from outside -Install _coTURN_ on your client. Please [refer above for details](#1-download-and-install). Note that in the case of the client you only need to install it, you do not need to perform any configuration after that. +For _coTURN_: + +Install _coTURN_ on your client. Please [refer above for details](coturn/#1-download-and-install). Note that in the case of the client you only need to install it, you do not need to perform any configuration after that. Run `turnutils_uclient -p -W -v -y turn.example.com` where @@ -231,6 +94,10 @@ Further you should see in the TURN server log the successful connection. This test only verifies that your TURN server is accessible from the outside, but it does not check if your TURN server can be actually used within Talk. For that please keep reading. +For _eturnal_: + +The easiest way is to refer to eturnal's Quick-Start guide, e.g. [in a 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). + ##### Test the TURN server connection from within Talk When the TURN server is set in the Talk settings a basic test against the TURN server is performed. You can perform a deeper test by forcing your browser to send the media of a call only through the TURN server: diff --git a/docs/coturn.md b/docs/coturn.md new file mode 100644 index 00000000000..ee14fdacd47 --- /dev/null +++ b/docs/coturn.md @@ -0,0 +1,153 @@ +# CoTURN configuration + +## Install and setup _coTURN_ as TURN server + +It is recommended to install the latest _coTURN_ version; at the very minimum _coTURN_ 4.5.0.8 should be used. In previous versions there is a bug that causes [the IPv6 UDP sockets created by coTURN not to be freed](https://github.com/coturn/coturn/issues/217). Due to this the _turn_ process ends not being able to open new ports and thus not being able to serve new connections. Moreover, when that happens, even if there are no connections a high CPU load will be caused by the _turn_ process. Therefore, if you can not install _coTURN_ 4.5.0.8 or a later version you should restart the _turn_ process periodically to work around that issue. + +#### 1. Download and install + +- On **Debian and Ubuntu** there are official repository packages available: + ``` + sudo apt install coturn + ``` +- For many **other Linux derivatives and UNIX-likes** packages can be found on [https://pkgs.org/download/coturn](https://pkgs.org/download/coturn) +- For all **other** cases check out the [Downloads in the wiki of coTURN](https://github.com/coturn/coturn/wiki/Downloads) + + +#### 2. Make coturn run as daemon on startup + +- On **Debian and Ubuntu** you just need to enable the deployed sysvinit service by adjusting the related environment variable: + ``` + sudo sed -i '/TURNSERVER_ENABLED/c\TURNSERVER_ENABLED=1' /etc/default/coturn + ``` + +- Since **Debian Buster** and **Ubuntu disco** the package ships a systemd unit, which does not use `/etc/default/coturn` but is enabled automatically on installation. To check whether a systemd unit is available: + ``` + ls -l /lib/systemd/system/coturn.service + ``` + +- If you installed coTURN manually, you may want to create a sysvinit service or systemd unit, or use another method to run the following during boot: + ``` + /path/to/turnserver -c /path/to/turnserver.conf -o + ``` + +- `-o` starts the server in daemon mode, `-c` defines the path to the config file. +- There is also an official example available at [https://github.com/coturn/coturn/blob/master/examples/etc/coturn.service](https://github.com/coturn/coturn/blob/master/examples/etc/coturn.service) + +##### Running coTURN on privileged ports + +On some GNU/Linux distributions (for example, **Ubuntu Focal and later**) when _coTURN_ is installed from the official package the _coturn_ service is executed as an unprivileged user like _turnserver_. Due to this by default _coTURN_ can not use privileged ports, like port 443. + +Depending on the system configuration Linux kernel capabilities could be used to overcome this limitation. Capabilities can be associated with executable files using _setcap_, so you could allow the _/usr/bin/turnserver_ executable to bind sockets to privileged ports with: +``` +setcap cap_net_bind_service=+ep /usr/bin/turnserver +``` + +Alternatively, if the system configuration does not allow to set the capability, or if the coturn process needs to access files only readable by root like an SSL certificate for TLS connections, you could configure the _coturn_ service to be executed by root instead of the unprivileged user by executing: +``` +systemctl edit coturn +``` +and then setting the following configuration, which will override the default one: +``` +[Service] +User=root +Group=root +``` + +#### 3. Configure `turnserver.conf` for usage with Nextcloud Talk + +- Next you need to adjust the coTURN configuration file to work with Nextcloud Talk. +- Choose the listening port (default is _3478_) and an authentication secret, where a random hex is recommended + ``` + openssl rand -hex 32 + ``` + +- Then uncomment/edit the following settings accordingly: + +``` +listening-port= +fingerprint +lt-cred-mech # Only on coTURN below v4.5.0.8! +use-auth-secret +static-auth-secret= +realm=your.domain.org +total-quota=0 +bps-capacity=0 +stale-nonce +no-loopback-peers # Only on coTURN below v4.5.1.0! +no-multicast-peers +``` + +- Support for TLS connections to the TURN server has been added in Talk 11. + + In some cases clients can be behind very restrictive firewalls that only allow TLS connections; in those cases the clients would be able to connect with other clients or the High Performance Backend only through a TURN server and a TLS connection. However, please note that TLS connections do not provide any additional security, as media streams are always end-to-end (When the High Performance Backend is used the High Performance Backend is one of the ends; in that case the media streams are not end-to-end encrypted between the participants but only between participants and the High Performance Backend) encrypted in WebRTC; enabling TLS is just a matter of providing the maximum compatibility. + + Also note that even with TURN over TLS a client may not be able to connect with the TURN server if the firewall performs deep packet inspection and drops packets to port 443 that are not really HTTPS packets. This would be a corner case, though, as given that the connection is encrypted in order to inspect the packets that means that the firewall acts as a man-in-the-middle and the connection is not actually encrypted end-to-end. There is nothing that can be done in that case, but it should be rather uncommon. + + In order to use TLS connections to the TURN server the TURN server requires an SSL certificate and, therefore, a domain. The path to the certificate file must be set in the [`cert` parameter](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L442-L446), and the private key file must be set in the [`pkey` file](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L448-L452). Besides that in [Talk settings](#4-configure-nextcloud-talk-to-use-your-turn-server) you must set the TURN server scheme as `turns:` or `turn: and turns:`. + + Note that, even if TLS provides the maximum compatibility, using a domain can cause problems with Firefox on a very specific scenario: [currently Firefox does not perform DNS requests through HTTP tunnels](https://bugzilla.mozilla.org/show_bug.cgi?id=1239006), so even if the WebRTC connection would work through the TURN server the TURN server may not be reachable. + +- The recommended listening port is port 443, even if only _turn:_ but not _turns:_ is used. In some cases firewalls restrict connections only to port 443, but they do not actually check whether the connection is a TLS connection or not. Nevertheless, as mentioned above using both _turn:_ and _turns:_ is recommended for maximum compatibility. + +- The `total-quota` parameter limits the number of allowed simultaneous connections to the TURN server. Along with [`max-bps` and `bps-capacity`](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L414-L423) it can be used to limit the effects of a [DoS attack against the TURN server](https://tools.ietf.org/html/rfc8656#section-21.3.1). The value of _0_ shown above means _unlimited_; if a connection limit is desired it should be adjusted depending on your specific setup. + + Please note that the number of allowed simultaneous connections limited by `total-quota` are not only fully established connections, but also the connections being tested during the negotiation phase used to establish the actual connection. During the negotiation phase each peer generates several candidates (an IP address and port) that can be used to establish a connection with that peer. Then the peers try to establish a connection between them with different candidate combinations until a valid one is found. If there is a TURN server, then the client will connect to the TURN server too, and it will generate additional candidates with the IP address of the TURN server (the so-called "relay" candidates). Each of those relay candidates will try to connect to the candidates of the other peer, and each of those connection attempts allocates a slot in the available quota of the TURN server. If there are no more available slots "Allocation Quota Reached" message is written to coTURN logs. + + In most cases the candidates that will be generated, and thus the connections to the TURN server during the negotiation phase, can not be known beforehand. When Janus is used the number of candidate combinations is reduced, as the Janus candidates can be known, but the number of relay candidates that will be generated by the client may still be unknown. For example, it seems that browsers generate one relay candidate for each host candidate. Host candidates are those with the IP address known to the client, so typically there will be one for each network device in the system; in the case of Firefox host candidates are also generated for the IP addresses of local bridge network devices. + + You should take all that into account if you intend to set a specific value to the `total-quota` parameter, but for maximum availability an unlimited quota is recommended. + +- If your TURN server is running **not behind a NAT**, but with direct www connection and **static public IP**, than you can limit the IPs it listens at and answers with, by setting those as `listening-ip` and `relay-ip`. On larger deployments it is recommended to run your TURN server on a dedicated machine that is directly accessible from the internet. + +- The following settings can be used to adjust the **logging behaviour**. On SBCs with SDcards you may want to adjust this, as by default coTURN logs very verbose. The config file explains everything very well: + +``` +no-stdout-log +log-file=... +syslog +simple-log +``` + +- `sudo systemctl restart coturn` or corresponding restart method + +##### Disabling UDP or TCP protocols + +Unless you have some special need, you should always enable both UDP and TCP protocols in your TURN server, as that provides the maximum compatibility. However, if you must limit the connections from clients to the TURN server through UDP or TCP protocols you can do that by enabling one the following settings, depending on the case: +``` +no-udp +no-tcp +``` + +Please note that those settings only limit the protocols from the client to the TURN server. The relayed protocol from the TURN server to the other end (Janus if the High Performance Backend is being used, another client or TURN server if it is not) must be UDP; _coTURN_ provides the setting `no-udp-relay` to disable the UDP protocol for the relayed connection, but enabling it would cause the TURN server to be unusable in a WebRTC context. + +Also keep in mind that disabling the UDP protocol from clients to the TURN server with `no-udp` in practice disables STUN on that server, as neither Janus nor the clients currently support STUN over TCP. + +##### TURN server and internal networks + +If your TURN server has access to an internal network you should prevent access to the local/internal IPs from the TURN server, except those that are actually needed (like the High Performance Backend if you are using it) by setting the [`denied-peer-ip` and `allowed-peer-ip` parameters](https://github.com/coturn/coturn/blob/upstream/4.5.1.3/README.turnserver#L523-L537). For example: +``` +allowed-peer-ip={IP_ADDRESS_OF_THE_HIGH_PERFORMANCE_BACKEND} +denied-peer-ip=0.0.0.0-0.255.255.255 +denied-peer-ip=10.0.0.0-10.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=172.16.0.0-172.31.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=192.168.0.0-192.168.255.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 +``` + +Otherwise, [a malicious user could access services in that internal network through your TURN server](https://www.rtcsec.com/2020/04/01-slack-webrtc-turn-compromise/). + +Alternatively you could of course prevent access to that internal network from the TURN server by means of a firewall. + +##### Continue with the integration into Nextcloud Talk + +Now you can go back to the [TURN overview page](TURN/#4-configure-nextcloud-talk-to-use-your-turn-server). diff --git a/docs/eturnal.md b/docs/eturnal.md new file mode 100644 index 00000000000..d8a97490965 --- /dev/null +++ b/docs/eturnal.md @@ -0,0 +1,147 @@ +# eturnal configuration + +## Install and setup _eturnal_ as TURN server + +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. + +#### 1. Download and install + +eturnal 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). + + +#### 2. Make eturnal run as daemon on startup + +- On Linux systems, the eturnal server is usually invoked by systemd. + ``` + sudo systemctl status eturnal + ``` + +- For non-systemd platforms, example init and OpenRC scripts are shipped below the `etc` directory. + + For controlling eturnal, the eturnalctl command can be used; see: + ``` + eturnalctl help + ``` + +##### Running eturnal on privileged ports + +On systemd-managed systems, the systemd unit grants `NET_BIND_SERVICE` capability to the [service](https://github.com/processone/eturnal/blob/29e82f260d369a39bd4a395cb981e914b141875b/config/eturnal.service#L23). + +Depending on the system configuration Linux kernel capabilities could be used to overcome this limitation. Capabilities can be associated with executable files using _setcap_, so you could allow eturnal's process manager _beam.smp_ in eturnal's `lib` directory, e.g.: +``` +setcap 'cap_net_bind_service=+ep' $(find /opt/eturnal -name beam.smp) +``` + +#### 3. Configure `eturnal.yml` for usage with Nextcloud Talk + +- Next you need to adjust eturnal's configuration file in `/etc/eturnal.yml` to work with Nextcloud Talk. This file uses the (indentation-sensitive!) YAML format. The shipped configuration file contains further explanations. +- Choose the listening port (default is _3478_) and an authentication secret, where a random hex is recommended + ``` + openssl rand -hex 32 + ``` + +- Then uncomment/edit the following settings accordingly: + +```yaml +eturnal: + ## Shared secret for deriving temporary TURN credentials (default: $RANDOM): + secret: "long-and-cryptic" # Shared secret, CHANGE THIS. + + ## The server's public IPv4 address (default: autodetected): + #relay_ipv4_addr: "203.0.113.4" + ## The server's public IPv6 address (optional): + #relay_ipv6_addr: "2001:db8::4" + + listen: + - + ip: "::" + port: + transport: udp + - + ip: "::" + port: + transport: tcp +``` + +- Support for TLS connections to the TURN server has been added in Talk 11. + + In some cases clients can be behind very restrictive firewalls that only allow TLS connections; in those cases the clients would be able to connect with other clients or the High Performance Backend only through a TURN server and a TLS connection. However, please note that TLS connections do not provide any additional security, as media streams are always end-to-end (When the High Performance Backend is used the High Performance Backend is one of the ends; in that case the media streams are not end-to-end encrypted between the participants but only between participants and the High Performance Backend) encrypted in WebRTC; enabling TLS is just a matter of providing the maximum compatibility. + + Also note that even with TURN over TLS a client may not be able to connect with the TURN server if the firewall performs deep packet inspection and drops packets to port 443 that are not really HTTPS packets. This would be a corner case, though, as given that the connection is encrypted in order to inspect the packets that means that the firewall acts as a man-in-the-middle and the connection is not actually encrypted end-to-end. There is nothing that can be done in that case, but it should be rather uncommon. + + In order to use TLS connections to the TURN server the TURN server requires an SSL certificate and, therefore, a domain. The path to the certificate file must be set in the [`tls_crt_file` parameter](https://eturnal.net/documentation/#tls_crt_file), and the private key file must be set in the [`tls_key_file` parameter](https://eturnal.net/documentation/#tls_key_file) within eturnal's configuration file as well as corresponding [listen](https://eturnal.net/documentation/#listen)er needs to be enabled. To listen for encrypted and unencrypted traffic on one port, the transport can be set to `auto` for `tcp`/`tls` multiplexing. + +```yaml +eturnal: + ... + listen: + ... + - + ip: "::" + port: + transport: auto + ... + ## 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 + ... +``` + + Besides that in [Talk settings](TURN.md/#4-configure-nextcloud-talk-to-use-your-turn-server) you must set the TURN server scheme as `turns:` or `turn: and turns:`. + + Note that, even if TLS provides the maximum compatibility, using a domain can cause problems with Firefox on a very specific scenario: [currently Firefox does not perform DNS requests through HTTP tunnels](https://bugzilla.mozilla.org/show_bug.cgi?id=1239006), so even if the WebRTC connection would work through the TURN server the TURN server may not be reachable. + +- The recommended listening port is port 443, even if only _turn:_ but not _turns:_ is used. In some cases firewalls restrict connections only to port 443, but they do not actually check whether the connection is a TLS connection or not. Nevertheless, as mentioned above using both _turn:_ and _turns:_ is recommended for maximum compatibility. + +- If your TURN server is running **not behind a NAT**, but with direct www connection and **static public IP**, than you can limit the IPs it listens at and answers with, by setting those as `ip` and `relay_ipv4_addr`/`relay_ipv6_addr` (IPv6 is optional). On larger deployments it is recommended to run your TURN server on a dedicated machine that is directly accessible from the internet. + +- 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. + +- `sudo systemctl restart eturnal` or corresponding restart method + +##### TURN server and internal networks + +If your TURN server has access to an internal network you should prevent access to the local/internal IPs from the TURN server, except those that are actually needed (like the High Performance Backend if you are using it) by setting the `blacklist`, [see also the official documentation](https://eturnal.net/documentation/#blacklist): + +```yaml +eturnal: + ... + ## 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 (like the High Performance Backend if you are using it) or specific (private) networks, you need to **add** a whitelist part into the configuration file, e.g.: + +```yaml +eturnal: + ... + whitelist: + - {IP_ADDRESS_OF_THE_HIGH_PERFORMANCE_BACKEND} + - "192.168.0.0/16" + - "203.0.113.113" + - "2001:db8::/64" + ... +``` + +The more specific, the better. + +Otherwise, [a malicious user could access services in that internal network through your TURN server](https://www.rtcsec.com/2020/04/01-slack-webrtc-turn-compromise/). + +Alternatively you could of course prevent access to that internal network from the TURN server by means of a firewall. + +## 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` + +##### Continue with the integration into Nextcloud Talk + +Now you can go back to the [TURN overview page](TURN/#4-configure-nextcloud-talk-to-use-your-turn-server). diff --git a/docs/index.md b/docs/index.md index 7628a7a07f7..ca020392bbd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,7 +10,9 @@ ## Administration documentation * [Server system requirements](system-requirements.md) -* [Configuring coTURN](TURN.md) +* [Configuring a TURN server](TURN.md) + * [Configuring coTURN](coturn.md) + * [Configuring eturnal](eturnal.md) * [Scalability](scalability.md) * [Call experience](call-experience.md) * [Occ commands](occ.md) diff --git a/mkdocs.yml b/mkdocs.yml index 0f4be21db1c..cd074c28cef 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,7 +21,10 @@ nav: - 'User system requirements': 'user-requirements.md' - 'Administration documentation': - 'Server system requirements': 'system-requirements.md' - - 'Configuring coTURN': 'TURN.md' + - 'Configuring a TURN server': + - 'Overview': 'TURN.md' + - 'coTURN': 'coturn.md' + - 'eturnal': 'eturnal.md' - 'Scalability': 'scalability.md' - 'Call experience': 'call-experience.md' - 'Occ commands': 'occ.md' From 074eaaa00088a81f3d6710470a5681f0521a157e Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 28 Jun 2023 12:48:37 +0200 Subject: [PATCH 2/5] Update docs/coturn.md Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Signed-off-by: sando38 <90323876+sando38@users.noreply.github.com> --- docs/coturn.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/coturn.md b/docs/coturn.md index ee14fdacd47..a826f102b60 100644 --- a/docs/coturn.md +++ b/docs/coturn.md @@ -150,4 +150,4 @@ Alternatively you could of course prevent access to that internal network from t ##### Continue with the integration into Nextcloud Talk -Now you can go back to the [TURN overview page](TURN/#4-configure-nextcloud-talk-to-use-your-turn-server). +Now you can go back to the [TURN overview page](TURN.md#4-configure-nextcloud-talk-to-use-your-turn-server). From 4628c64f7764ae829b5ecb1203fc866980f36715 Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 28 Jun 2023 12:48:54 +0200 Subject: [PATCH 3/5] Update docs/eturnal.md Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Signed-off-by: sando38 <90323876+sando38@users.noreply.github.com> --- docs/eturnal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/eturnal.md b/docs/eturnal.md index d8a97490965..459d59046bd 100644 --- a/docs/eturnal.md +++ b/docs/eturnal.md @@ -144,4 +144,4 @@ Hint: If `eturnalctl` is not part of your `$PATH`, consider either sym-linking i ##### Continue with the integration into Nextcloud Talk -Now you can go back to the [TURN overview page](TURN/#4-configure-nextcloud-talk-to-use-your-turn-server). +Now you can go back to the [TURN overview page](TURN.md#4-configure-nextcloud-talk-to-use-your-turn-server). From bd53ecafbff9c053c2330998f676840ed50e8bdb Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 28 Jun 2023 12:49:04 +0200 Subject: [PATCH 4/5] Update docs/TURN.md Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Signed-off-by: sando38 <90323876+sando38@users.noreply.github.com> --- docs/TURN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/TURN.md b/docs/TURN.md index cf538a3642a..a2fd390ce92 100644 --- a/docs/TURN.md +++ b/docs/TURN.md @@ -61,7 +61,7 @@ If you need to retain the previous behaviour you should now do it by external me For _coTURN_: -Install _coTURN_ on your client. Please [refer above for details](coturn/#1-download-and-install). Note that in the case of the client you only need to install it, you do not need to perform any configuration after that. +Install _coTURN_ on your client. Please [refer above for details](coturn.md#1-download-and-install). Note that in the case of the client you only need to install it, you do not need to perform any configuration after that. Run `turnutils_uclient -p -W -v -y turn.example.com` where From dbdbd73b1ff516fff4d726fd813883220c2e0bbc Mon Sep 17 00:00:00 2001 From: sando38 <90323876+sando38@users.noreply.github.com> Date: Wed, 28 Jun 2023 12:49:13 +0200 Subject: [PATCH 5/5] Update docs/eturnal.md Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Signed-off-by: sando38 <90323876+sando38@users.noreply.github.com> --- docs/eturnal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/eturnal.md b/docs/eturnal.md index 459d59046bd..c593281638f 100644 --- a/docs/eturnal.md +++ b/docs/eturnal.md @@ -87,7 +87,7 @@ eturnal: ... ``` - Besides that in [Talk settings](TURN.md/#4-configure-nextcloud-talk-to-use-your-turn-server) you must set the TURN server scheme as `turns:` or `turn: and turns:`. + Besides that in [Talk settings](TURN.md#4-configure-nextcloud-talk-to-use-your-turn-server) you must set the TURN server scheme as `turns:` or `turn: and turns:`. Note that, even if TLS provides the maximum compatibility, using a domain can cause problems with Firefox on a very specific scenario: [currently Firefox does not perform DNS requests through HTTP tunnels](https://bugzilla.mozilla.org/show_bug.cgi?id=1239006), so even if the WebRTC connection would work through the TURN server the TURN server may not be reachable.