Configuring the TURN Server

Basic Configuration

IceLink includes a STUN/TURN server API that lets you run your own server in your own environment. We recommend using our .NET example from the SDK as a starting point. Examples are also available for Java and macOS (Objective-C), but are not as robust.

The server supports STUN (over UDP), TURN (over UDP and TCP), and TURNS (over TCP/TLS). When starting the server, you can choose which ports to listen to for UDP traffic, TCP traffic, and TLS traffic. We recommend:

  • UDP: port 80 and port 3478
  • TCP: port 80 and port 3478
  • TLS: port 443 and port 5349 (requires a valid TLS certificate)

In the .NET example, this is configurable by simply editing app.config.

<configuration>
  <appSettings>
    ...
    <add key="UdpPorts" value="80,3478" />
    <add key="TcpPorts" value="80,3478" />
    <add key="TlsPorts" value="443,5349" />
    ...
  </appSettings>
</configuration>

Setting the Public IP or External STUN Server

Unless your server's network interface card is bound to a public IP address, you will need to set either the PublicIPAddress or ExternalStunServer properties in app.config. If you know the public IP address ahead of time, or don't want to rely on an external STUN server, simply enter the public IP address. If you want simpler deployments and better support for auto-scaling, you can use an external STUN server to auto-discover the server's public IP address at startup.

<configuration>
  <appSettings>
    ...
    <add key="ExternalStunServer" value="stun.l.google.com:19302" />
    <add key="PublicIPAddress" value="" />
    ...
  </appSettings>
</configuration>

Configuring Secure TURN (TURNS)

TURNS provides an additional layer of security around the transport by sending all data over a secure TCP socket. This allows traversal over highly secure networks where only TLS-encrypted traffic is allowed in/out, typically on port 443. For a more in-depth look at the security of TURNS, see the TURN Traffic Concerns and Secure TURN (TURNS) section in Security.

Before configuring TURNS, you will need a TLS certificate. If you don't have one, you can obtain one from any number of vendors online. Once you have your TLS certificate, there are only two steps:

  1. Installing the TLS certificate into your keystore.
  2. Configuring the TURN server to use the installed TLS certificate.

Installing the TLS Certificate

  1. Right click on your TLS certificate (.pfx format) and select Install PFX. You'll see the Certificate Import Wizard pictured above.
  2. Choose Local Machine and click Next.

  3. Leave the selected file and click Next.

  4. Enter the password for the private key and accept other default settings then click Next.

  5. Accept default setting and click Next.

  6. Click Finish.

That's it! Your TLS certificate has been successfully installed. Next you will configure the TURN server to use it.

Configuring the TURN Server

  1. Open the Windows certificate manager (certmgr) and browse to Personal > Certificates. You should see your newly installed certificate listed.
  2. Double-click on your certificate record and select the Details tab.
  3. Find the Thumbprint field and copy the value.
  4. Paste this value into the TlsCertificateHash property in app.config, e.g.:
<configuration>
  <appSettings>
    ...
    <add key="TlsPorts" value="443,5349" />
    <add key="TlsCertificateHash" value="12dbdd75dfgdf686868687481cf7f6b026c" /> 
    ...
  </appSettings>
</configuration>


Some versions of Windows will add extra spaces that need to be removed, as well as a null character at the beginning of the string. This null character is not visible, so to remove it, place your cursor between the first two visible characters (1 and 2 in the above example), press the left arrow, and then press backspace. If a null character was present, there will be no visible change.

That's it! After restarting your server, you should see a message indicating that the server is now listening on the requested TLS ports.

Testing the Server

The easiest way to test is to browse to https://test.icelink.fm/turn.htm from Chrome or Firefox, update the STUN/TURN URIs and/or credentials, and click Test. You can add or remove URIs to test individual components/ports. For example, to verify that TURNS is working properly, remove the STUN and TURN URIs and leave just a single TURNS URI to test. Whatever you test with here is generally what should go into your client applications.

TURNS will validate the TLS certificate installed on your server to ensure that it matches the hostname. For this reason, TURNS requires a hostname and will generally not work with an IP address.

In addition to testing manually, the SDK includes a test class IceServerTest that allows you to run tests programatically and check the results. This is encouraged at application startup or immediately before starting a call or joining a conference, as server outages will directly impact connectivity.