Warning

Kurento is a low-level platform to create WebRTC applications from scratch. You will be responsible of managing STUN/TURN servers, networking, scalability, etc. If you are new to WebRTC, we recommend using OpenVidu instead.

OpenVidu is an easier to use, higher-level, Open Source platform based on Kurento.

Configuration

Table of Contents

• Configuration

  • Debug Logging

  • STUN/TURN Server

  • Network Interface

  • WebRTC Bitrate

  • RTP Ports

  • Advanced Settings

    • ICE-TCP

    • External IP Address

    • Maximum Transmission Unit

    • WebRTC DTLS certificates

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:

• Kurento Client JavaDoc.

• Kurento Client JsDoc.

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.

Debug Logging

KMS uses the environment variable GST_DEBUG to define the debug level of all underlying modules. Check Debug Logging for more information about this and other environment variables.

Set this variable to change the verbosity level of the log messages generated by KMS.

Local install

• Set environment variable GST_DEBUG in /etc/default/kurento-media-server.

Docker

• Pass environment variable GST_DEBUG:

  docker run [...] \
      -e GST_DEBUG="Kurento*:5" \
      kurento/kurento-media-server:6.18.0
  

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

Docker

• Pass environment variable KMS_NETWORK_INTERFACES.

Client API

• Java: setNetworkInterfaces.

• JavaScript: setNetworkInterfaces.

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:

• setMinVideoRecvBandwidth / setMaxVideoRecvBandwidth

• setMinVideoSendBandwidth / setMaxVideoSendBandwidth

• setMinOutputBitrate / setMaxOutputBitrate

  • This setting is also configurable in /etc/kurento/modules/kurento/MediaElement.conf.ini.

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.

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

• Java: setIceTcp.

• JavaScript: setIceTcp.

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

• Java: setExternalIPv4.

• JavaScript: setExternalIPv4.

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

• Java: setMtu.

• JavaScript: setMtu.

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.