The module contains REGISTER processing logic.

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.

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.

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):

                      SER
                  +---------+
UA1 ---- NAT1 ----| 5060    |
                  |         |
UA2 ---- NAT2 ----| 5090    |
                  +---------+

Registrar and usrloc would store the public IP of NAT with each registered contact, thus it would know how to reach both user agents.

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.

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:

                                 SER
                 INVITE UA1  +--------+     INVITE UA1
UA1 ---- NAT1 <------------- |  5060  | <----------------
                             |        |
UA2 ---- NAT2                |  5090  |
                             +--------+

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:

                                 SER
                 INVITE UA2  +--------+     INVITE UA2
UA1 ---- NAT1        +------ |  5060  | <---------------
                     |       |        |
UA2 ---- NAT2 X <----+       |  5090  |
                             +--------+

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:

                                 SER
                             +--------+     INVITE UA2
UA1 ---- NAT1                |  5060  | <---------------
                 INVITE UA2  |        |
UA2 ---- NAT2 <------------- |  5090  |
                             +--------+

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:

sip:1.2.3.4:5060;dstip=5.6.7.8;dstport=5090

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.

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:

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
Date: Fri, 02 Sep 2005 11:20:12 GMT

You can use append_time function from textops module to append the header field to the reply. Put the function before save("location"); in the configuration file.

if (uri == myself) {
    if (method == "REGISTER") {
        append_time();
        save("location");
        break;
    };
};

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.

Contact: <sip:nils@192.168.0.122:2532>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"

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.

The registrar module now looks for the sip instance parameter in the Contact URI:

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.

Contact: <sip:lando@192.168.0.2:2500>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b1f-448a-a8be-e29572ea3bee>"

Registrar module depends on the following SER modules: