<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
	[ <!ENTITY % local.common.attrib
	 "xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
	 <!-- Include general documentation entities -->
	 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
	 %docentities;
	]
>

<section id="registrar" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
	<authorgroup>
	    <author>
		<firstname>Jan</firstname>
		<surname>Janak</surname>
		<affiliation><orgname>FhG FOKUS</orgname></affiliation>
		<address>
		    <email>jan@iptel.org</email>
		</address>
	    </author>
	</authorgroup>
	<copyright>
	    <year>2003</year>
	    <holder>FhG FOKUS</holder>
	</copyright>
    </sectioninfo>

    <title>Registrar Module</title>

    <section id="registrar.overview">
	<title>Overview</title>
	<para>The module contains REGISTER processing logic.</para>
    </section>

    <section id="nat_support">
	<title>NAT Support In Registrar</title>
	<para>
	    Registrar and usrloc modules implement NAT extensions that ensure
	    that SIP messages beging sent to registered contacts would use the
	    same socket (with the same IP address and port) on which the
	    REGISTER that registered the contact had been received. REGISTER
	    messages generated by user agents behind NAT ofter open a pinhole
	    in the NAT because REGISTER is usually the first message sent from
	    the user agent to the SIP server. A small example follows.
	</para>
	<para>
	    Let's suppose that we have a single SER instance listening on two
	    ports -- 5060 and 5090. Using a different port seems to be often
	    necessary because of broken SIP ALGs (Application Level Gateways)
	    that are often built into DSL routers or other devices. Such ALGs
	    would mangle SIP requests and responses coming to and from port
	    5060 and the only option how to avoid such mangling is using a
	    different port number.
	</para>
	<para>
	    Let's suppose that we have two UAs beind NAT, one of them is configured
	    to reach SER on port 5060, the other one is configured to use port 5090
	    (due to the reasons described above):
	</para>
	<programlisting>
                      SER
                  +---------+
UA1 ---- NAT1 ----| 5060    |
                  |         |
UA2 ---- NAT2 ----| 5090    |
                  +---------+
	</programlisting>
	<para>
	    Registrar and usrloc would store the public IP of NAT with each
	    registered contact, thus it would know how to reach both user
	    agents.
	</para>
	<para>
	    In addition to the public IP and port of the NAT device, registrar
	    would also remember the destination IP and port of the REGISTER
	    request (the IP and port used in SER). If registrar did not store
	    this information, it would not know what outbound socket it should
	    use when sending SIP messages to the registered contact. It would
	    use the default port number (often 5060) for such outgoing requests.
	</para>
	<para>
	    When an INVITE for UA1 comes, everything would work because UA1
	    used port 5060 when registering and that is also the destination
	    port in the pinhole being kept open in NAT1:
	</para>
	<programlisting>
<![CDATA[
                                 SER
                 INVITE UA1  +--------+     INVITE UA1
UA1 ---- NAT1 <------------- |  5060  | <----------------
                             |        |
UA2 ---- NAT2                |  5090  |
                             +--------+
]]>
	</programlisting>
	<para>
	    When an INVITE for UA2 comes, SER would again use port 5060 as the
	    default outgoing source port number, but this time the message will
	    be dropped by NAT2, because the pinhole opened during the
	    registration has 5060 as the destination port number:
	</para>
	<programlisting>
<![CDATA[
                                 SER
                 INVITE UA2  +--------+     INVITE UA2
UA1 ---- NAT1        +------ |  5060  | <---------------
                     |       |        |
UA2 ---- NAT2 X <----+       |  5090  |
                             +--------+
]]>
	</programlisting>
	<para>
	    That is the reason why registrar and usrloc also need to remember
	    the IP and port used on the server side, that information would be
	    used later when forwarding INVITEs:
	</para>
	<programlisting>
<![CDATA[
                                 SER
                             +--------+     INVITE UA2
UA1 ---- NAT1                |  5060  | <---------------
                 INVITE UA2  |        |
UA2 ---- NAT2 <------------- |  5090  |
                             +--------+
]]>
	</programlisting>
	<note>
	    <para>
		The X next to NAT2 has disappeared in this picture which means
		that the message will be lucky enough to make it through.
	    </para>
	</note>
	<para>
	    SER would encode this information into a SIP URI when saving contacts in
	    database and later, after restart of SER, this information will be
	    restored. The URI looks like:
	</para>
	<programlisting>
