Skip to content

Run a TURN server on the Spreedbox

Jump to bottom
Joachim Bauch edited this page Nov 4, 2016 · 1 revision

This document is a step-by-step description of the necessary actions that must be performed in order to install a TURN server on a Spreedbox.

Prerequisites

The following information will be needed later during the setup:

  1. The external hostname of the Spreedbox.
  2. The external IP address of the Spreedbox (this is optional and might not be required in all scenarios).
  3. A TCP and UDP port (3478 by default) must be open in the firewall and forwarded to the Spreedbox (to the same port). This port will be used by clients to allocate TURN sessions.
  4. The TCP and UDP port range 49152 - 65535 must be open in the firewall and forwarded to the Spreedbox (to the same ports). Ports in this range will be used for the previously allocated TURN sessions.
  5. Only one of TCP or UDP may be used, but for maximum compatibility, both should be configured.

Connect to the Spreedbox

Installing a TURN server on the Spreedbox is an advanced setup and not supported through any configuration UI, so all actions must be performed as root through the commandline on the Spreedbox through SSH. That means you will need an SSH client like ssh on Linux or Putty on Windows.

Connecting as root is disabled by default, the default username is spreedbox with password spreedbox, which can then switch to root using sudo:

$ ssh spreedbox@name-or-ip-of-my-spreedbox
$ sudo su

Install TURN server software coturn

Currently there are no official Coturn packages for the Ubuntu 14.04 as shipped with the Spreedbox, so it must be installed from an external PPA:

$ apt-get install software-properties-common
$ add-apt-repository ppa:fancycode/coturn
$ apt-get update
$ apt-get install coturn

Enable the TURN service

The TURN service is not started automatically after installation but must be enabled and configured first. That way it will also restart after a reboot.

Open the file /etc/default/coturn and uncomment the line TURNSERVER_ENABLED (i.e. remove the leading #) to read

TURNSERVER_ENABLED=1

Configure the TURN service

To prevent unauthorized access to the TURN service, a shared secret is used by the TURN and the spreed-webrtc services. Best would be to generate a random key:

$ libressl-openssl rand -hex 32
random-secret-used-for-the-documentation-only

Next, the TURN service must be configured to support the allocation requests from WebRTC clients. You will need the port from step 3 of the prerequisites.

Open the file /etc/turnserver.conf and add / edit the following entries (most already exist but are commented out):

listening-port=the-port-from-step-3
fingerprint
lt-cred-mech
use-auth-secret
static-auth-secret=the-shared-secret-from-above
realm=Spreedbox
total-quota=100
bps-capacity=0
stale-nonce
cipher-list="ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AES:RSA+3DES:!ADH:!AECDH:!MD5"
no-loopback-peers
no-multicast-peers

With the port 3478 and the secret from above it would be

listening-port=3478
fingerprint
lt-cred-mech
use-auth-secret
static-auth-secret=random-secret-used-for-the-documentation-only
realm=Spreedbox
total-quota=100
bps-capacity=0
stale-nonce
cipher-list="ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AES:RSA+3DES:!ADH:!AECDH:!MD5"
no-loopback-peers
no-multicast-peers

Restart the TURN server service afterwards:

$ service coturn restart

This will output various information about the used addresses. The service logs to /var/log/turn_*.log, if clients allocate sessions it will be logged there.

There are some cases depending on network / firewall setup, where the actual external IP address of the Spreedbox must be configured in the TURN server for client connections to succeed. You will need the external IP address from step 2 of the prerequisites.

Open the file /etc/turnserver.conf and add / edit the following entry (might already exists but is commented out):

external-ip=the-external-ip-from-step-2

Restart the TURN server service afterwards:

$ service coturn restart

Configure spreed-webrtc

Now that the TURN service is running, it must be configured in spreed-webrtc so it can be used by web clients. You will need the external hostname of the Spreedbox from step 1 and the port from step 3 of the prerequisites.

Open the file /etc/spreed/webrtc.conf and add the following entries:

[app]
turnURIs = turn:hostname:port?transport=udp turn:hostname:port?transport=tcp
turnSecret = the-shared-secret-from-above

So for the hostname spreedbox.domain.invalid and port 3478 with the secret from above it would be

[app]
turnURIs = turn:spreedbox.domain.invalid:3478?transport=udp turn:spreedbox.domain.invalid:3478?transport=tcp
turnSecret = random-secret-used-for-the-documentation-only

If either TCP or UDP is not available, the corresponding entry should be omitted from the turnURIs configuration.

Restart the spreed-webrtc service afterwards:

$ service spreed-webrtc restart

Any already connected web clients will ask to / automatically reconnect and get the TURN configuration from the service.

Clone this wiki locally