registrar Module

Jan Janak

   FhG FOKUS

Edited by

Jan Janak

Bogdan-Andre Iancu

   Copyright  2003 FhG FOKUS
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview

              1.1.1. PATH support

        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. default_expires (integer)
              1.3.2. min_expires (integer)
              1.3.3. max_expires (integer)
              1.3.4. default_q (integer)
              1.3.5. nat_flag (integer)
              1.3.6. sip_natping_flag (integer)
              1.3.7. tcp_persistent_flag (integer)
              1.3.8. realm_prefix (string)
              1.3.9. append_branches (integer)
              1.3.10. use_domain (integer)
              1.3.11. case_sensitive (integer)
              1.3.12. desc_time_order (integer)
              1.3.13. received_avp (integer)
              1.3.14. received_param (integer)
              1.3.15. max_contacts (integer)
              1.3.16. retry_after (integer)
              1.3.17. sock_flag (integer)
              1.3.18. sock_hdr_name (string)
              1.3.19. use_branch_flags (integer)
              1.3.20. method_filtering (integer)
              1.3.21. use_path (integer)
              1.3.22. path_mode (integer)
              1.3.23. path_use_received (integer)

        1.4. Exported Functions

              1.4.1. save(domain)
              1.4.2. save_noreply(domain)
              1.4.3. save_memory(domain)
              1.4.4. lookup(domain)
              1.4.5. registered(domain)
              1.4.6. add_sock_hdr(hdr_name)

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Set default_expires parameter
   1-2. Set min_expires parameter
   1-3. Set max_expires parameter
   1-4. Set default_q parameter
   1-5. Set nat_flag parameter
   1-6. Set sip_natping_flag parameter
   1-7. Set tcp_persistent_flag parameter
   1-8. Set realm_prefix parameter
   1-9. Set append_branches parameter
   1-10. Set use_domain parameter
   1-11. Set case_sensitive parameter
   1-12. Set desc_time_order parameter
   1-13. Set received_avp parameter
   1-14. Set received_param parameter
   1-15. Set max_contacts parameter
   1-16. Set retry_after parameter
   1-17. Set sock_flag parameter
   1-18. Set sock_hdr_namer parameter
   1-19. Set use_branch_flags parameter
   1-20. Set method_filtering parameter
   1-21. Set use_path parameter
   1-22. Set path_mode parameter
   1-23. Set path_use_received parameter
   1-24. save usage
   1-25. save_noreply usage
   1-26. save_memory usage
   1-27. lookup usage
   1-28. registered usage
   1-29. add_sock_hdr usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   The module contains REGISTER processing logic.
     _________________________________________________________

1.1.1. PATH support

   Register module includes Path support (according to RFC 3327)
   for usage in registrars and home-proxies.

   A call to save(...) stores, if path-support is enabled in the
   registrar-module, the values of the Path Header(s) along with
   the contact into usrloc. There are three modes regarding the
   reply to a REGISTER including one or more Path HFs:

     * off - stores the value of the Path headers into usrloc
       without passing it back to the UAC in the reply.
     * lazy - stores the Path header and passes it back to the
       UAC if Path-support is indicated by the "path" param in
       the Supported HF.
     * strict - rejects the registration with "420 Bad Extension"
       if there's a Path header but no support for it is
       indicated by the UAC. Otherwise it's stored and passed
       back to the UAC.

   A call to lookup(...) always uses the path header if found,
   and inserts it as Route HF either in front of the first Route
   HF, or after the last Via HF if no Route is present. It also
   sets the destination uri to the first Path uri, thus
   overwriting the received-uri, because NAT has to be handled at
   the outbound-proxy of the UAC (the first hop after client's
   NAT).

   The whole process is transparent to the user, so no config
   changes are required beside setting the registrar-parameters
   "use_path" and "path_mode".
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * usrloc - User Location Module.
     * sl - Stateless Replies.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.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 1-1. Set default_expires parameter
...
modparam("registrar", "default_expires", 1800)
...
     _________________________________________________________

1.3.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 1-2. Set min_expires parameter
...
modparam("registrar", "min_expires", 60)
...
     _________________________________________________________

1.3.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 1-3. Set max_expires parameter
...
modparam("registrar", "max_expires", 120)
...
     _________________________________________________________

1.3.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 1-4. Set default_q parameter
...
modparam("registrar", "default_q", 100)
...
     _________________________________________________________

1.3.5. nat_flag (integer)

   The parameter specifies the flag to be used as NAT marker. The
   idea is to set this flag if a register come behind a NAT; the
   "save()" functions will save the flag in the usrloc, flag that
   will be restore by the "lookup()" function.

   Default value is -1 (disabled). 

   Example 1-5. Set nat_flag parameter
...
modparam("registrar", "nat_flag", 6)
...
     _________________________________________________________

1.3.6. sip_natping_flag (integer)

   The parameter specifies the flat to be used to mark the
   contacts to be NAT pinged via a SIP request instead if dummy
   UDP package. The flag will be stored in usrloc by the "save()"
   functions and internally used by the "nathelper" module. The
   flag will NOT be restore by the "lookup()" function.

   Default value is -1 (disabled). 

   Example 1-6. Set sip_natping_flag parameter
...
modparam("registrar", "sip_natping_flag", 7)
...
     _________________________________________________________

1.3.7. tcp_persistent_flag (integer)

   The parameter specifies the flat to be used to control the
   module behaviour regarding TCP connections. If the flag is set
   for a REGISTER via TCP containing a TCP contact, the module,
   via the "save()" functions will set the lifetime of the TCP
   connection to the contact expire value. By doing this, the TCP
   connection will stay on as long as the contact is valid.

   Default value is -1 (disabled). 

   Example 1-7. Set tcp_persistent_flag parameter
...
modparam("registrar", "tcp_persistent_flag", 7)
...
     _________________________________________________________

1.3.8. realm_prefix (string)

   Prefix to be automatically strip from realm. As an alternative
   to SRV records (not all SIP clients support SRV lookup), a
   subdomain of the master domain can be defined for SIP purposes
   (like sip.mydomain.net pointing to same IP address as the SRV
   record for mydomain.net). By ignoring the realm_prefix "sip.",
   at registration, sip.mydomain.net will be equivalent to
   mydomain.net .

   Default value is NULL (none). 

   Example 1-8. Set realm_prefix parameter
...
modparam("registrar", "realm_prefix", "sip.")
...
     _________________________________________________________

1.3.9. 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 1-9. Set append_branches parameter
...
modparam("registrar", "append_branches", 0)
...
     _________________________________________________________

1.3.10. 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 1-10. Set use_domain parameter
...
modparam("registrar", "use_domain", 1)
...
     _________________________________________________________

1.3.11. 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 1-11. Set case_sensitive parameter
...
modparam("registrar", "case_sensitive", 1)
...
     _________________________________________________________

1.3.12. 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 1-12. Set desc_time_order parameter
...
modparam("registrar", "desc_time_order", 1)
...
     _________________________________________________________

1.3.13. 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 1-13. Set received_avp parameter
...
modparam("registrar", "received_avp", 43)
...
     _________________________________________________________

1.3.14. 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 1-14. Set received_param parameter
...
modparam("registrar", "received_param", "rcv")
...
     _________________________________________________________

1.3.15. 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 1-15. Set max_contacts parameter
...
# Allow no more than 10 contacts per AOR
modparam("registrar", "max_contacts", 10)
...
     _________________________________________________________

1.3.16. 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 1-16. Set retry_after parameter
...
modparam("registrar", "retry_after", 30)
...
     _________________________________________________________

1.3.17. sock_flag (integer)

   Flag to signal to register module to look into REGISTER
   request for a header which contains a socket description
   (IP:port). This socket info will be stored by register instead
   of the received socket info.

   This make sens only in multiple replicated servers scenarios.

   Default value is -1 (no flag). 

   Example 1-17. Set sock_flag parameter
...
modparam("registrar", "sock_flag", 18)
...
     _________________________________________________________

1.3.18. sock_hdr_name (string)

   Header which contains a socket description (proto:IP:port) to
   overide the the received socket info. The heaer will be read
   only if the flag sock_flag is set.

   This make sens only in multiple replicated servers scenarios.

   Default value is NULL. 

   Example 1-18. Set sock_hdr_namer parameter
...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
     _________________________________________________________

