This is the site logo "Carlinvi"

Turn/Coturn Server Installation

Kurento Media Server, just like any WebRTC endpoint, will work fine on its own, for LAN connections or for servers which have a public IP address assigned to them. However, sooner or later you will want to make your application work in a cloud environment with NAT firewalls, and allow KMS to connect with remote clients. At the same time, remote clients will probably want to connect from behind their own NAT router too, so your application needs to be prepared to perform NAT Traversal in both sides. This can be done by setting up a STUN server or a TURN relay, and configuring it in both KMS and the client browser.

How to install Coturn

Coturn is a STUN server and TURN relay, supporting all features required for the ICE protocol and allowing to establish WebRTC connections from behind a NAT.

Coturn can be installed directly from the Ubuntu package repositories:

sudo apt-get update ; sudo apt-get install --no-install-recommends coturn

To configure it for WebRTC, follow these steps:

  1. Edit /etc/turnserver.conf.
# The external IP address of this server, if Coturn is behind a NAT.
# It must be an IP address, not a domain name.
#external-ip=<CoturnIp>

# STUN listener port for UDP and TCP.
# Default: 3478.
#listening-port=3478

# TURN lower and upper bounds of the UDP relay ports.
# Default: 49152, 65535.
#min-port=49152
#max-port=65535

# Uncomment to enable moderately verbose logs.
# Default: verbose mode OFF.
#verbose

# TURN fingerprints in messages.
fingerprint

# TURN long-term credential mechanism.
lt-cred-mech

# TURN static user account for long-term credential mechanism.
user=<TurnUser>:<TurnPassword>

# TURN realm used for the long-term credential mechanism.
realm=kurento.org

# Set the log file name.
# The log file can be reset sending a SIGHUP signal to the turnserver process.
log-file=/var/log/turn.log

# Disable log file rollover and use log file name as-is.
simple-log
  • The external-ip is necessary in cloud providers that use internal NATs, such as AWS (Amazon EC2). Uncomment this line and write the machine’s public IP address in the field <CoturnIp>. It must be an IP address, not a domain name.
  • Comment out (or delete) all the TURN parameters if you only want Coturn acting as a STUN server.
  • Create the destination log file, otherwise Coturn will not have permissions to create the file by itself:
sudo install -o turnserver -g turnserver -m 644 /dev/null  var/log/turn.log
  1. Edit the file /etc/default/coturn and uncomment or add this line:
TURNSERVER_ENABLED=1
  1. Start the Coturn system service:
sudo service coturn restart
  1. The following ports should be open in your firewall / NAT / cloud provider’s Security Group:
  • listening-port (default: 3478) UDP & TCP. You can skip opening one of the protocols if you disable either UDP or TCP in Coturn (for example, with no-tcp).
  • All the range from min-port to max-port (default: 49152 to 65535). As per RFC 8656, this is the port range that Coturn will use by default for TURN relay. Again, you can disable either of TCP or UDP (for example, with no-tcp-relay).

Note:

Port ranges do NOT need to match between Coturn and Kurento Media Server.

If you happen to deploy both Coturn and KMS in the same machine, we recommend that their port ranges do not overlap.

  1. Provide your STUN or TURN server settings to both Kurento Media Server and all WebRTC clients (like web browsers). Check STUN/TURN Server Configuration for ways to configure this in Kurento.
  1. Check that your Coturn server is working. For that, follow the steps given in the next section.

How to test my STUN/TURN server

To test if your STUN/TURN server is functioning properly, open the Trickle ICE test page. In that page, follow these steps:

  1. Remove any server that might be filled in already by default.
  2. Fill in your STUN/TURN server details.
  • To only test STUN (TURN relay will not be tested):
stun:<StunServerIp>:<StunServerPort>
  • To test both STUN and TURN:
turn:<TurnServerIp>:<TurnServerPort>

… and also fill in the TURN username and TURN password.

  1. Click on Add Server. You should have only one entry in the list, with your server details.
  1. Click on Gather candidates. Verify that you get candidates of type srflx if you are testing STUN. Likewise, you should get candidates of type srflx and type relay if you are testing TURN.If you are missing any of the expected candidate types, your STUN/TURN server is not working well and WebRTC will fail. Check your server configuration, and your cloud provider’s network settings.

How to configure Kurento Media Server

Most (but not all, see below) of the settings in Kurento can be set statically in configuration files:

  • /etc/kurento/kurento.conf.json

The main configuration file. Provides settings for the behavior of Kurento Media Server itself.

  • /etc/kurento/modules/kurento/MediaElement.conf.ini

Generic parameters for all kinds of MediaElement.

  • /etc/kurento/modules/kurento/SdpEndpoint.conf.ini

Audio/video parameters for SdpEndpoints (i.e. WebRtcEndpoint and RtpEndpoint).

  • /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini

Specific parameters for WebRtcEndpoint.

  • /etc/kurento/modules/kurento/HttpEndpoint.conf.ini

Specific parameters for HttpEndpoint.

  • /etc/default/kurento-media-server

This file is loaded by the system’s service init files. Defines some environment variables, which have an effect on features such as the Debug Logging, or the Core Dump files that are generated when a crash happens.

For other settings not directly available in configuration files, make sure to read the Client API SDK docs, where all exposed methods are documented:

