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

If path support is enabled in the registrar module, a call to save(...) stores 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:

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

GRUU (RFC5627) is supported with both public and temporary addresses.

The public GRUU is build based on the '+sip.instance' UUID parameter as recommended by RFC.

The temporary GRUU is built based on internal SRUID (unique id generator) and it is kept the same for the duration of contact validity.

The following modules must be loaded before this module:

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

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. This parameter can be modified via ser config framework. A random value in a specific interval can be selected by using the default_expires_range parameter

Default value is 3600.

...
modparam("registrar", "default_expires", 1800)
...

This parameter specifies that the expiry used for newly created usrloc records are not fixed, but a random value in the interval “[default_expires-default_expires_range%, default_expires]”. The value is between 0 and 100 and represent the maximim percentage from expires that will be substracted when computing the value. Default is 0, meaning default_expires is left unmodified. This parameter can be modified via the Kamailio config framework.

Default value is 0.

...
modparam("registrar", "default_expires_range", 30) # +- 30% from default_expires
...

Similar to default_expires_range, but it applies to the incoming expires value. Default in 0, meaning the expires is left unmodified. This parameter can be modified via the Kamailio config framework.

Default value is 0.

...
modparam("registrar", "expires_range", 30) # expires within [0.7*expires .. expires]
...

The minimum expires value of a “Contact”. Values lower than this minimum will be automatically set to the minimum. Value 0 disables the checking. This parameter can be modified via the Kamailio config framework.

Default value is 60.

...
modparam("registrar", "min_expires", 60)
...

The maximum accepted expires value of a “Contact”, values higher than this maximum will be automatically set to the maximum. Value 0 disables the checking. This parameter can be modified via the Kamailio config framework.

Default value is 0.

...
modparam("registrar", "max_expires", 120)
...

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. This parameter can be modified via the Kamailio config framework.

Default value is 0.

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

Prefix to be automatically stripped 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. This parameter can be modified via the Kamailio config framework.

Default value is NULL (none).

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

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. This parameter can be modified via Kamailio config framework.

Default value is 1.

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

This module parameter has been removed. Use the 'uri' parameter from functions (e.g., save, lookup, registered).

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. This parameter can be modified via Kamailio config framework.

Default value is 0.

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

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 transport protocol of the REGISTER message being processed.

Default value is "NULL" (disabled).

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

The name of the parameter that will be appended to Contact URI's of 200 OK when the received URI was set by the “nathelper” module. If the value is an empty string, then the parameter is not appended anymore.

Default value is "received".

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

The parameter can be used to limit the number of contacts per AOR (Address of Record) in the user location database. If the maximum number of contacts is exceeded, Kamailio will not accept the registration and send an error response. Value 0 disables the check. This parameter can be modified via the Kamailio config framework. (Please also check the flag for save() if you only want only one active registration).

Default value is 0.

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

The registrar can generate a 5xx reply to REGISTER requests 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. This parameter can be modified via the Kamailio config framework.

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

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

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

This makes sense only in multiple replicated servers scenarios.

Default value is -1 (no flag).

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

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 makes sense only in multiple replicated servers scenarios.

Default value is NULL.

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

Tells if the contact filtering based on supported methods should be performed during lookup on initial requests without to-tag. It's enabled only if it has a non zero value. Supported methods are listed in the “Allow:” header in the REGISTER message and stored in the location database.

Default value is 0 (disabled).

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

If set to 1, the “Path:” header is handled according to the parameter This parameter can be modified via Kamailio config framework. “path_mode”.

Default value is 0 (disabled).

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

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

Default value is 2.

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

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

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

If set to 1, when performing a lookup the Path (if present) is evaluated and if the first hop is local (according to “myself” test), we skip it to avoid unnecessary looping.

This is useful if multiple servers are sharing a common location database, each saving contacts with their local address as the Path.

Default value is 0 (disabled).

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

obsolete. use match_option in registered function

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

Default value is NULL (disabled).

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

Defines the name of XAVP class to store runtime module config values. The values are stored as inner XAVPs, like $xavp(class=>attribute). Valid inner XAVP names:

For example. if this parameter is set to 'reg', then the number of maximum contacts can be set in $xavp(reg=>max_contacts).

Default value is NULL (disabled).

...
modparam("registrar", "xavp_cfg", "reg")
...

Defines the name of XAVP class to store details from the location records. The values are stored as inner XAVPs, like $xavp(class[0]=>attribute). Valid inner XAVP names:

For example. if this parameter is set to 'ulrcd', then values are set in:

Default value is NULL (disabled).

