Configurable TURN servers

Overview

This feature is available as an add-on feature.

Client SDK: Please note that your App ID is your API key.

You can customize TURN server usage for each client in the session in the following ways:

You can add a list of your own TURN servers that the client will use.
You can decide whether the client should use your TURN servers exclusively or use them in addition to the Vonage TURN servers

Adding your own TURN servers can help users connect in restrictive network environments where Vonage TURN servers might be blocked.

If you chose to override the Vonage TURN servers and only use your own TURN servers, you can make sure that media streams never leave your network.

You can add your own TURN servers for each client connecting to the session, using OpenTok.js (for web clients), the iOS SDK, or the Android SDK. The custom TURN server API was added in version 2.13.0 of these client SDKs.

There is also a IP proxy add-on feature that lets you use your own proxy server to route non-media traffic-such as Video API calls, WebSocket connections, and log traffic.

OpenTok.js (v2.13.0+)

The options parameter of the OT.initSession() method includes an undocumented iceConfig property. This property includes the following properties:

includeServers (String) - Set this to 'custom' and client will use only the custom TURN servers you provide in the customServers array. Set this to 'all' (the default) and the client will use both the custom TURN servers you provide along with Vonage TURN servers.
transportPolicy (String) - Set this to 'all' (the default) and the client will use all ICE transport types (such as host, srflx, and TURN) to establish media connectivity. Set this to 'relay' to force connectivity through TURN always and ignore all other ICE candidates.
customServers (Array) - Set this to an array of objects defining your custom TURN servers. Each object corresponds to one custom TURN server, and it includes the following properties:
- urls (String or Array of Strings) - A string or an array of strings, where each string is a URL supported by the TURN server (and this may be only one URL).
- username (String) - The username for the TURN server defined in this object.
- credential (String) - The credential string for the TURN server defined in this object.

Note: To have the client only use the TURN servers you specify (and not use the Vonage TURN servers): set the includeServers property to 'custom', set the transportPolicy property to 'relay', and set the customServers property to list your TURN servers.

JavaScript Example code

Type definition

Android SDK

The Session.Builder class includes two methods for configuring TURN server usage for the client:

Session.Builder.setCustomIceServers() - Call this method to add a list of custom TURN servers for the client.
Session.Builder.setIceRouting() - Call this method to add limiting the ICE options for the client.

In addition to the two new methods, two new enums define TURN server options:

IncludeServers - Includes options for using only the custom servers or both Vonage servers and the custom servers.
TransportPolicy - Describes the routing method to use.

Note: To have the client only use the TURN servers you specify (and not use the Vonage TURN servers), call the following methods of the Session.Builder object you use to create the Session object:

setCustomIceServers() - Pass in a list of IceServer objects (corresponding to your custom TURN servers) as the serverList parameter, and pass in IncludeServers.TURN as the config parameter.
setIceRouting() - Pass in TransportPolicy.Relay.

See the Java comments below.

Android SDK API additions

Android example code

iOS SDK

When you initialize an OTSession object, set the OTSessionSettings.iceConfig property to define custom TURN server configuration for the client. The OTSessionICEConfig class defines the OTSessionSettings.iceConfig property.

Note: To have the client only use the TURN servers you specify (and not use the Vonage TURN servers), call the [OTSessionSettings addICEServerWithURL:] method of the OTSessionSettings object you use to create the OTSession object. Then set the following properties of the OTSessionSettings object:

includeServers - Set this to OTSessionICEIncludeServersCustom.
transportPolicy - Set this to OTSessionICETransportRelay.

iOS SDK API additions

iOS example code

Windows SDK

Use the IceConfig class to set the custom ICE configuration to be used by the client.

The IceConfig() constructor method includes the following parameters:

customIceServers -- Set this to A list of IceServer objects, representing custom TURN servers to be used by the client. For each IceServer, you set the URL, username, and credential string for the custom TURN server
transportPolicy -- Set this to a value in the ICETransport enum:
- All -- The client will use all ICE candidate types (such as host, srflx, and relay) to establish media connectivity.
- Relayed -- The client will force connectivity through TURN always and ignore all other ICE candidates.
includeServers -- Set this to a value in the IncludeServers enum:
- All -- The client will use Vonage TURN servers in addition to the custom TURN servers you provide.
- Custom -- The client will only use the custom TURN servers you provide.