The Kurento Docker images also accept some environment variables that map directly to settings in the above files. If this is not flexible enough, you can always use a bind-mount or volume with a different set of configuration files in /etc/kurento. For some tips about these techniques, go to Kurento in Docker.

STUN/TURN Server

Read When are STUN and TURN needed? to learn about when you might need to use these, and STUN/TURN server install for guidance on how to install your own STUN/TURN server.

Local install

  • Set values stunServerAddress and stunServerPort to use a STUN server, or set turnURL to use a TURN server; in /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini.

Docker

  • Pass environment variables KMS_STUN_IP  and KMS_STUN_PORT for STUN, or KMS_TURN_URL for TURN.

Client API

  • Java: setStunServerAddress and setStunServerPort for STUN, or setTurnUrl for TURN.
  • JavaScript: setStunServerAddress and setStunServerPort for STUN, or setTurnUrl for TURN.
Network Interface

To specify the network interface name(s) that KMS should use to communicate from the environment where it is running (either a physical machine, a virtual machine, a Docker container, etc.)

Local install

  • Set value networkInterfaces in /etc/kurento/modules/kurento/WebRtcEndpoint.conf.in.

Docker

  • Pass environment variable KMS_NETWORK_INTERFACES

Client API

RTP Ports

These two parameters define the minimum and maximum ports that Kurento Media Server will bind to (listen) in order to receive remote RTP packets. This affects the operation of both RtpEndpoint and WebRtcEndpoint.

Plain RTP (RtpEndpoint) needs 2 ports for each media kind: an even port is used for RTP, and the next odd port is used for RTCP. WebRTC (WebRtcEndpoint) uses RTCP Multiplexing (rtcp-mux) when possible, so it only uses 1 port for each media kind.

Local install

  • Set values minPort, maxPort in /etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini.

Docker

  • Pass environment variables KMS_MIN_PORT, KMS_MAX_PORT.
WebRTC Bitrate

The default MaxVideoSendBandwidth range of the WebRtcEndpoint is a VERY conservative one, and leads to a low maximum video quality. Most applications will probably want to increase this to higher values such as 2000 kbps (2 mbps): Java, JavaScript.

There are several ways to override the default settings for variable bitrate and network bandwidth estimation:

Advanced Settings

These settings are only provided for advanced users who know what they are doing and why they need them. For most cases, the default values are good enough for most users.

ICE-TCP

ICE-TCP is what allows WebRTC endpoints to exchange ICE candidates that use the TCP protocol; in other words, the feature of using TCP instead of UDP for WebRTC communications.

If you have a well known scenario and you are 100% sure that UDP will work, then disabling TCP provides slightly faster times when establishing WebRTC sessions. I.e., with ICE-TCP disabled, the time between joining a call and actually seeing the video will be shorter.

Of course, if you cannot guarantee that UDP will work in your network, then you should leave this setting enabled, which is the default. Otherwise, UDP might fail and there would be no TCP fallback for WebRTC to work.

Local install

  • Set value iceTcp to 1 (ON) or 0 (OFF) in /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini.

Docker

  • Set environment variable KMS_ICE_TCP to 1 (ON) or 0 (OFF).

Client API

External IP Address

When this feature is used, all of the Kurento IPv4 and/or IPv6 ICE candidates are mangled to contain the given address. This can speed up WebRTC connection establishment in scenarios where the external or public IP is already well known, also having the benefit that STUN won’t be needed for the media server.

Local install

  • Set values externalIPv4, externalIPv6 in /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini.

Docker

  • Pass environment variables KMS_EXTERNAL_IPV4, KMS_EXTERNAL_IPV6.
  • If the special value auto is used, then the container will auto-discover its own public IP address by performing a DNS query to some of the well established providers (OpenDNS, Google, Cloudflare). You can review the script here: getmyip.sh. In cases where these services are not reachable, the external IP parameters are left unset.

Client API

Maximum Transmission Unit

The MTU is a hard limit on the size that outbound packets will have. For some users it is important being able to lower the packet size in order to prevent fragmentation.

For the vast majority of use cases it is better to use the default MTU value of 1200 Bytes, which is also the default value in most popular implementations of WebRTC (see Browser MTU).

Local install

  • Set value mtu in /etc/kurento/modules/kurento/BaseRtpEndpoint.conf.ini.

Docker

  • Pass environment variable KMS_MTU.

Client API

WebRTC DTLS certificates

By default, Kurento uses a different self-signed certificate for every WebRtcEndpoint (see Media Plane security (DTLS)). If you want or need to use the same cert for every endpoint, first join both your certificate (chain) file(s) and the private key with a command such as this one:

# Make a single file to be used with Kurento Media Server.
cat cert.pem key.pem >cert+key.pem

Then, configure the path to cert+key.pem:

Local install

  • Set either of pemCertificateRSA or pemCertificateECDSA with the path to your certificate file in /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini.

Docker

  • Pass environment variables KMS_PEM_CERTIFICATE_RSA or KMS_PEM_CERTIFICATE_ECDSA with the path inside the container. Also, make sure the file is actually found in that path; normally you would do that with a bind-mount, a Docker volume, or a custom Docker image. For more information and examples, check Kurento in Docker.