- regenerated README

modules_s/registrar/README

@@ -1,4 +1,3 @@
-
 1. Registrar Module
 
 Jan Janak
@@ -8,16 +7,34 @@ Jan Janak
    Copyright © 2003 FhG FOKUS
    Revision History
    Revision $Revision$ $Date$
-     _________________________________________________________________
-
-   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.4. Processing +sip.instance parameter
+   1.5. Dependencies
+   1.6. Parameters
+
+        1.6.1. default_expires (integer)
+        1.6.2. min_expires (integer)
+        1.6.3. max_expires (integer)
+        1.6.4. default_q (integer)
+        1.6.5. append_branches (integer)
+        1.6.6. use_domain (integer)
+        1.6.7. case_sensitive (integer)
+        1.6.8. desc_time_order (integer)
+        1.6.9. received_avp (integer)
+        1.6.10. received_param (integer)
+        1.6.11. max_contacts (integer)
+        1.6.12. retry_after (integer)
+
+   1.7. Functions
+
+        1.7.1. save(domain)
+        1.7.2. save_noreply(domain)
+        1.7.3. lookup(domain)
+        1.7.4. registered(domain)
 
 1.1. Overview
 
@@ -33,17 +50,16 @@ Jan Janak
    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):
+   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    |
@@ -54,16 +70,16 @@ 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.
+   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:
+   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  | <----------------
@@ -73,8 +89,8 @@ 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:
+   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  | <---------------
@@ -94,21 +110,21 @@ 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.
+   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.
+   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
 
@@ -126,8 +142,8 @@ Call-ID: [email protected]
 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.
+   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) {
@@ -138,32 +154,75 @@ if (uri == myself) {
     };
 };
 
-1.4. Dependencies
+1.4. Processing +sip.instance parameter
+
+   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.
+
+   Example 2. A Contact header with sip instance parameter
+Contact: <sip:[email protected]:2532>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5
+b1f-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:
+     * 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.
+     * 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.
+
+   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.
+
+   Example 3.
+Contact: <sip:[email protected]:2500>;q=1.0;+sip.instance="<urn:uuid:6a66f3bd-5b
+1f-448a-a8be-e29572ea3bee>"
+
+1.5. Dependencies
 
    Registrar module depends on the following SER modules:
      * usrloc - User Location Module.
      * sl - Stateless Replies.
 
-1.5. Parameters
+1.6. Parameters
 
    Revision History
    Revision $Revision$ $Date$
 
-1.5.1. default_expires (integer)
+1.6.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).
+   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
+   Example 4. Set default_expires parameter
 ...
 modparam("registrar", "default_expires", 1800)
 ...
 
-1.5.2. min_expires (integer)
+1.6.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
@@ -171,25 +230,25 @@ modparam("registrar", "default_expires", 1800)
 
    Default value is 60.
 
-   Example 3. Set min_expires parameter
+   Example 5. Set min_expires parameter
 ...
 modparam("registrar", "min_expires", 60)
 ...
 
-1.5.3. max_expires (integer)
+1.6.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
+   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
+   Example 6. Set max_expires parameter
 ...
 modparam("registrar", "max_expires", 120)
 ...
 
-1.5.4. default_q (integer)
+1.6.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
@@ -198,29 +257,29 @@ modparam("registrar", "max_expires", 120)
 
    Default value is 0.
 
-   Example 5. Set default_q parameter
+   Example 7. Set default_q parameter
 ...
 modparam("registrar", "default_q", 100)
 ...
 
-1.5.5. append_branches (integer)
+1.6.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.
+   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
+   Example 8. Set append_branches parameter
 ...
 modparam("registrar", "append_branches", 0)
 ...
 
-1.5.6. use_domain (integer)
+1.6.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
@@ -228,43 +287,43 @@ modparam("registrar", "append_branches", 0)
 
    Default value is 0.
 
-   Example 7. Set use_domain parameter
+   Example 9. Set use_domain parameter
 ...
 modparam("registrar", "use_domain", 1)
 ...
 
-1.5.7. case_sensitive (integer)
+1.6.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
+   Example 10. Set case_sensitive parameter
 ...
 modparam("registrar", "case_sensitive", 1)
 ...
 
-1.5.8. desc_time_order (integer)
+1.6.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.
+   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
+   Example 11. Set desc_time_order parameter
 ...
 modparam("registrar", "desc_time_order", 1)
 ...
 
-1.5.9. received_avp (integer)
+1.6.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.
+   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
 
@@ -273,44 +332,43 @@ Note
 
    Default value is 42.
 
-   Example 10. Set received_avp parameter
+   Example 12. Set received_avp parameter
 ...
 modparam("registrar", "received_avp", 43)
 ...
 
-1.5.10. received_param (integer)
+1.6.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
+   Example 13. Set received_param parameter
 ...
 modparam("registrar", "received_param", "rcv")
 ...
 
-1.5.11. max_contacts (integer)
+1.6.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.
+   (Address of Record) in the user location database. Value 0 disables the
+   check.
 
    Default value is 0.
 
-   Example 12. Set max_contacts parameter
+   Example 14. Set max_contacts parameter
 ...
 # Allow no more than 10 contacts per AOR
 modparam("registrar", "max_contacts", 10)
 ...
 
-1.5.12. retry_after (integer)
+1.6.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.
+   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
@@ -318,34 +376,34 @@ modparam("registrar", "max_contacts", 10)
 
    Default value is 0 (disabled).
 
-   Example 13. Set retry_after parameter
+   Example 15. Set retry_after parameter
 ...
 modparam("registrar", "retry_after", 30)
 ...
 
-1.6. Functions
+1.7. Functions
 
    Revision History
    Revision $Revision$ $Date$
 
-1.6.1.  save(domain)
+1.7.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.
+   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
+   Example 16. save usage
 ...
 save("location");
 ...
 
-1.6.2.  save_noreply(domain)
+1.7.2.  save_noreply(domain)
 
    Same as save() but it doesn't send a reply.
 
@@ -353,12 +411,12 @@ save("location");
      * 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
+   Example 17. save_noreply usage
 ...
 save_noreply("location");
 ...
 
-1.6.3.  lookup(domain)
+1.7.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
@@ -370,12 +428,12 @@ save_noreply("location");
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
 
-   Example 16. lookup usage
+   Example 18. lookup usage
 ...
 lookup("location");
 ...
 
-1.6.4.  registered(domain)
+1.7.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
@@ -385,7 +443,7 @@ lookup("location");
    Meaning of the parameters is as follows:
      * domain - Name of table that should be used for the lookup.
 
-   Example 17. registered usage
+   Example 19. registered usage
 ...
 if (registered("location")) {
     sl_send_reply("100", "Trying");