Interactive Connectivity Establishment (ICE)

Overview

WebRTC uses Interactive Connectivity Establishment (ICE) to find a working network path between two peers. Each peer gathers candidate addresses: its local (host) addresses, its public address as seen from the internet, and, if needed, a relay address. The peers then test those candidates in priority order until one succeeds. With trickle ICE, peers don't wait for gathering to finish; they exchange each candidate as it's discovered and begin testing immediately, which shortens connection setup time.

Session Traversal Utilities for NAT (STUN) and Traversal Using Relays around NAT (TURN) make candidate gathering possible. A STUN server reports back the peer's server-reflexive candidate, which is the public address and port that the request arrived from. A TURN server acts as a media relay, lending the peer one of its own addresses as a relay candidate. Because relayed paths cost bandwidth and add a hop, ICE ranks relay candidates lowest and only uses one when nothing more direct works. For best results, we recommend using STUN and TURN together.

ICE candidate gathering is configured per application, either in the ICE Candidate Setup section of the application's WebRTC tab in Wowza Streaming Engine Manager or directly in the application's Application.xml file. This article explains when to use STUN, when to use TURN, and how to configure each.

Trickle ICE

By default, Wowza Streaming Engine sends each candidate to the peer as it's discovered and begins connectivity checks immediately, instead of waiting for gathering to finish. With trickle ICE, host and server-reflexive candidates are already being tested while the relay allocation is still in flight. 

STUN

A STUN server allows Wowza Streaming Engine to discover its own server-reflexive address so peers can connect directly through NAT. Use STUN when:

• You prefer direct connectivity and can accept occasional packet loss
• Your clients are behind NAT devices
• You need to discover server-reflexive candidates

Configure a STUN server

The standard STUN port is 3478, but servers may listen on other ports. To use more than one STUN server, specify the addresses as a comma-separated list.

Publicly available STUN servers include:

• stun.l.google.com:19302 (Google)
• stun1.l.google.com:19302 (Google)
• stun2.l.google.com:19302 (Google)
• stun3.l.google.com:19302 (Google)
• stun4.l.google.com:19302 (Google)
• stun.stunprotocol.org:3478 (StunProtocol)
• stun.ekiga.net:3478 (Ekiga)

Configure a STUN server in WSE Manager

1. Open Wowza Streaming Engine Manager.
2. Navigate to Applications.
3. Select your application.
4. Click the WebRTC tab.
5. Locate the ICE Candidate Setup section.
6. Set the following field:
   • STUN Server: The address of the STUN server, in the format udp://{hostname-or-ip}:{port}. For example, udp://stun.l.google.com:19302.
7. Click Save.
8. Restart the application for the change to take effect.

Configure a STUN server in Application.xml

1. Open [install-dir]/conf/[app-name]/Application.xml.
2. Add the following property to the <Properties> container inside the <WebRTC> container:

   <!-- STUN server configuration -->
   <Property>
       <Name>harvest.stunserver</Name>
       <Value>udp://{hostname-or-ip}:{port}</Value>
       <Type>String</Type>
   </Property>
   

3. Save the file. 
4. Restart the application for the change to take effect.

TURN

A TURN server relays media when a direct path can't be established at all, such as when a client is behind symmetric NAT or a restrictive firewall. Because all media for that connection passes through the relay, TURN consumes bandwidth on the relay host. Use TURN when:

• You need guaranteed connectivity
• Your clients are behind symmetric NAT devices
• Your clients are behind restrictive firewalls
• Peer-to-peer connectivity can't be established by other means

Configure a TURN relay server

A TURN relay server is typically hosted on your own infrastructure or provided by a TURN service vendor. Most production TURN relay servers require authentication, so you'll usually set a username and password alongside the relay address.

Configure a TURN relay server in WSE Manager

1. Open Wowza Streaming Engine Manager.
2. Navigate to Applications.
3. Select your application.
4. Click the WebRTC tab.
5. Locate the ICE Candidate Setup section.
6. Set the following fields:
   • TURN Relay: The address of the TURN server, in the format udp://{hostname-or-ip}:{port}.
   • TURN Username: The username used to authenticate with the TURN server.
   • TURN Password: The corresponding credential. Use a strong, unique value.
7. Click Save. 
8. Restart the application for the changes to take effect.

Configure a TURN relay server in Application.xml

1. Open [install-dir]/conf/[app-name]/Application.xml.

2. Add the following properties to the <Properties> container at the end of the file:

   <!-- TURN relay configuration -->
   <Property>
       <Name>harvest.turnrelay</Name>
       <Value>udp://{hostname-or-ip}:{port}</Value>
       <Type>String</Type>
   </Property>
   
   <!-- TURN authentication -->
   <Property>
       <Name>harvest.turnrelay.username</Name>
       <Value>{username}</Value>
       <Type>String</Type>
   </Property>
   <Property>
       <Name>harvest.turnrelay.password</Name>
       <Value>{password}</Value>
       <Type>String</Type>
   </Property>
   

3. Save the file.
4. Restart the application for the changes to take effect.

ICE restart

An ICE restart re-runs candidate gathering and connectivity checks on an already-established peer connection, without tearing down the session. This recovers a connection when the network path changes underneath it, for example a client moving from Wi-Fi to cellular, a NAT binding expiring, or a route failing mid-session.

During a restart, the engine runs a second (pending) ICE agent alongside the existing one. Media continues to flow over the existing candidate pair until the pending agent reaches connectivity, at which point the connection switches to the new pair. Because a restart re-gathers candidates, a client that moves onto a restrictive network mid-session can only recover if a relay candidate is available to it. Configuring a TURN relay is what makes recovery possible in those cases.

Update ICE restart settings

ICE restart is enabled by default. You can disable it or change the default timeout by updating the app's Application.xml configuration file. ICE restart cannot currently be configured in WSE Manager.

Update ICE restart in Application.xml

Follow the steps below to update the ICE restart settings in your app's configuration file.

1. Open [install-dir]/conf/[app-name]/Application.xml.
2. Add the following properties to the <Properties> container inside the <WebRTC> container:

   <!-- ICE restart configuration -->
   <Property>
       <Name>iceRestartEnabled</Name>
       <Value>true</Value>
       <Type>Boolean</Type>
   </Property>
   <Property>
       <Name>iceRestartTimeoutMs</Name>
       <Value>15000</Value>
       <Type>Long</Type>
   </Property>

3. Save the file.
4. Restart the application for the changes to take effect.