...
modparam("registrar", "xavp_rcd", "ulrcd")
...

If set to 1 and the “+sip.instance” parameter to Contact header of REGISTER is present, then the value of the parameter is saved to location and pub-gruu and temp-gruu addresses are generated.

Set it to 0 if you want to ignore GRUU extensions in REGISTER.

Default value is 1 (enabled).

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

If set to 0 this module will accept REGISTER requests that do not contain a “Supported:” header with the outbound options-tag. The 200 OK response to REGISTER requests that this module generates will not contain “Require:” or “Supported:” headers with the outbound options-tag. If the client has a “Require:” header with the outbound options tag the REGISTER will be rejected with a “420 Bad Extension” response.

If set to 1 this module will accept REGISTER requests that do not contain a “Supported:” header with the outbound options-tag and REGISTER requests that do contain a Supported: or Requires: header with the outbound options-tag. When the client supports outbound the appropriate RFC5626 procedures will be followed.

If set to 2 this module will reject REGISTER requests that do not contain a “Supported:” header with the outbound options-tag. When the client supports outbound the appropriate RFC5626 procedures will be followed.

Default value is 0.

...
modparam("registrar", "outbound_mode", 2)
...

If set to 0 this module will ignore the “regid” contact param when saving REGISTER request if the request does not indicate support for outbound.

If set to 1 this module will use “regid” contact param (if present) when saving REGISTER request even if REGISTER request does not indicate support for outbound.

Default value is 0.

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

If set to 0 then this module will not add a “Flow-Timer:” header to 200 OK responses to REGISTER requests.

If set to > 0 then this module will add a “Flow-Timer:” header containing this value to 200 OK responses to REGISTER requests. This parameter may only be set to a value > 0 when outbound_mode is set to 1 or 2.

When set to a value greater than 0 this parameter should be set to slightly less than the connection timeout value between the UAC and the network (this corresponds to the core tcp_connection_lifetime option and websocket keepalive_timeout modparam). This parameter is most useful when you have a single edge proxy/registrar or if you have an edge proxy that cannot modify responses. If you are using a separate edge proxy you should consider leaving this parameter set to 0 and adding the “Flow-Timer:” header on the edge proxy as this allows you to keep all of the timer values for a specific flow in one configuration.

Default value is 0.

...
modparam("registrar", "flow_timer", 25)
...

The function processes a REGISTER message. It can add, remove or modify location records (in usrloc) 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 the location database. On an error, an error message will be sent with a short description in reason phrase.

Meaning of the parameters is as follows:

Return codes:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and REPLY_ROUTE.

...
save("location");
save("location", "0x01");
save("location", "0x00", "sip:test@kamailio.org");
...

The lookup function extracts username and/or domain 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 and request is initial request without to-tag, the lookup function will return only the contacts that support the method of the processed request.

Meaning of the parameters is as follows:

Return codes:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

The function performs lookup(domain) on r-uri and additional branches (only branches that have no other attributes set than uri).

Meaning of the parameters is as follows:

Return codes are propagated from the lookup(domain) function.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

...
lookup_branches("location");
...

The function returns true if the AOR in the 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 nor append branches. If uri parameter is not provided, then it considered to be the Request-URI for SIP requests and To-URI for SIP replies.

Meaning of the parameters is as follows:

This function can be used from ANY_ROUTE.

...
if (registered("location")) {
	sl_send_reply("100", "Trying");
	...
};
...
$xavp(regcfg=>match_received) = $su;
if (registered("location","$rz:$Au", 2)) {
	sl_send_reply("100", "Trying");
	...
};
...

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

This makes sense only in multiple replicated servers scenarios.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE.

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

The function removes contacts associated with 'uri' from the location database. If 'ruid' is provided a specific contact is removed, if 'ruid' is not provided all the current contacts are removed. If 'ruid' is provided and the “usrloc” module is using “db_mode=3”, 'uri' does not need to be given and can be empty string.

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

...
unregister("location", "$ru");
unregister("location", "sip:user@kamailio.org");
unregister("location", "$ru", "$ulc(caller=>ruid)");
unregister("location", "", "$ruid");
...

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

Meaning of the parameters is as follows:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

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:

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

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

Executed when a contact in location table has expired. The variable $ulc(exp=>...) is filled with the attributes of the expired contact.

...
event_route[usrloc:contact-expired] {
    xlog("expired contact for $ulc(exp=>aor)\n");
}
...

Value of max_expires parameter.

The value of max_contacts parameter.

The value of default_expires parameter.

Number of accepted registrations.

Number of rejected registrations.

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:

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

...
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;
  }
}
...