State of knowledge

July 2022

Introduction

Direct audio/video communication has become an important part of modern collaboration.

In order to be able to implement this efficiently from a technical point of view while at the same time keeping internal networks secure, framework conditions must be observed that at first glance make it difficult to establish direct communication across network boundaries.

A NAT router is often used in private IPv4 networks to increase security, making it difficult or impossible for an external computer to contact an internal client without being requested to do so.

Unfortunately, this also blocks the connections necessary for efficient audio/video communication.

In order to still be able to establish these and similar connections, techniques have been developed that allow audio/video communication to take place without any reduction in security. These techniques include STUN and TURN.

This documentation describes how to commission a STUN (RFC5398)/TURN (RFC5766) server on the internet that is interoperable with estos products.

The basis for this is the well-known TURN server "coTurn": https://github.com/coturn/coturn

We have compiled the requirements and the options for checking here for the simplest possible commissioning.

The procedure described here requires detailed IT expertise in configuration and administration.

Requirements

The requirements are oriented towards the simplest possible setup and maintenance. You can also commission this STUN/TURN server with other requirements.

Computer

  • Linux machine with Docker installed and hosted directly on the internet (not on the company LAN/DMZ).

    • Min. 2 vCPU, 4GB RAM and 20GB Disk

    • Public IP address assigned directly to the machine or a 1:1 NAT with public IP address.

Ports

  • Ports published in the firewall/NAT or forwarded to the machine.

    • 3478/TCP (may vary depending on settings during installation)

    • 3478/UDP (may vary depending on settings during installation)

    • 49152-65535/UDP 

    • behind NAT: 1:1 portmapping

      • For this "external" IP, the NAT must forward the ports directly (the forwarded port 54321 must always be mapped to the same "external" port 54321)

Network performance

  • Please ensure that the network of the hosted machine provides the following:

    • High PPS (packet-per-second performance)

    • Low network jitter (<= 30ms)

    • Low latency (<= 150ms)

Bandwidth

  • Bandwidth: Other network requirements: 

    • for audio calls (AudioChat or softphone calls) via the TURN server:

      • Opus Codec, „Fullband Speech“ at (useful) bit rates between 28 – 40 Kbit/s, pTime 20ms

      • Total typical 45 Kbit/s per direction, total 90 Kbit/s

    • For video calls via the TURN server:

      • Video Codec VP8 with 640x480, 30 f/s, Audio Codec Opus, 50 f/s.

      • 300kbit/s to 2.3 MBit/s per direction

      • Total 600 Kbit/s up to 4.6 MBit/s max.

        Bandwidth

        When calculating the required bandwidth, only calls that are actually forwarded via the TURN server must be taken into account.

Examples of known hosting services

When selecting the service provider for hosting Linux machines, the above-mentioned requirements should be taken into account. Since the network line in particular has a decisive influence on the behavior of the TURN component in terms of forwarding (relaying) the media streams, it is important to investigate whether the provider has special features for this. Furthermore, you should also pay attention to the costs incurred by the consumption of bandwidth.

AWS Amazon Web Services

If you deploy the TURN server in an AWS instance, for example, Enhanced Networking is available only on instances launched with HVM AMIs. Preferably, use C3/C4/R3 instances. For details about AWS EC2 instance types, click here.

Microsoft Azure

The Accelerated Networking feature can be used to improve the network performance in Microsoft Azure environments. Please refer to the notes in the documentation: https://docs.microsoft.com/en-us/azure/virtual-network/create-vm-accelerated-networking-powershell

You should search for similar keywords when choosing a provider.

Start-up

As a basis, a Linux machine is available directly on the internet (public IP address) and Docker is installed on it.

Please familiarize yourself in advance with the common commands of your Linux and Docker installation. An overview of Docker can be found here: https://docs.docker.com/engine/install/

Quick start Docker installation

curl -sSL https://get.docker.com | sudo bash -
BASH

Privileges

Normally, Docker commands must always be executed with "root" or "sudo" privileges. For details, see the Docker installation guide appropriate for your Linux distribution.

For example for Ubuntuhttps://docs.docker.com/engine/install/ubuntu/
"You need to use sudo to run Docker commands"

coTurn with a Docker image from estos (quick start without options).

This command is used to work with the default values (see the table below):

sudo docker run -d --name stunturn --network host --restart always estos/stunturn
BASH

Optional: coTurn with a Docker image from estos (with all options)

If you do not want to use the default values, adjust the following command to your needs:

