
1. Registrar Module

Jan Janak

   FhG FOKUS

   Copyright © 2003 FhG FOKUS
   Revision History
   Revision $Revision: 1.11 $ $Date: 2005/09/02 11:36:37 $
     _________________________________________________________________

   Table of Contents

   1.1. Overview
   1.2. NAT Support In Registrar
   1.3. Synchronizing UA Internal Clock
   1.4. Dependencies
   1.5. Parameters
   1.6. Functions

1.1. Overview

   The module contains REGISTER processing logic.

1.2. NAT Support In Registrar

   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 publi 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 remmember 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  |
                             +--------+

Note

   The X next to NAT2 has disappeared in this picture which means that
   the message will be lucky enough to make it through.

   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.

1.3. Synchronizing UA Internal Clock

   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.

   Example 1. Adding Date header to Replies
if (uri == myself) {
    if (method == "REGISTER") {
        append_time();
        save("location");
        break;
    };
};

1.4. Dependencies

   Registrar module depends on the following SER modules:
     * usrloc - User Location Module.
     * sl - Stateless Replies.

1.5. Parameters

   Revision History
   Revision $Revision: 1.11 $ $Date: 2005/09/02 11:36:37 $

1.5.1. default_expires (integer)

   If the processed message contains neither Expires HFs nor expires
   contact parameters, this value will be used for newly created usrloc
   records. The parameter contains number of second to expire (for
   example use 3600 for one hour).

   Default value is 3600.

   Example 2. Set default_expires parameter
...
modparam("registrar", "default_expires", 1800)
...

1.5.2. min_expires (integer)

   The minimum expires value of a Contact, values lower than this minimum
   will be automatically set to the minimum. Value 0 disables the
   checking.

   Default value is 60.

   Example 3. Set min_expires parameter
...
modparam("registrar", "min_expires", 60)
...

1.5.3. max_expires (integer)

   The maximum expires value of a Contact, values higher than this
   maximum will be automatically set to the maximum. Value 0 disables the
   checking.

   Default value is 0.

   Example 4. Set max_expires parameter
...
modparam("registrar", "max_expires", 120)
...

1.5.4. default_q (integer)

   The parameter represents default q value for new contacts. Because ser
   doesn't support float parameter types, the value in the parameter is
   divided by 100 and stored as float. For example, if you want default_q
   to be 0.38, use value 38 here.

   Default value is 0.

   Example 5. Set default_q parameter
...
modparam("registrar", "default_q", 100)
...

1.5.5. append_branches (integer)

   The parameter controls how lookup function processes multiple
   contacts. If there are multiple contacts for the given username in
   usrloc and this parameter is set to 1, Request-URI will be overwritten
   with the highest-q rated contact and the rest will be appended to
   sip_msg structure and can be later used by tm for forking. If the
   parameter is set to 0, only Request-URI will be overwritten with the
   highest-q rated contact and the rest will be left unprocessed.

   Default value is 1.

   Example 6. Set append_branches parameter
...
modparam("registrar", "append_branches", 0)
...

1.5.6. use_domain (integer)

   If set to 1 then the registrar will use username@domain as address of
   record. If the variable is set to 0 then only username will be used as
   the address of record.

   Default value is 0.

   Example 7. Set use_domain parameter
...
modparam("registrar", "use_domain", 1)
...

1.5.7. case_sensitive (integer)

   If set to 1 then AOR comparison will be case sensitive, if set to 0
   then AOR comparison will be case insensitive--This is recommended.

   Default value is 0.

   Example 8. Set case_sensitive parameter
...
modparam("registrar", "case_sensitive", 1)
...

1.5.8. desc_time_order (integer)

   If set to 1 then all contacts will be ordered in descending
   modification time order. In this case the most recently
   updated/created contact will be used.

   Default value is 0.

   Example 9. Set desc_time_order parameter
...
modparam("registrar", "desc_time_order", 1)
...

1.5.9. received_avp (integer)

   Registrar will store the value of the AVP configured by this parameter
   in the received column in the user location database. It will leave
   the column empty if the AVP is empty. The AVP should contain a SIP URI
   consisting of the source IP, port, and protocol of the REGISTER
   message being processed.

Note

   The value of this parameter should be the same as the value of
   corresponding parameter of nathelper module.

   Default value is 42.

   Example 10. Set received_avp parameter
...
modparam("registrar", "received_avp", 43)
...

1.5.10. received_param (integer)

   The name of the parameter that will be appended to Contacts of 200 OK
   when the received URI was set by nathelper module.

   Default value is "received".

   Example 11. Set received_param parameter
...
modparam("registrar", "received_param", "rcv")
...

1.5.11. max_contacts (integer)

   The parameter can be used to limit the number of contacts per AOR
   (Address of Record) in the user location database. Value 0 disables
   the check.

   Default value is 0.

   Example 12. Set max_contacts parameter
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...

1.5.12. retry_after (integer)

   The registrar can generate 5xx reply to REGISTER in various
   situations. It can, for example, happen when the max_contacts
   parameter is set and the processing of REGISTER request would exceed
   the limit. In this case the registrar would generate "503 Service
   Unavailable" response.

   If you want to add the Retry-After header field in 5xx replies, set
   this parameter to a value grater than zero (0 means do not add the
   header field). See section 20.33 of RFC3261 for more details.

   Default value is 0 (disabled).

   Example 13. Set retry_after parameter
...
modparam("registrar", "retry_after", 30)
...

1.6. Functions

   Revision History
   Revision $Revision: 1.11 $ $Date: 2005/09/02 11:36:37 $

1.6.1.  save(domain)

   The function processes a REGISTER message. It can add, remove or
   modify usrloc records depending on Contact and Expires HFs in the
   REGISTER message. On success, 200 OK will be returned listing all
   contacts that are currently in usrloc. On an error, error message will
   be send with a short description in reason phrase.

   Meaning of the parameters is as follows:
     * domain - Logical domain within registrar. If database is used then
       this must be name of the table which stores the contacts.

   Example 14. save usage
...
save("location");
...

1.6.2.  save_noreply(domain)

   Same as save() but it doesn't send a reply.

   Meaning of the parameters is as follows:
     * domain - Logical domain within registrar. If database is used then
       this must be na e of the table which stores the contacts.

   Example 15. save_noreply usage
...
save_noreply("location");
...

1.6.3.  lookup(domain)

   The functions extracts username from Request-URI and tries to find all
   contacts for the username in usrloc. If there are no such contacts, -1
   will be returned. If there are such contacts, Request-URI will be
   overwritten with the contact that has the highest q value and
   optionally the rest will be appended to the message (depending on
   append_branches parameter value).

   Meaning of the parameters is as follows:
     * domain - Name of table that should be used for the lookup.

   Example 16. lookup usage
...
lookup("location");
...

1.6.4.  registered(domain)

   The function returns true if the AOR in the Request-URI is registered,
   false otherwise. The function does not modify the message being
   process, it neither rewrites the Request-URI if a contact is found not
   append branches.

   Meaning of the parameters is as follows:
     * domain - Name of table that should be used for the lookup.

   Example 17. registered usage
...
if (registered("location")) {
    sl_send_reply("100", "Trying");
    ...
};
...
