<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/en/2176/25/9/_/styles/combined.css?spaceKey=AST&forWysiwyg=true" type="text/css">
</head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
<h2><a href="https://wiki.asterisk.org/wiki/display/AST/Interactive+Connectivity+Establishment+%28ICE%29+in+Asterisk">Interactive Connectivity Establishment (ICE) in Asterisk</a></h2>
<h4>Page <b>added</b> by <a href="https://wiki.asterisk.org/wiki/display/~beagles">Brent Eagles</a>
</h4>
<br/>
<div class="notificationGreySide">
<h1><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-Overview"></a>Overview </h1>
<p>If an Asterisk server (or any VoIP server for that matter) is directly accessible on the Internet and and is being "called" by the average SIP softphone or appliance, chances are that turning "on" a check box or maybe some STUN server configuration is all that is needed to make everything "just work". Likewise, configuration is straightforward when servers and phones are on the same local network. If host A and host B are both behind <em>network address translation</em> (NAT) firewalls and they need to be able to connect and transmit and receive live data, things can become more difficult. If the networks are very basic, relatively static and the NAT sufficiently configurable, it may be possible to successfully configure a solution (DMZ's, port forwarding, etc). However, add a little additional complexity and things quickly become difficult. Common examples are: layers of NATs between A and B, dynamic address allocation, highly restrictive firewalls, shifting network configurations. Even if configuration is possible, it is burdensome to maintain and can be prohibitively costly in time and resources. The problem is common and severe enough that the VoIP community has been working on solutions for some time. The <em>Interactive Connectivity Establishment</em> protocol, or ICE, is a relatively recent and promising approach to resolving these kinds of problems. </p>
<p>Support for ICE was added to Asterisk in version 11. ICE is a standardized mechanism for establishing communication suitable for live media streams between software agents running behind NAT firewalls. Establishing connections through NATs is referred to as <em>traversing</em> the NAT. To achieve this, the ICE protocol defines: </p>
<ul>
<li>a series of tests for determining internally and externally accessible IP addresses;</li>
<li>a standard form for specifying a set of prioritized candidate IP addresses in SDP that can be used to reach a software agent in an <em>offer</em>;</li>
<li>a series of operations for validating potential candidates and matching with local candidates to the offered candidates, resulting in candidate pairs;</li>
<li>a standard form for providing an <em>answer</em> specifying validated candidates; and</li>
<li>a series of rules for picking which candidate pair to ultimately use.</li>
</ul>
<p>There are mechanisms other than ICE that can be used to communicate through NAT firewalls. They generally require specialized end-to-end configuration or fragile assumptions that may not always be valid. With some basic general configuration (i.e. the hostname of a STUN or TURN server), ICE takes a logical approach to an optimal connection. Configured with available TURN server(s), ICE will even find a successful connection "through" symmetric NATs. In short, if all the software agents are properly configured, ICE will <em>find a way if there is a way</em>. It is worthwhile noting that while ICE is intended for RTP, there are other standard mechanisms for SIP messaging through firewalls. </p>
<p>There is a lot to ICE that is beyond the scope of this document. For in-depth detail, see the links to the relevant <a href="#InteractiveConnectivityEstablishment%28ICE%29inAsterisk-rfcs">RFCs</a> below. While the RFCs contain a lot of information, it is mostly oriented at implementation of the ICE protocol and is not necessary for using Asterisk's ICE support. At a user level ICE uses SDP offer/answer, so the general concepts are fairly easy to follow for those familiar with SIP. Also, the details of visually interpreting candidate lists are fairly straightforward and are as easily digestible as media format SDP after a small amount of practice. </p>
<h1><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-ConfiguringICESupportinAsterisk"></a>Configuring ICE Support in Asterisk </h1>
<h2><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-EnablingICESupport"></a>Enabling ICE Support </h2>
<p>Asterisk ICE support is enabled by default. However, as ICE needs a STUN and/or TURN server to gather usable candidates, these do need to be configured to get things working. Since ICE is an RTP level feature, the configuration can be found in the <tt>rtp.conf</tt> file. The configuration applies to all RTP based communications so the options are set in the <tt>general</tt> section. To configure a STUN server add a <tt>stunaddr</tt> option with the hostname of the STUN server. For example, </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>
stunaddr=setyourphaserson.stun.org
</pre>
</div></div>
<p><em>A short list of publicly accessible STUN servers can be found at the <a href="http://www.voip-info.org/wiki/view/STUN" class="external-link" rel="nofollow">VoIP-Info's STUN</a> page.</em> </p>
<p>TURN servers are required for relay candidates and are configured through the <tt>turnaddr</tt> property. TURN servers often require authentication so options are provided for configuring the username and password. </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>
turnaddr=4everyseason.turn.org
turnusername=relayme
turnpassword=please
</pre>
</div></div>
<p>The <tt>turnport</tt> option can also be used if the TURN server is running on a non-standard port. If omitted, Asterisk uses the standard port number 3478. </p>
<p>Since ICE is enabled by default, configuration of the STUN server and optionally, the TURN server, is all that is required to get things running. </p>
<p>Successful configuration can be visually verified by turning SIP debugging on (<tt>sip set debug on</tt>) in an Asterisk console and looking at INVITE messages as they go past. The body of a typical message would look something like this: </p>
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>
0: v=0
1: o=root 1903343929 1903343929 IN IP4 10.0.1.40
2: s=Asterisk PBX SVN-trunk-r372051
3: c=IN IP4 10.0.1.40
4: t=0 0
5: m=audio 17234 RTP/AVP 0 3 8 101
6: a=rtpmap:0 PCMU/8000
7: a=rtpmap:3 GSM/8000
8: a=rtpmap:8 PCMA/8000
9: a=rtpmap:101 telephone-event/8000
10: a=fmtp:101 0-16
11: a=silenceSupp:off - - - -
12: a=ptime:20
13: a=ice-ufrag:0d9cc44338ad8ced48b2d92c34556f4e
14: a=ice-pwd:193c1361446d012a1e298d5278b5c4b6
15: a=candidate:Ha000128qZ 1 UDP 2130706431 10.0.1.40 17234 typ host
16: a=candidate:Ha00030f 1 UDP 2130706431 10.0.3.15 17234 typ host
17: a=candidate:S8e86c939 1 UDP 1694498815 142.134.201.57 17234 typ srflx
18: a=candidate:Ha000128 2 UDP 2130706430 10.0.1.40 17235 typ host
19: a=candidate:Ha00030f 2 UDP 2130706430 10.0.3.15 17235 typ host
20: a=candidate:S8e86c939 2 UDP 1694498814 142.134.201.57 17234 typ srflx
21: a=sendrecv
</pre>
</div></div>
<p>The lines 13 through to 20 are ICE specific. Lines 13 and 14 are automatically generated and are used to identify a peer endpoint in an ICE session. Lines 15 through 20 are examples of candidates. Lines 17 and 20 are examples of <em>server reflexive</em> candidates as indicated by the "type srflx" at the end of the candidate strings. Server reflexive address are obtained through STUN and indicate an external binding on the NAT firewall. There are two because there is one for RTP and one for RTCP. RTP and RTCP candidates are distinguishable by their <em>component id</em> , 1 for RTP or 2 for RTCP, and is the 2nd "field" of the candidate string. The candidate strings that end in "typ host" are for <em>host candidates</em> and indicate actual network interfaces on the host computer. In this case, the host running Asterisk had two network interfaces, one bound to 10.0.1.40 and one bound to 10.0.3.15. </p>
<h2><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-DisablingICESupport"></a>Disabling ICE Support </h2>
<p>Generation of SDP for ICE candidate lists can be disabled by adding <tt>icesupport = no</tt> to the general section in <tt>sip.conf</tt> or on a peer-by-peer basis. Since ICE operates on RTP, ICE details are configured in the <tt>rtp.conf</tt> file. To disable ICE support in RTP, add <tt>icesupport = no</tt> to the general section in <tt>rtp.conf</tt>. </p>
<h1><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-References"></a>References </h1>
<p><a name="InteractiveConnectivityEstablishment%28ICE%29inAsterisk-rfcs"></a> RFCS: </p>
<p><a href="http://tools.ietf.org/html/rfc5245" class="external-link" rel="nofollow">RFC 5245</a> Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols <br/>
<a href="http://tools.ietf.org/html/rfc5389" class="external-link" rel="nofollow">RFC 5389</a> Session Traversal Utilities for NAT (STUN) <br/>
<a href="http://tools.ietf.org/html/rfc5766" class="external-link" rel="nofollow">RFC 5766</a> Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN) </p>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;" class="grey">
<a href="https://wiki.asterisk.org/wiki/users/removespacenotification.action?spaceKey=AST">Stop watching space</a>
<span style="padding: 0px 5px;">|</span>
<a href="https://wiki.asterisk.org/wiki/users/editmyemailsettings.action">Change email notification preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/AST/Interactive+Connectivity+Establishment+%28ICE%29+in+Asterisk">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/display/AST/Interactive+Connectivity+Establishment+%28ICE%29+in+Asterisk?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>