Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Use TURN server
To support users which cannot establish peer-to-peer connections due to firewall restrictions or otherwise restricted networks, a TURN server is required to proxy realtime data through a public network.
TURN server configuration
It is recommended to run your own TURN server on a server with a direct Internet connection / public IP. A free and open source TURN server implementation is available at https://github.com/coturn/coturn - all examples below assume that you use coturn. Coturn is available as package for Ubuntu and Debian easily. Make sure you use coturn version 4.5 or later. For example a compatible server with large amount of free traffic can be set up on any of the cheap VPS providers out there for a low monthly/yearly fee. Just make sure the server has low latency for the users you expect to use TURN (means choose the provider location as close as possible to the users).
Example Spreedbox WebRTC coturn configuration:
listening-port=443 #tls-listening-port=443 alt-listening-port=3478 #alt-tls-listening-port=5349 listening-ip=<public-ip-1> #listening-ip=<public-ip-2> relay-ip=<public-ip-1> fingerprint lt-cred-mech use-auth-secret static-auth-secret=<static-auth-secret> realm=spreedbox.local total-quota=100 bps-capacity=0 stale-nonce #cert=/path/to/tls/cert-with-chain.pem #pkey=/path/to/tls/private-key.pem 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
Make sure to enable the service in
/etc/default/coturn and replace the values accordingly in
/etc/turnserver.conf (assuming you installed on Debian/Ubuntu with packaging). For detailed information on these configuration options see Coturn example configuration. It is recommended to have two public IP addresses. If you have only one most cases will work just fine but some might not. The value for
<static-auth-secret> should be long and securely generated and is needed together with the IPs and ports in the next section for Spreed WebRTC configuration. If you choose to enable TLS for TURN then make sure to have a offically trusted certificate and use the correct hostname in TURN URIs.
Warning: A TURN server can potentially generate a lot of traffic as it is essentially an proxy between arbitrary parties only protected by the credentials issued to Spreedbox WebRTC users. Make sure you have traffic warnings in place and use a limit to the overall TURN server bandwidth using the
bps-capacity configuration directive as shown above.
The custom configuration file for Spreed WebRTC on the Spreedbox is found in
/etc/spreed/webrtc.conf. That file is empty by default, so to add a TURN server which is using shared secret authentication run the following command.
cat <<EOF | sudo tee -a /etc/spreed/webrtc.conf [app] turnURIs = turn:<host>:<port>?transport=udp turn:<host>:<port>?transport=tcp turnSecret = <static-auth-secret> stunURIs = EOF
<ip>:<port> with the IP address and port of the TURN server you want to use. For best firewall compatibility, it is recommended that the TURN server supports both TCP and UDP and uses port
443. Currently, browsers can only use IPv4 TURN servers. The above example uses
turn: protocol which means that the TURN server connection is done unencrypted. To use an encrypted connection, use
turns: protocol. Note that
turns: is not supported by all browsers and that the TURN encryption only is used for the TURN protocol - the Spreedbox realtime WebRTC data is always end-to-end encrypted, no matter if
turns:. If the TURN server supports TLS connections then make sure that you use the correct host in the TURN URI as the certificate is validated (example: turns:turn.spreed.me:443?transport=udp) - else the TURN connection will fail.
<static-auth-secret> with whatever secret is configured at the TURN server. Shared secret mode is the only mode for TURN credentials supported by Spreed WebRTC.
TURN servers usually also can provide STUN. Thus, the
stunURIs configuration can be empty if a TURN server is available.
If you have changed
/etc/spreed/webrtc.conf before, make sure that you now do not have multiple
[app] sections and then restart the Spreed WebRTC service to apply the changes.
sudo restart spreed-webrtc
All clients need to reload after the TURN configuration was changed, to retrieve the new configuration and TURN credentials.
Check that TURN is used
How to check if TURN is used depends on the client / browser. In Chromium based browsers WebRTC logs can be viewd at
chrome://webrtc-internals. TURN candidates show up as
relay type. Similarly Firefox shows the WebRTC details at
about:webrtc and TURN candidates as
relayed. The candidates IP address is one of the TURN servers external addresses.
Note that TURN is used as last resort and only when everything else failed.
Notes on security when using TURN
The TURN server knows and can log who is communicating with whom based on the IP address where the TURN connection comes from or wants to connect to.
WebRTC traffic is relayed unmodified after the TURN connection is established - so technically for WebRTC there is no difference with or without TURN. Using TURN does not weaken WebRTC security as WebRTC uses DTLS-SRTP.
On top of that the traffic between the client and the TURN server can be TLS encrypted if setup for
Run TURN server on Spreedbox behind NAT
For testing purposes, the TURN server can also be configured to run on the Spreedbox itself, even if it is located behind a NAT.
While this is not recommended and should not be used for production, it usually is sufficient for testing or running with only a couple of participants - all depending on the network connectivity of the Spreedbox.
Currently there are no official Coturn packages for the Ubuntu 14.04 as shipped with the Spreedbox, but you can install it from an external PPA:
$ sudo apt-get install software-properties-common $ sudo add-apt-repository ppa:fancycode/coturn $ sudo apt-get update $ sudo apt-get install coturn
Next, follow the configuration as described above, but make sure to leave the
relay-ip unconfigured (i.e. commented out). Also
443 as described above is already used for the webservice on the
Spreedbox, so you must select another one (you can keep the default
Please note that the port you configure here must be setup in your firewall to be forwarded to the Spreedbox.
spreed-webrtc as described above and use your external hostname / IP
turnURIs and don't configure the
stunURIs to be empty (you can just
remove the line so the default is used).
spreed-webrtc, you should be able to connect
participants from outside your NAT with people inside.
If it still doesn't work, you might need to configure the setting
/etc/turnserver.conf to your external IP (i.e. outside your NAT) and