From ba9dc395cba83154fc650d1a7c237edb09f14e22 Mon Sep 17 00:00:00 2001 From: reivilibre Date: Mon, 14 Nov 2022 17:55:58 +0000 Subject: deploy: 64dd8a9c6e43beed32fa1c94fda1d3d80957fef6 --- develop/turn-howto.html | 217 ++++++------------------------------------------ 1 file changed, 27 insertions(+), 190 deletions(-) (limited to 'develop/turn-howto.html') diff --git a/develop/turn-howto.html b/develop/turn-howto.html index 1709c38a2c..d387a50965 100644 --- a/develop/turn-howto.html +++ b/develop/turn-howto.html @@ -76,7 +76,7 @@ @@ -154,192 +154,23 @@ TURN.

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:

+

Requirements

-

For TURN relaying with coturn to work, it must be hosted on a server/endpoint with a public IP.

+

For TURN relaying to work, the TURN service must be hosted on a server/endpoint with a public IP.

Hosting TURN behind NAT requires port forwaring and for the NAT gateway to have a public IP. However, even with appropriate configuration, NAT is known to cause issues and to often not work.

-

coturn setup

-

Initial installation

-

The TURN daemon coturn is available from a variety of sources such as native package managers, or installation from source.

-

Debian installation

-

Just install the debian package:

-
apt install coturn
-
-

This will install and start a systemd service called coturn.

-

Source installation

-
    -
  1. -

    Download the latest release from github. Unpack it and cd into the directory.

    -
    2. -
  2. -

    Configure it:

    -
    ./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.

    -
    3. -
  3. -

    Build and install it:

    -
    make
-make install
-
    -
    4. -
-

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:

    -
    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.

    -
    2. -
  2. -

    You will most likely want to configure coturn to write logs somewhere. The -easiest way is normally to send them to the syslog:

    -
    syslog
-
    -

    (in which case, the logs will be available via journalctl -u coturn on a -systemd system). Alternatively, coturn can be configured to write to a -logfile - check the example config file supplied with coturn.

    -
    3. -
  3. -

    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
-
    -
    4. -
  4. -

    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 -issues as well as the underlying -WebRTC issue. -Consider using a ZeroSSL certificate for your TURN server as a working alternative.

    -
    5. -
  5. -

    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.)

    -
    6. -
  6. -

    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.

    -
    7. -
  7. -

    (Re)start the turn server:

    -
      -
    • -

      If you used the Debian package (or have set up a systemd unit yourself):

      -
      systemctl restart coturn
-
      -
      • -
    • -

      If you installed from source:

      -
      bin/turnserver -o
-
      -
      • -
    -
    8. -
+

Afterwards, the homeserver needs some further configuration.

Synapse setup

Your homeserver configuration file needs the following extra keys:

    -
  1. "turn_uris": This needs to be a yaml list of public-facing URIs -for your TURN server to be given out to your clients. Add separate -entries for each transport your TURN server supports.
    2. -
  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. -
  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. -
  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.
    5. +
  5. turn_uris
    6. +
  6. turn_shared_secret
    7. +
  7. turn_user_lifetime
    8. +
  8. 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.

@@ -378,7 +209,7 @@ TURN ports (normally 3478 and 5349).

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.)

    • @@ -409,9 +240,13 @@ for your TURN server and specify only an IPv4 address as your external-ip<
  • -

    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 for it to become effective):

    +
        ## Logging configuration:
+        log_level: debug
+

    ... and then see if there are any clues in its logs.

  • @@ -439,19 +274,21 @@ 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:

    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:

    +

    or for eturnal

    +
    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
 user=username:password
    @@ -474,7 +311,7 @@ entry in the results.

    -
    @@ -486,7 +323,7 @@ entry in the results.

    - -- cgit 1.5.1