sip:1.2.3.4:5060;dstip=5.6.7.8;dstport=5090
	</programlisting>
	<para>
	    Where the hostname part is the public IP of the NAT, the port
	    (5060) is the port allocated by the NAT, "dstip" parameter is the
	    IP used on SER side and "dstport" parameter is the port number used
	    on SER side during registration. This information is later used to
	    find the correct outgoing socket in SER. If no such socket can be
	    found (it can happen if you reconfigure SER to use different ports
	    or IPs), it will use the default IP/port again.
	</para>
    </section>

    <section>
	<title>Synchronizing UA Internal Clock</title>
	<para>
	    Many existing user agents support date and time synchronization
	    from the registrar. Registrar can append "Date" header field to the
	    200 OK to REGISTER message received from the user agent. User
	    agents that support time synchronization would read the current
	    date and time from the header field and set internal clock to
	    it. For example:
	</para>
	<programlisting>
<![CDATA[
SIP/2.0 200 OK
Via: SIP/2.0/UDP 62.240.165.98;branch=z9hG4bK3E66B9EB
CSeq: 1469 REGISTER
To: "1 1" <sip:jan@charon.ok2rab.cz>;tag=2bd21cbe8bf183397d829c66d62463e6.0aea
From: "1 1" <sip:jan@charon.ok2rab.cz>
Call-ID: 1767561454@62.240.165.98]]>
<emphasis>Date: Fri, 02 Sep 2005 11:20:12 GMT</emphasis>
	</programlisting>
	<para>
	    You can use <function>append_time</function> function from textops
	    module to append the header field to the reply. Put the function
	    before <function>save("location");</function> in the configuration file.
	</para>

	<example>
	    <title>Adding Date header to Replies</title>
	    <programlisting>
if (uri == myself) {
    if (method == "REGISTER") {
        <emphasis>append_time();</emphasis>
        save("location");
        break;
    };
};
	    </programlisting>
	</example>
    </section>

	<section id="sip.instance">
	<title>Processing +sip.instance parameter</title>
	<para>
		The GRUU extension for SIP (draft-ietf-sip-gruu-04) adds a new parameter
		to the URI of the Contact header in the REGISTER request to identify a UA
		instance globaly unique in the world. This is reached by adding a globaly
		unqiue identifier, the so called sip instace, as a parameter to the Contact 
		URI within all REGISTER requests.
	</para>

	<example>
		<title>A Contact header with sip instance parameter</title>
		<programlisting>
<![CDATA[
Contact: <sip:nils@192.168.0.122:2532>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"]]>
		</programlisting>
	</example>

	<para>
		By looking at this sip instance parameter the registrar can decide if the
		incoming request is just an update of an existing Contact URI or if a new
		Contact URI has to be added to the AOR of this account. Thus even after a
		reboot of the UA the new REGISTER can be determined the request as an 
		update of an old, already existing entry.
	</para>

	<para>
		The registrar module now looks for the sip instance parameter in the Contact URI:
		<itemizedlist>
		<listitem>
			<para>
			If the sip instance parameter is not present in the URI of the Contact header 
			the algorithm stays the same as like before the GRUU extension. Which means 
			the registrar only compares the SIP URI from the Contact header with the 
			existing URIs for the AOR (account). If exactly the same URI already exists
			the existing entry will be updated, otherwise the URI will be added to the list.
			</para>
		</listitem>
		<listitem>
			<para>
			If the sip instace parameter is present in the URI of the Contact header it 
			will be first searched for an existing Contact with exactly the same sip 
			instance value. If an URI with exactly the same sip instance value exists 
			already in the database, the existing entry will be replaced with the new 
			value, no matter if they differ or not. If no Contact with this sip instance
			value exists a new entry for it will be added.
			</para>
		</listitem>
		</itemizedlist>
	</para>
	<para>
		For example the following Contact would replace the Contact value from the example
		above in the usrloc database because the sip instance value is the same, although
		the Contact URI differs. Without the sip instance this would have created two 
		entries in the usrloc database.
	</para>
	<example>
		<title>Different Contact with the same sip.instance</title>
		<programlisting>
<![CDATA[
Contact: <sip:lando@192.168.0.2:2500>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"]]>
		</programlisting>
	</example>
	</section>

    <section id="registrar.dep">
	<title>Dependencies</title>
	<para>
	    Registrar module depends on the following SER modules:
	    <itemizedlist>
		<listitem>
		    <para>
			<emphasis>usrloc</emphasis> - User Location Module.
		    </para>
		</listitem>
		<listitem>
		    <para>
			<emphasis>sl</emphasis> - Stateless Replies.
		    </para>
		</listitem>
	    </itemizedlist>
	</para>
    </section>

    <xi:include href="params.xml"/>
    <xi:include href="functions.xml"/>

</section>

