<html>
<head>
<base href="https://wiki.asterisk.org/wiki">
<link rel="stylesheet" href="/wiki/s/2041/1/7/_/styles/combined.css?spaceKey=TOP&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/TOP/Registrar">Registrar</a></h2>
<h4>Page <b>edited</b> by <a href="https://wiki.asterisk.org/wiki/display/~mmichelson">Mark Michelson</a>
</h4>
<br/>
<h4>Changes (8)</h4>
<div id="page-diffs">
<table class="diff" cellpadding="0" cellspacing="0">
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The SIP registrar's job is to maintain a mapping of addresses-of-record (AoRs) to contact URIs. The registrar is responsible for letting other SIP services within a cluster know of updates to this mapping. The registrar populates this mapping based on incoming SIP REGISTER requests it receives. <br> <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Endpoints <br> <br>How does the AoR->contact URI mapping apply to configured SIP endpoints? SIP endpoints will be configured to determine which AoRs they are associated with. For instance, if a SIP endpoint named "Bob" were to be configured to be associated with the AoR "sip:bob@example.com" then this would imply the following things: <br> <br># REGISTER requests from Bob would be permitted to add and remove bindings for the AoR sip:bob@example.com <br># SIP Requests targeted at sip:bob@example.com would be targeted for Bob. <br> <br>An endpoint may be associated with multiple AoRs and multiple endpoints may be associated with the same AoR. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Registration data <br> <br></td></tr>
<tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">First, let's define what</span> <span class="diff-added-words"style="background-color: #dfd;">What is</span> a <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">single "registration" is.</span> <span class="diff-added-words"style="background-color: #dfd;">"registration?"</span> A registration in Asterisk SCF is a single contact URI that is bound to an AoR. We can infer from this that a single AoR may have multiple registrations associated with it, and <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">we can also see that</span> a single REGISTER message may create multiple registrations in Asterisk SCF. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Registrations need to be defined in slice since the registrar will need to replicate its state. Here we go: <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">The Registration object is defined in slice since the registrar's state will need to be replicated. <br></td></tr>
<tr><td class="diff-unchanged" > <br>{code: language=slice} <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >The {{Registration}} object represents all the state data that needs to be replicated between registrars. Individual registrars will be responsible for scheduling destruction of their local registration <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">objects. This can be accomplished using</span> <span class="diff-added-words"style="background-color: #dfd;">objects based on</span> the <span class="diff-changed-words">expiration<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;"> transmitted in the {{Registration}}</span>.</span> <br></td></tr>
<tr><td class="diff-unchanged" > <br>h1. Interfaces <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
<tr><td class="diff-changed-lines" >A {{RegistrationListener}} registers itself with the {{Registrar}} in order to receive updates about the {{Registrar}}'s bindings. <span class="diff-added-words"style="background-color: #dfd;">Most {{RegistrarListeners}} will be other SIP services that need to use the registration data.</span> A {{RegistrarListener}} is always provided with a {{ContactDict}} instead of a {{RegistrationDict}} because information besides the contact in a {{Registration}} is not useful outside the registrar service. If a component wishes to get a full {{Registration}} it may use a variant of {{getRegistrations}} to do so. <br></td></tr>
<tr><td class="diff-unchanged" > <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;">You may notice that SIP endpoints are not referenced at all in these interfaces. The reason is that, as of this article's creation, there is no such thing as a SIP endpoint defined in slice, much less a method of retrieving a list of SIP endpoints based on AoRs. As such, when a REGISTER is received, the registrar may use the routing service's endpoint location feature to locate an endpoint based on data in the from header. However, the registrar will not be able to find any other endpoints associated with the AoR. The responsibility for updating local endpoints falls to the {{RegistrarListeners}}. <br> <br></td></tr>
<tr><td class="diff-unchanged" >h1. Operation <br> <br></td></tr>
<tr><td class="diff-snipped" >...<br></td></tr>
<tr><td class="diff-unchanged" >The diagram shows that when contacts are added or removed from the registrar, the {{RegistrarListener}} is notified. Notice the third REGISTER transaction does not result in the listener being <br>notified. This is because the REGISTER in question was refreshing the expiration period for a previously-established contact. While this results in internal changes to the registrar (as well as state replication changes), {{RegistrarListeners}} do not need to be updated. <br></td></tr>
<tr><td class="diff-added-lines" style="background-color: #dfd;"> <br>h1. Future improvements <br> <br>* The registrar specification does not currently authorize third party registrations. By this, I mean that an endpoint can only be configured to update his own AoRs, not those associated with other endpoints. This could be allowed, but the configuration would become more complex for a feature that is not widely used. <br> <br>* Once SIP configuration interfaces and objects have stabilized, the section about {{RegistrarListeners}} may change. If it becomes practical, there may not be any such thing as a {{RegistrationListener}} if the registrar is able to push configuration updates for endpoints directly. <br></td></tr>
</table>
</div> <h4>Full Content</h4>
<div class="notificationGreySide">
<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/wiki/images/icons/emoticons/forbidden.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td>Work in progress</td></tr></table></div>
<h1><a name="Registrar-Registrar%27sDuties"></a>Registrar's Duties</h1>
<p>The SIP registrar's job is to maintain a mapping of addresses-of-record (AoRs) to contact URIs. The registrar is responsible for letting other SIP services within a cluster know of updates to this mapping. The registrar populates this mapping based on incoming SIP REGISTER requests it receives.</p>
<h1><a name="Registrar-Endpoints"></a>Endpoints</h1>
<p>How does the AoR->contact URI mapping apply to configured SIP endpoints? SIP endpoints will be configured to determine which AoRs they are associated with. For instance, if a SIP endpoint named "Bob" were to be configured to be associated with the AoR "sip:bob@example.com" then this would imply the following things:</p>
<ol>
<li>REGISTER requests from Bob would be permitted to add and remove bindings for the AoR sip:bob@example.com</li>
<li>SIP Requests targeted at sip:bob@example.com would be targeted for Bob.</li>
</ol>
<p>An endpoint may be associated with multiple AoRs and multiple endpoints may be associated with the same AoR.</p>
<h1><a name="Registrar-Registrationdata"></a>Registration data</h1>
<p>What is a "registration?" A registration in Asterisk SCF is a single contact URI that is bound to an AoR. We can infer from this that a single AoR may have multiple registrations associated with it, and a single REGISTER message may create multiple registrations in Asterisk SCF.</p>
<p>The Registration object is defined in slice since the registrar's state will need to be replicated.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
class Registration
{
/**
* The URI associated with this particular registration.
*/
string contact;
/**
* The Call-ID from the latest successful registration.
*/
string callid;
/**
* The CSeq from the latest successful registration.
*/
int cseq;
/**
* A UNIX timestamp indicating when the registration is set
* to expire
*/
int expiration;
};
sequence<Registration> RegistrationSeq;
dictionary<string, RegistrationSeq> RegistrationDict;
]]></script>
</div></div>
<p>The <tt>Registration</tt> object represents all the state data that needs to be replicated between registrars. Individual registrars will be responsible for scheduling destruction of their local registration objects based on the expiration.</p>
<h1><a name="Registrar-Interfaces"></a>Interfaces</h1>
<p>The registrar won't have much in the way of public interfaces since the data it makes available is pushed out to the other SIP services.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<script type="syntaxhighlighter" class="toolbar: false; theme: Confluence; brush: java; gutter: false"><![CDATA[
/**
* The first string in the dictionary is an AoR
* The string sequence is a list of all contacts
* bound to the particular AoR.
*/
dictionary<string, StringSeq> ContactDict;
/**
* A RegistrarListener is updated when registration
* information changes. Typical RegistrarListeners will
* be SIP services that require up-to-date registration
* information.
*/
interface RegistrarListener
{
/**
* Alerts the listener that contacts have been added.
* The AoR may itself be new or an AoR with previous
* bindings may have new contacts added to it.
*/
void contactsAdded(ContactDict contacts);
/**
* Alerts the listener that contacts have been removed.
* There is no specific call for indicating that an AoR
* no longer has contacts associated with it. After this
* method has been called, listeners should take
* appropriate action if the AoR has no bound contacts.
*/
void contactsRemoved(ContactDict contacts);
};
interface Registrar
{
/**
* Add a new listener to the registrar.
* The return value is the map of all AoRs and their
* bindings.
*/
ContactDict addListener(RegistrarListener *listener);
/**
* Remove a listener.
*/
void removeListener(RegistrarLister *listener);
/**
* Get the mapping of all active registrations.
*/
RegistrationDict getRegistrations();
/**
* Get all registrations associated with a particular AoR
*/
RegistrationSeq getRegistrations(string aor);
};
]]></script>
</div></div>
<p>A <tt>RegistrationListener</tt> registers itself with the <tt>Registrar</tt> in order to receive updates about the <tt>Registrar</tt>'s bindings. Most <tt>RegistrarListeners</tt> will be other SIP services that need to use the registration data. A <tt>RegistrarListener</tt> is always provided with a <tt>ContactDict</tt> instead of a <tt>RegistrationDict</tt> because information besides the contact in a <tt>Registration</tt> is not useful outside the registrar service. If a component wishes to get a full <tt>Registration</tt> it may use a variant of <tt>getRegistrations</tt> to do so.</p>
<p>You may notice that SIP endpoints are not referenced at all in these interfaces. The reason is that, as of this article's creation, there is no such thing as a SIP endpoint defined in slice, much less a method of retrieving a list of SIP endpoints based on AoRs. As such, when a REGISTER is received, the registrar may use the routing service's endpoint location feature to locate an endpoint based on data in the from header. However, the registrar will not be able to find any other endpoints associated with the AoR. The responsibility for updating local endpoints falls to the <tt>RegistrarListeners</tt>.</p>
<h1><a name="Registrar-Operation"></a>Operation</h1>
<p><span class="image-wrap" style=""><img src="/wiki/download/attachments/12550396/Registration.png?version=1&modificationDate=1299018543697" style="border: 0px solid black" /></span></p>
<p>The diagram shows that when contacts are added or removed from the registrar, the <tt>RegistrarListener</tt> is notified. Notice the third REGISTER transaction does not result in the listener being<br/>
notified. This is because the REGISTER in question was refreshing the expiration period for a previously-established contact. While this results in internal changes to the registrar (as well as state replication changes), <tt>RegistrarListeners</tt> do not need to be updated.</p>
<h1><a name="Registrar-Futureimprovements"></a>Future improvements</h1>
<ul>
<li>The registrar specification does not currently authorize third party registrations. By this, I mean that an endpoint can only be configured to update his own AoRs, not those associated with other endpoints. This could be allowed, but the configuration would become more complex for a feature that is not widely used.</li>
</ul>
<ul>
<li>Once SIP configuration interfaces and objects have stabilized, the section about <tt>RegistrarListeners</tt> may change. If it becomes practical, there may not be any such thing as a <tt>RegistrationListener</tt> if the registrar is able to push configuration updates for endpoints directly.</li>
</ul>
</div>
<div id="commentsSection" class="wiki-content pageSection">
<div style="float: right;">
<a href="https://wiki.asterisk.org/wiki/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
</div>
<a href="https://wiki.asterisk.org/wiki/display/TOP/Registrar">View Online</a>
|
<a href="https://wiki.asterisk.org/wiki/pages/diffpagesbyversion.action?pageId=12550396&revisedVersion=4&originalVersion=3">View Changes</a>
|
<a href="https://wiki.asterisk.org/wiki/display/TOP/Registrar?showComments=true&showCommentArea=true#addcomment">Add Comment</a>
</div>
</div>
</div>
</div>
</div>
</body>
</html>