Update documentation for TURN server for 20.04

Author: ffdixon

_posts/2019-02-14-setup-turn-server.md

@@ -9,9 +9,9 @@ order: 4
 
 This document covers how to setup a TURN server for BigBlueButton to allow users behind restrictive firewalls to connect.
 
-# Setup a TURN server
+You can also use [bbb-install.sh](https://github.com/bigbluebutton/bbb-install#install-a-turn-server) to automate the steps in this document.
 
-** This section is being updated for steps to install on Ubuntu 20.04.  If you want to setup a TURN server, please use [bbb-install.sh](https://github.com/bigbluebutton/bbb-install#install-a-turn-server).  **
+# Setup a TURN server
 
 BigBlueButton normally requires a wide range of UDP ports to be available for WebRTC communication. In some network restricted sites or development environments, such as those behind NAT or a firewall that restricts outgoing UDP connections, users may be unable to make outgoing UDP connections to your BigBlueButton server.
 
@@ -44,7 +44,7 @@ Note: coturn will not automatically start until configuration is applied (see be
 
 ## Required DNS Entry
 
-You need to setup a fully qualified domain name that resolves to the external IP address of your turn server.  You'll used this domain name to generate a TLS certificate using Let's Encrypt (next section).
+You need to setup a fully qualified domain name that resolves to the external IP address of your turn server.  You'll use this domain name to generate a TLS certificate using Let's Encrypt (next section).
 
 ## Required Ports
 
@@ -66,41 +66,57 @@ $ sudo apt-get update
 $ sudo apt-get install certbot
 ```
 
-You can then run a `certbot` command like the following to generate the certificate, replacing `turn.example.com` with the domain name of your TURN server:
+You can then run a `certbot` command like the following to generate the certificate, replacing `<turn.example.com>` with the domain name of your TURN server:
 
 ```bash
 $ sudo certbot certonly --standalone --preferred-challenges http \
-    --deploy-hook "systemctl restart coturn" \
-    -d turn.example.com
+    -d <turn.example.com>
+```
+
+Current versions of the certbot command set up automatic renewal by default.  To ensure that the certificates are readable by `coturn`, which runs as the `turnserver` user, add the following renewal-hook to Let's Encrypt.  First, create the directory `/etc/letsencrypt/renewal-hooks/deploy`.
+
+
+```bash
+$ sudo mkdir -p /etc/letsencrypt/renewal-hooks/deploy
+```
+
+Next, create the file `/etc/letsencrypt/renewal-hooks/deploy/coturn` with the following contents.  Replace <turn.example.com> with the hostname of your TURN server.
+
+```
+#!/bin/bash -e
+for certfile in fullchain.pem privkey.pem ; do
+	cp -L /etc/letsencrypt/live/<turn.example.com>/"${certfile}" /etc/turnserver/"${certfile}".new
+	chown turnserver:turnserver /etc/turnserver/"${certfile}".new
+	mv /etc/turnserver/"${certfile}".new /etc/turnserver/"${certfile}"
+done
+systemctl kill -sUSR2 coturn.service
 ```
 
-Current versions of the certbot command set up automatic renewal by default.  Note that when certbot renews the certificate, it will restart coturn so coturn will start to use the updated certificate files. This will interrupt any ongoing TURN connections. You may wish to change the schedule of certbot renewals or disable automatic renewal if this is a concern.
+Make this file executable.
+
+```
+$ sudo chmod 0755 /etc/letsencrypt/renewal-hooks/deploy/coturn
+```
 
 ## Configure coturn
 
-`coturn` configuration is stored in the file `/etc/turnserver.conf`. There are a lot of options available, all documented in comments in that file.  We include a sample configuration below with comments indicating the recommended settings, with some notes in locations where customization is required.
+`coturn` configuration is stored in the file `/etc/turnserver.conf`. There are a lot of options available, all documented in comments in the default configuration file.  We include a sample configuration below with the recommended settings (refer to the default configuration file for more information on the settings)..
 
-You can repace the contents `/etc/turnserver.conf` with this file and make two changes:
+Use the file below for `/etc/turnserver.conf` and make the following changes:
 
-* Replace `turn.example.com` with the hostname of your TURN server, and  
-* Replace `<random value>` to a random value for a shared secret (instructions for generating a new secret are in a comment in the file).
+* Replace `<turn.example.com>` with the hostname of your TURN server, and  
+* Replace `<example.com>` with the realm of your TURN server, and  
+* Replace `<secret_value>` to a random value for a shared secret (you can generate one by running `openssl rand -hex 16`)
+* Replace `<IP>` with the external IP of your TURN server
 
-Attention: The `turnserver` process will run as the `turnserver` user, which usually doesn't have access to the certificates/keys in `/etc/letsencrypt/live`. It is recommended that you either create a `ssl-cert` user group, add the `turnserver` user to it and adjust the permissions for `/etc/letsencrypt/live` such that the group can read it or, alternatively, copy the certificates/keys to a safe location (that `turnserver` has access to) after each certificate renewal.
+This configuration file assumes your TURN server is not behind NAT and has a public IP address.
 
 ```ini
-# Example coturn configuration for BigBlueButton
-
-# These are the two network ports used by the TURN server which the client
-# may connect to. We enable the standard unencrypted port 3478 for STUN,
-# as well as port 443 for TURN over TLS, which can bypass firewalls.
 listening-port=3478
 tls-listening-port=443
 
-# If the server has multiple IP addresses, you may wish to limit which
-# addresses coturn is using. Do that by setting this option (it can be
-# specified multiple times). The default is to listen on all addresses.
-# You do not normally need to set this option.
-#listening-ip=172.17.19.101
+listening_ip=$IP
+relay_ip=$IP
 
 # If the server is behind NAT, you need to specify the external IP address.
 # If there is only one external address, specify it like this:
@@ -111,97 +127,96 @@ tls-listening-port=443
 #external-ip=172.17.19.131/10.0.0.11
 #external-ip=172.17.18.132/10.0.0.12
 
-# Fingerprints in TURN messages are required for WebRTC
-fingerprint
+min-port=32769
+max-port=65535
+verbose
 
-# The long-term credential mechanism is required for WebRTC
+fingerprint
 lt-cred-mech
-
-# Configure coturn to use the "TURN REST API" method for validating time-
-# limited credentials. BigBlueButton will generate credentials in this
-# format. Note that the static-auth-secret value specified here must match
-# the configuration in BigBlueButton's turn-stun-servers.xml
-# You can generate a new random value by running the command:
-#   openssl rand -hex 16
 use-auth-secret
-static-auth-secret=<random value>
-
-# If the realm value is unspecified, it defaults to the TURN server hostname.
-# You probably want to configure it to a domain name that you control to
-# improve log output. There is no functional impact.
-realm=example.com
-
-# Configure TLS support.
-# Adjust these paths to match the locations of your certificate files
-cert=/etc/letsencrypt/live/turn.example.com/fullchain.pem
-pkey=/etc/letsencrypt/live/turn.example.com/privkey.pem
-# Limit the allowed ciphers to improve security
-# Based on https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
-cipher-list="ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS"
-
-# Enable longer DH TLS key to improve security
-dh2066
-
-# All WebRTC-compatible web browsers support TLS 1.2 or later, so disable
-# older protocols
+static-auth-secret=<secret_value>
+realm=<example.com>
+
+cert=/etc/turnserver/fullchain.pem
+pkey=/etc/turnserver/privkey.pem
+# From https://ssl-config.mozilla.org/ Intermediate, openssl 1.1.0g, 2020-01
+cipher-list="ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384"
+dh-file=/etc/turnserver/dhp.pem
+
+keep-address-family
+no-cli
 no-tlsv1
 no-tlsv1_1
+```
 
-# Log to a single filename (rather than new log files each startup). You'll
-# want to install a logrotate configuration (see below)
-log-file=/var/log/coturn.log
+We need to create `dph.pem` file,
 
-# To enable single filename logs you need to enable the simple-log flag
-simple-log
+```bash
+$ sudo mkdir -p /etc/turnserver
+$ sudo openssl dhparam -dsaparam  -out /etc/turnserver/dhp.pem 2048
+```
 
-# Lower and upper bounds of the UDP relay endpoints:
-# (default values are 49152 and 65535)
-#
-min-port=32768
-max-port=65535
+To increase the file handle limit for the TURN server and to give it the ability to bind to port 443, add the following systemd override file.  First, create the directory.
+
+```bash
+$ sudo mkdir -p /etc/systemd/system/coturn.service.d
 ```
 
-If the TURN server is used by many users concurrently, it might hit the open file-handles limit. Therefore it is recommended to increase this limit by adding `ulimit -n 49152` in `/etc/init.d/coturn` or editing the systemd service specification using `sudo systemctl edit --full coturn` and then adding `LimitNOFILE=49152`. Once this change is applied, restart the coturn service.
+and then then create `/etc/systemd/system/coturn.service.d/override.conf` with the following contents
+
+```
+[Service]
+LimitNOFILE=1048576
+AmbientCapabilities=CAP_NET_BIND_SERVICE
+ExecStart=
+ExecStart=/usr/bin/turnserver --daemon -c /etc/turnserver.conf --pidfile /run/turnserver/turnserver.pid --no-stdout-log --simple-log --log-file /var/log/turnserver/turnserver.log
+Restart=always
+```
 
 ## Configure Log Rotation
 
 To rotate the logs for `coturn`, install the following configuration file to `/etc/logrotate.d/coturn`
 
 ```
-/var/log/coturn.log
+/var/log/turnserver/*.log
 {
-    rotate 30
-    daily
-    missingok
-    notifempty
-    delaycompress
-    compress
-    postrotate
-    systemctl kill -sHUP coturn.service
-    endscript
+	rotate 7
+	daily
+	missingok
+	notifempty
+	compress
+	postrotate
+		/bin/systemctl kill -s HUP coturn.service
+	endscript
 }
 ```
 
-## Enabling the coturn service
+And create the associated log directory
 
-The ubuntu package for `coturn` requires that you edit a file to enable startup. Edit the file `/etc/default/coturn` and ensure the following line is uncommented:
-
-```ini
-TURNSERVER_ENABLED=1
 ```
+$ sudo mkdir -p /var/log/turnserver
+$ sudo chown turnserver:turnserver /var/log/turnserver
+```
+
+## Restart coturn
 
-You can then start the coturn service by running
+With the above steps completed, restart the TURN server
 
 ```bash
-$ systemctl start coturn
+$ sudo /etc/letsencrypt/renewal-hooks/deploy/coturn    # Initial copy of certificates 
+$ sudo systemctl daemon-reload                         # Ensure the override file is loaded
+$ sudo systemctl restart coturn                        # Restart
 ```
 
-## Configure BigBlueButton to use the coturn server
+Ensure that the `coturn` has binded to port 443 with `netstat -antp | grep 443`.  Also restart your TURN server and ensure that `coturn` is running (and binding to port 443 after restart).
+
+
+# Configure BigBlueButton to use your TURN server
 
 You must configure bbb-web so that it will provide the list of turn servers to the web browser. Edit the file `/usr/share/bbb-web/WEB-INF/classes/spring/turn-stun-servers.xml` using the contents below and make edits:
 
-* replace both instances of `turn.example.com` with the hostname of the TURN server, and 
-* replace `<random value>` with the secret you configured in `turnserver.conf`.
+* replace both instances of `<turn.example.com>` with the hostname of the TURN server, and 
+* replace `<secret_value>` with the secret you configured in `turnserver.conf`.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -211,19 +226,19 @@ You must configure bbb-web so that it will provide the list of turn servers to t
         http://www.springframework.org/schema/beans/spring-beans-2.5.xsd">
 
     <bean id="stun0" class="org.bigbluebutton.web.services.turn.StunServer">
-        <constructor-arg index="0" value="stun:turn.example.com"/>
+        <constructor-arg index="0" value="stun:<turn.example.com>"/>
     </bean>
 
 
     <bean id="turn0" class="org.bigbluebutton.web.services.turn.TurnServer">
-        <constructor-arg index="0" value="<random value>"/>
-        <constructor-arg index="1" value="turns:turn.example.com:443?transport=tcp"/>
+        <constructor-arg index="0" value="<secret_value>"/>
+        <constructor-arg index="1" value="turns:<turn.example.com>:443?transport=tcp"/>
         <constructor-arg index="2" value="86400"/>
     </bean>
 
     <bean id="turn1" class="org.bigbluebutton.web.services.turn.TurnServer">
-        <constructor-arg index="0" value="<random value>"/>
-        <constructor-arg index="1" value="turn:turn.example.com:443?transport=tcp"/>
+        <constructor-arg index="0" value="<secret_value>"/>
+        <constructor-arg index="1" value="turn:<turn.example.com>:443?transport=tcp"/>
         <constructor-arg index="2" value="86400"/>
     </bean>
 
@@ -288,16 +303,16 @@ Filtering test: success
 Nat filtering: Endpoint Independent Filtering
 ```
 
-If you get an error, check that `coturn` is running on the TURN server using `systemctl status coturn.service`.  Check the logs by doing `tail -f /var/log/coturn.log`.  You can get verbose logs by adding `verbose` to `/etc/turnserver.conf` and restarting the TURN server `systemctl restart coturn.service`
+If you get an error, check that `coturn` is running on the TURN server using `systemctl status coturn.service`.  Check the logs by doing `tail -f /var/log/turnserver/coturn.log`.  You can get verbose logs by adding `verbose` to `/etc/turnserver.conf` and restarting the TURN server `systemctl restart coturn.service`
 
 
-You can test your TURN server using the [trickle ICE](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/) page.  This gives you a log of the relay candidates as they are returned from ICE gathering.  To test using this page, you need to generate some test credentials.  Run the following BASH script and substitute `<host>` with the hostname of your TURN server and `<password>` with the password for your TURN server.
+You can test your TURN server using the [trickle ICE](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/) page.  This gives you a log of the relay candidates as they are returned from ICE gathering.  To test using this page, you need to generate some test credentials.  Run the following BASH script and substitute `<turn.example.com>` with the hostname of your TURN server and `<secret_value>` with the password for your TURN server.
 
 ```bash
 #!/bin/bash
 
-HOST=<host>
-SECRET=<password>
+HOST=<turn.example.com>
+SECRET=<secret_value>
 
 time=$(date +%s)
 expiry=8400
@@ -313,6 +328,6 @@ echo
 
 ```
 
-Enter the values into URI, username, and password into the trickle ICE page and click 'Gather candidates'.  You should see a list of relay candidates.  If you don't, again check that your TURN server is running and tail the logs TURN server logs via `tail -f /var/log/coturn.log` or `journalctl -f -u coturn.service`.
+Enter the values into URI, username, and password into the trickle ICE page and click 'Gather candidates'.  You should see a list of relay candidates.  If you don't, again check that your TURN server is running and tail the logs TURN server logs via `tail -f /var/log/turnserver/coturn.log` or `journalctl -f -u coturn.service`.
 
 You can get verbose logs by adding `verbose` to `/etc/turnserver.conf` and then restarting the TURN server `systemctl restart coturn.service`, and try testing again from FireFox or the above Tricke ICE page.