sudo docker run -d --name stunturn --network host --restart always \
-e EXTERNAL_IP_ADDRESS=YourExternalIPAddress \
-e LISTENING_IP_ADDRESS=YourLocalIPAddress \
-e TURN_PORT=3478 \
-e TURN_USERNAME=YourTurnUsername \
-e TURN_PASSWORD=YourTurnPassword \
-e LOG_LEVEL=moderate \
estos/stunturn
BASH
ParameterRequiredDefault valueDescription
LISTENING_IP_ADDRESSnoall local network interfacesLocal IP network interface. If not set, all local network interfaces are monitored.
EXTERNAL_IP_ADDDRESSnoautomatically recognizedPublic IP address that STUN/TURN will use as a relay address.
Useful in scenarios with NAT. Automatically detected if not set.
TURN_PORTno3478TCP port (for TURN) and UDP port (for STUN) that the STUN/TURN server responds to.
TURN_USERNAMEnostunturnUsername for TURN authentication
TURN_PASSWORDnorandom passwordPassword for TURN authentication
LOG_LEVELnonormalAllowed values: 'normal', 'moderate', 'debug'

Checking the condition of the containers

sudo docker container list
CODE

Checking the logs for the configuration of the UCServer

sudo docker logs stunturn
CODE

Ergebnis

No TURN_PORT env variable set. Default 3478 UDP and TCP will be used
No TURN_USERNAME env variable set, user will be set to 'stunturn' and password will be randomly generated
Created TURN user 'stunturn' with password 'RLYmta9lTFQM0ClqECWq'. Please use said credentials into your estos application
Executing TURN service... 
Your STUN and TURN server is now running
Please configure your estos UCServer own STUN and TURN servers according to the following template: 
STUN Server --> stun:1.123.456.254:3478
TURN Server --> turn:1.123.456.254:3478
TURN username: stunturn
TURN password: RLYmta9lTFQM0ClqECWq
CODE

Configuration in the UCServer administration

STUN/TURN – use custom servers – configure server

In the UCServer administration, configure the created STUN/TURN server in the item "STUN/TURN" → "Use custom servers" → "Configure server..."

In the item "Checking the logs", a log output was displayed after starting the Docker container. This also contains the data necessary for configuration:

Example screenshot: UCServer Administration – Configure custom servers – Specify URI for STUN/TURN

Confirm the data with OK and Apply.

Diagnosis/Test

Then run a test via the "Run Diagnostics" button.

Test OK

If both tests are successful with "OK", the UCServer can use the STUN/TURN server.

Please note that this test was performed from the "point of view" of the UCServer and therefore also from the "point of view" of the Kurento Media Server shipped locally with it.
If you use other clients, such as a mobile app in the LTE network or a ProCall client for Windows at home, then a successful test on the UCServer does not mean that the ProCall client at home has also been tested successfully. In this case, a test should be performed locally, e.g. with https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

Test failed

If the executed test failed in UCServer administration, then you can view details about the test and the result using the "Open log file" button.

These provide clues as to where to look for the error.

Verification of possible sources of error
  • Authentication → Verify the created username and password.
  • Timeout → Check the entire network path between UCServer and the coTurn server running in the Docker container.
    Can the UCServer reach the Linux machine on the internet at all?
    Are the required ports released outbound from the UCServer and released and/or forwarded inbound to the Linux machine, etc.?
  • Topology error → Is the Linux machine really connected to the internet and not to the LAN of the UCServer installation?
    Is an incorrect public IP address set up?

Logs for diagnostics of the STUN/TURN server

Logs

The logs are stored in a local file inside the container in the following name format: /var/tmp/stunturn_DD_MM_YYYY.log

To list all logs, execute:

sudo docker exec stunturn ls /var/tmp/
CODE

To output a specific log (e.g. from 26/4/2022):

sudo docker exec stunturn cat /var/tmp/stunturn_26_04_2022.log

Version history

Dateestos stunturn tagoriginal docker imagecoturnlatest
8/3/20224.5.2-r84.5.2-r84.5.2
21/7/20224.5.2-r134.5.2-r134.5.2(tick)

Update to current version

A direct update is not possible. You have to delete the running container and the local image and then start it up again with the new image. If you used individual parameters to start the container, you must use them again.

The following steps must be performed to install the latest version:

  • Check the currently installed version to see if an update is available at all

    sudo docker inspect stunturn | grep image.version
    CODE
  • Delete currently running container

    sudo docker container rm -f stunturn
    CODE
  • Delete local image of the old version

    sudo docker image rm estos/stunturn:latest
    CODE
  • Download current image and run it as a container (note individual settings above under "Startup")

    sudo docker run -d --name stunturn --network host --restart always estos/stunturn
    CODE
  • Check version number

    sudo docker inspect stunturn | grep image.version
    CODE

More useful Docker commands

Display running containers

sudo docker container list
CODE

Stop container stunturn and then delete

sudo docker container stop stunturn
sudo docker rm stunturn
CODE

Further information on the ICE, STUN, TURN mode of operation

If you are interested in further information regarding STUN/TURN or if you are looking for more details about further functions of coTurn, you will find some hints here: