registrar Module

Jan Janak

FhG FOKUS

Daniel-Constantin Mierla

Edited by

Jan Janak

Edited by

Bogdan-Andre Iancu

Revision History
Revision $Revision: 4594 $$Date: 2008-08-06 12:08:33 +0200 (Wed, 06 Aug 2008) $

Table of Contents

1. Admin Guide
1.1. Overview
1.1.1. PATH support
1.2. Dependencies
1.2.1. Kamailio 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. tcp_persistent_flag (integer)
1.3.6. realm_prefix (string)
1.3.7. append_branches (integer)
1.3.8. aor_avp (str)
1.3.9. case_sensitive (integer)
1.3.10. received_avp (str)
1.3.11. received_param (string)
1.3.12. max_contacts (integer)
1.3.13. retry_after (integer)
1.3.14. sock_flag (integer)
1.3.15. sock_hdr_name (string)
1.3.16. method_filtering (integer)
1.3.17. use_path (integer)
1.3.18. path_mode (integer)
1.3.19. path_use_received (integer)
1.3.20. reg_callid_avp (string)
1.4. Exported Functions
1.4.1. save(domain)
1.4.2. save(domain,flags)
1.4.3. lookup(domain)
1.4.4. registered(domain)
1.4.5. add_sock_hdr(hdr_name)
1.4.6. unregister(domain, uri)
1.4.7. reg_fetch_contacts(domain, uri, profile)
1.4.8. reg_free_contacts(profile)
1.5. Exported Statistics
1.5.1. max_expires
1.5.2. max_contacts
1.5.3. defaults_expires
1.5.4. accepted_regs
1.5.5. rejected_regs
1.6. Exported pseudo-variables
1.6.1. $ulc(profile=>attr)
2. 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 tcp_persistent_flag parameter
1.6. Set realm_prefix parameter
1.7. Set append_branches parameter
1.8. Set aor_avp parameter
1.9. Set case_sensitive parameter
1.10. Set received_avp parameter
1.11. Set received_param parameter
1.12. Set max_contacts parameter
1.13. Set retry_after parameter
1.14. Set sock_flag parameter
1.15. Set sock_hdr_namer parameter
1.16. Set method_filtering parameter
1.17. Set use_path parameter
1.18. Set path_mode parameter
1.19. Set path_use_received parameter
1.20. Set reg_callid_avp parameter
1.21. save usage
1.22. save usage
1.23. lookup usage
1.24. registered usage
1.25. add_sock_hdr usage
1.26. registered usage
1.27. registered usage
1.28. registered usage
1.29. $ulc(name) usage

Chapter 1. Admin 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. Kamailio 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 Kamailio 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). If it is set to a lower value than the “min_expires” parameter then it will be ignored.

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 Kamailio doesn't support float parameter types, the value in the parameter is divided by 1000 and stored as float. For example, if you want default_q to be 0.38, use value 380 here.

Default value is 0.

Example 1.4. Set default_q parameter

...
modparam("registrar", "default_q", 1000)
...

1.3.5. tcp_persistent_flag (integer)

The parameter specifies the message flag 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.5. Set tcp_persistent_flag parameter

...
modparam("registrar", "tcp_persistent_flag", 7)
...

1.3.6. 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.6. Set realm_prefix parameter

...
modparam("registrar", "realm_prefix", "sip.")
...

1.3.7. 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.7. Set append_branches parameter

...
modparam("registrar", "append_branches", 0)
...

1.3.8. aor_avp (str)

If set, the module will try first to get the AOR from this AVP instead of fetching it form the processed request.

The AVP must contain a valid SIP URI. If no AVP is found, it will be tried to get the AOR from the message (standard behaviour).

Default value is "NULL" (disabled).

Example 1.8. Set aor_avp parameter

...
modparam("registrar", "aor_avp", "$avp(i:3223)")
...

1.3.9. case_sensitive (integer)

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

Default value is 0.

Example 1.9. Set case_sensitive parameter

...
modparam("registrar", "case_sensitive", 1)
...

1.3.10. received_avp (str)

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 "NULL" (disabled).

Example 1.10. Set received_avp parameter

...
modparam("registrar", "received_avp", "$avp(s:rcv)")
...

1.3.11. received_param (string)

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.11. Set received_param parameter

...
modparam("registrar", "received_param", "rcv")
...

1.3.12. 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.12. Set max_contacts parameter

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

1.3.13. 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.13. Set retry_after parameter

...
modparam("registrar", "retry_after", 30)
...
		

1.3.14. sock_flag (integer)

Message 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.14. Set sock_flag parameter

...
modparam("registrar", "sock_flag", 18)
...
		

1.3.15. sock_hdr_name (string)

Header which contains a socket description (proto:IP:port) to override the received socket info. The header 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.15. Set sock_hdr_namer parameter

...
modparam("registrar", "sock_hdr_name", "Sock-Info")
...
		

1.3.16. 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.16. Set method_filtering parameter

...
modparam("registrar", "method_filtering", 1)
...
		

1.3.17. 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.17. Set use_path parameter

...
modparam("registrar", "use_path", 1)
...
		

1.3.18. 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.18. Set path_mode parameter

...
modparam("registrar", "path_mode", 0)
...
		

1.3.19. 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 branch 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.19. Set path_use_received parameter

...
modparam("registrar", "path_use_received", 1)
...
		

1.3.20. reg_callid_avp (string)

If reg_callid_avp is defined and populated when registered() is invoked, the result is TRUE only if an active registration with the specified callID is found.

Default value is NULL (disabled).

Example 1.20. Set reg_callid_avp parameter

...
modparam("registrar", "reg_callid_avp", "$avp(s:avp)")
...
		

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 and when called from the REQUEST_ROUTE, 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 and REPLY_ROUTE.

Example 1.21. save usage

...
save("location");
...

1.4.2.  save(domain,flags)

Same as save() but it accepts a set of flags for controlling its behaviour.

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.

  • flags - the value may be a bitwise OR of the following flags:

    • 0x01 - save the contacts only in memory cache without no DB operation;

    • 0x02 - do not generate a SIP reply to the current REGISTER request. When used in ONREPLY_ROUTE, this parameter is obsolete.

    • 0x04 - store and maintain one contact per AoR. If there are other contact addresses for AoR not matching current registration, remove them. This mode ensures one contact per AoR (user).

    The flags may be given in decimal or hexa format.

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

Example 1.22. save usage

...
save("location","0x01");
...

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

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.23. lookup usage

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

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

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

Example 1.24. registered usage

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

1.4.5.  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.25. add_sock_hdr usage

...
add_sock_hdr("Sock-Info");
...

1.4.6.  unregister(domain, uri)

The function remove all the contact associated to 'uri'.

Meaning of the parameters is as follows:

  • domain - Name of table that should be used for the lookup or contact addresses.

  • uri - The SIP URI address of the user which to remove the contact addresses for. It can contain pseudo-variables that are evaluated at runtime.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

Example 1.26. registered usage

...
unregister("location", "$ru");
unregister("location", "sip:user@kamailio.org");
...

1.4.7.  reg_fetch_contacts(domain, uri, profile)

The function fetches the contacts for 'uri' from table 'domain' to pseudo-variable $ulc(profile).

Meaning of the parameters is as follows:

  • domain - Name of table that should be used for the lookup of contact addresses.

  • uri - The SIP URI address of the user which to fetch the contact addresses for. It can contain pseudo-variables that are evaluated at runtime.

  • profile - Name of $ulc pseudo-variable profile that will store the fetched contacts. It is a static string.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

Example 1.27. registered usage

...
reg_fetch_contacts("location", "$ru", "callee");
reg_fetch_contacts("location", "sip:user@kamailio.org", "caller");
...

1.4.8.  reg_free_contacts(profile)

The function frees the contacts from pseudo-variable $ulc(profile). Should be called to release the content of a profile. Anyhow, fetching a new contact addresses set over a profile will release any existing data in that profile.

Meaning of the parameters is as follows:

  • profile - Name of $ulc pseudo-variable profile that stores fetched contacts. It is a static string.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

Example 1.28. registered usage

...
reg_free_contacts("callee");
...

1.5. Exported Statistics

1.5.1. max_expires

Value of max_expires parameter.

1.5.2. max_contacts

The value of max_contacts parameter.

1.5.3. defaults_expires

The value of default_expires parameter.

1.5.4. accepted_regs

Number of accepted registrations.

1.5.5. rejected_regs

Number of rejected registrations.

1.6. Exported pseudo-variables

1.6.1. $ulc(profile=>attr)

Access the attributes of contact addresses stored in 'profile'. It must be used after a call of “reg_fetch_contacts()”.

The “profile” has to be one of the values used with “reg_fetch_contacts()”.

The “attr” can be:

  • aor - address of record

  • domain - use location domain name

  • aorhash - hash id for the record

  • count - number of contacts

  • addr - contact address

  • path - path vector

  • received - received address

  • expires - expires value

  • callid - call-id header value

  • q - the q value

  • flags - flags value

  • cflags - cflags value

  • user_agent - user agent

  • socket - local socket

  • modified - last modified time

  • methods - methods value

The pseudo-variable accepts positive index value to access a specific contact record.

Example 1.29. $ulc(name) usage

...
if(reg_fetch_contacts("location", "$fu", "caller"))
{
  xlog("caller=>aor: $(ulc(caller=>aor))\n");
  xlog("caller=>domain: $(ulc(caller=>domain))\n");
  xlog("caller=>aorhash $(ulc(caller=>aorhash))\n");
  xlog("caller=>count $(ulc(caller=>count))\n");
  $var(i) = 0;
  while($var(i) < $(ulc(caller=>count)))
  {
    xlog("--- contact [$var(i)]\n");
    xlog("caller=>addr:       $(ulc(caller=>addr)[$var(i)])\n");
    xlog("caller=>path:       $(ulc(caller=>path)[$var(i)])\n");
    xlog("caller=>received:   $(ulc(caller=>received)[$var(i)])\n");
    xlog("caller=>expires:    $(ulc(caller=>expires)[$var(i)])\n");
    xlog("caller=>callid:     $(ulc(caller=>callid)[$var(i)])\n");
    xlog("caller=>q:          $(ulc(caller=>q)[$var(i)])\n");
    xlog("caller=>cseq:       $(ulc(caller=>cseq)[$var(i)])\n");
    xlog("caller=>flags:      $(ulc(caller=>flags)[$var(i)])\n");
    xlog("caller=>cflags:     $(ulc(caller=>cflags)[$var(i)])\n");
    xlog("caller=>user_agent: $(ulc(caller=>user_agent)[$var(i)])\n");
    xlog("caller=>socket:     $(ulc(caller=>socket)[$var(i)])\n");
    xlog("caller=>modified:   $(ulc(caller=>modified)[$var(i)])\n");
    xlog("caller=>methods:    $(ulc(caller=>methods)[$var(i)])\n");
    $var(i) = $var(i) + 1;
  }
}
...
				 

Chapter 2. Frequently Asked Questions

2.1.

What happend with the old “nat_flag” module parameter?

In was removed, as the module internally loads this value from the “USRLOC” module (see the “nat_bflag” USRLOC parameter).

2.2.

What happend with the old “use_domain” module parameter?

In was removed, as the module internally loads this option from the “USRLOC” module. This was done in order to simplify the configuration.

2.3.

What happend with the old “save_noreply” and “save_memory” functions?

There functions were merged into the new “save(domain,flags)” functions. If a reply should be sent or if the DB should be updated also is controlled via the flags.

2.4.

Where can I find more about Kamailio?

Take a look at http://www.kamailio.org/.

2.5.

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:

E-mails regarding any stable Kamailio release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .

2.6.

How can I report a bug?

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

2.7.

What happened to the desc_time_order parameter?

It was removed, as its functionality was mmigrate into usrloc module, were there is a parameter with the same name.