1.3.19. use_branch_flags (integer)

   If enabled (has a non zero value), the NAT flag for the
   additional branches will be pushed in branch flags (in
   dset/branch array). Otherwise it will be pushed in the message
   flags. In both cases, the NAT flag for the RURI will be push
   into message flags.

   This make sens to be enabled only if branch route will be
   used.

   Default value is 0 (disabled). 

   Example 1-19. Set use_branch_flags parameter
...
modparam("registrar", "use_branch_flags", 1)
...
     _________________________________________________________

1.3.20. method_filtering (integer)

   Tells if the contact filtering based on supported methods
   should be performed during lookup. It's enabled only if it has
   a non zero value.

   Default value is 0 (disabled). 

   Example 1-20. Set method_filtering parameter
...
modparam("registrar", "method_filtering", 1)
...
     _________________________________________________________

1.3.21. use_path (integer)

   If set to 1, the Path header is handled according to the
   parameter "path_mode".

   Default value is 0 (disabled). 

   Example 1-21. Set use_path parameter
...
modparam("registrar", "use_path", 1)
...
     _________________________________________________________

1.3.22. path_mode (integer)

   The registrar module implements three different modes
   regarding the response to a registration which includes one or
   more Path headers:

     * 0 - The Path header is saved into usrloc, but is not
       included in the reply.
     * 1 - The Path header is saved into usrloc, but is only
       included in the reply if path support is indicated in the
       registration request by the "path" option of the
       "Supported" header.
     * 2 - The path header is only saved into usrloc, if path
       support is indicated in the registration request by the
       "path" option of the "Supported" header. If no path
       support is indicated, the request is rejected with "420 -
       Bad Extension" and the header "Unsupported: path" is
       included in the reply along with the received "Path"
       header. This mode is the one recommended by RFC-3327.

   Default value is 2. 

   Example 1-22. Set path_mode parameter
...
modparam("registrar", "path_mode", 0)
...
     _________________________________________________________

1.3.23. path_use_received (integer)

   If set to 1, the "received" parameter of the first Path uri of
   a registration is set as received-uri and the NAT flag is set
   for this contact. This is useful if the registrar is placed
   behind a SIP loadbalancer, which passes the nat'ed UAC address
   as "received" parameter in it's Path uri.

   Default value is 0 (disabled). 

   Example 1-23. Set path_use_received parameter
...
modparam("registrar", "path_use_received", 1)
...
     _________________________________________________________

1.4. Exported Functions

1.4.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.

   This function can be used from REQUEST_ROUTE.

   Example 1-24. save usage
...
save("location");
...
     _________________________________________________________

1.4.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 name of the table which stores the
       contacts.

   This function can be used from REQUEST_ROUTE.

   Example 1-25. save_noreply usage
...
save_noreply("location");
...
     _________________________________________________________

1.4.3. save_memory(domain)

   Same as save() but it updates only the memory cache, even if
   DB support (any type) is enabled.

   Meaning of the parameters is as follows:

     * domain - Logical domain within registrar (Ex: "location").

   This function can be used from REQUEST_ROUTE.

   Example 1-26. save_memory usage
...
save_memory("location");
...
     _________________________________________________________

1.4.4. 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).

   If the method_filtering option is enabled, the lookup function
   will return only the contacts that support the method of the
   processed request.

   Meaning of the parameters is as follows:

     * domain - Name of table that should be used for the lookup.

   Return codes:

     * 1 - contacts found and returned.
       -1 - no contact found.
       -2 - contacts found, but method not supported.
       -3 - internal error during processing.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1-27. lookup usage
...
lookup("location");
switch ($?) {
    case -1:
    case -3:
        sl_send_reply("404", "Not Found");
        exit;
    case -2:
        sl_send_reply("405", "Not Found");
        exit;
};
...
     _________________________________________________________

1.4.5. 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.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1-28. registered usage
...
if (registered("location")) {
        sl_send_reply("100", "Trying");
        ...
};
...
     _________________________________________________________

1.4.6. add_sock_hdr(hdr_name)

   Adds to the current REGISTER request a new header with
   "hdr_name" which contains the description of the received
   socket (proto:ip:port)

   This make sens only in multiple replicated servers scenarios.

   Meaning of the parameters is as follows:

     * hdr_name - header name to be used.

   This function can be used from REQUEST_ROUTE.

   Example 1-29. add_sock_hdr usage
...
add_sock_hdr("Sock-Info");
...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.