The Session.Builder class includes an IceConfig property. Set this to an IceConfig object when building the Session object.

Windows SDK API additions

Windows example code

macOS SDK

The type otc_custom_ice_config defines a struct that includes the following members:

num_ice_servers -- The number of ICE servers
ice_url -- An array of strings specifying your ICE server URLs.
ice_user -- An array of strings specifying usernames for the TURN servers.
ice_credential -- An array of strings specifying credential strings for the TURN servers. Call the otc_session_settings_set_custom_ice_config() function and pass in the otc_custom_ice_config instance:

macOS SDK example code

Linux SDK

The type otc_custom_ice_config defines a struct that includes the following members:

num_ice_servers -- The number of ICE servers
ice_url -- An array of strings specifying your ICE server URLs.
ice_user -- An array of strings specifying usernames for the TURN servers.
ice_credential -- An array of strings specifying credential strings for the TURN servers.

Call the otc_session_settings_set_custom_ice_config() function and pass in the otc_custom_ice_config instance:

Linux SDK example code

Known issue

If you set a client to always use TURN servers in a relayed session, it will not be able to subscribe to its own streams (streams it publishes).

FAQs

Does the configurable TURN API address the issue for HTTP traffic?

No. Configurable TURN allays customers’ concerns around connecting to trusted end-points for media traffic only.

For HTTP traffic, customers will have to do one of the following:

Whitelist vonage and opentok domain names:
- *.opentok.com
- *.tokbox.com
- *.vonage.com
Whitelist IP address blocks provided for the Vonage Video API.
Use web proxy settings on the clients to proxy all Vonage HTTPS traffic through your own targets. See the Proxy requirements section here.

How is the media path being selected between the available TURN targets. Does it take into account the round-trip latency, or is it influenced by the order in which we list the targets, or is it random?

Order of TURN servers is not guaranteed based on the list provided. Instead, when the media starts flowing, the ICE implementation selects which candidate/server has the best connectivity and successfully negotiated first.

If the TURN server URL maps to multiple IP addresses, how is the specific TURN server selected for the session? Is this random?

Most implementations, including the ones used in Chrome and Firefox, take the first IP returned by the DNS lookup. This results in a random round-robin selection typically.

If both TCP and UDP TURN servers are provided and are reachable, is it possible to prioritize UDP targets and only fall back to TCP if required?

UDP relay candidates will be preferred over TCP relay candidates since those candidates have a lower local type preference and therefore a lower priority. Refer to RFC 8445 for details for details. The order of ICE servers passed in does not influence this.

Can a single client use different media paths for different streams?

Yes, this is expected behavior as Vonage treats each individual media stream separately.

How much control does the Configurable TURN API have in the media path selection?

Media path selection is handled by ICE (Interactive Connectivity Establishment) inside WebRTC and we have no way to modify this behavior. The Configurable TURN API only helps modify the list of ICE servers provided by the client to WebRTC and does not influence the selection process.

Is direct connection to Vonage Media Server over UDP always preferred?

Yes, direct connection to Vonage Media Server is always preferred. It fails over to using TURN if connection to the Vonage Media Server is unsuccessful or if the "Force TURN" option is used in the Configurable TURN API.

Can I use multiple TURN servers of the same type for load balancing?

This is not recommended as it will result in a random server being picked by the client and that server can change over the duration of the connection.

How do I load-balance my custom TURN server deployment?

Please contact us for more information.

Can the TURN server decrypt media?

No, the TURN server does not have access to the SRTP keys that are exchanged using DTLS-SRTP and only available to the endpoints of the connection.

What happens if a TURN server crashes during a session and how to recover

If a TURN server crashes while it is being used this will result in the client's connection becoming disconnected. The client will try to re-establish a connection using an ICE Restart.

How can I test a TURN server?

You can test your TURN server either using Trickle Ice test page or coturn turnutils_uclient.

Navigation