Kamailio is basically only a transaction statefull proxy, without any dialog support build in. There are many features/services which actually requires a dialog awareness, like storing the information in the dialog creation stage, information which will be used during the whole dialog existence.

The most urging example is NAT traversal, in dealing with the within the dialog INVITEs (re-INVITEs). When processing the initial INVITE, the proxy detects if the caller or callee is behind some NAT and fixes the signalling and media parts - since not all the detection mechanism are available for within the dialog requests (like usrloc), to be able to fix correspondingly the sequential requests, the proxy must remember that the original request was NAT processed. There are many other cases where dialog awareness fixes or helps.

The solution is to store additional dialog-related information in the routing set (Record-Route/Route headers), headers which show up in all sequential requests. So any information added to the Record-Route header will be found (with no direction dependencies) in Route header (corresponding to the proxy address).

As storage container, the parameters of the Record-Route / Route header will be used - Record-Route parameters mirroring are reinforced by RFC 3261 (see 12.1.1 UAS behavior).

For this purpose, the modules offers the following functions:

add_rr_param() - see Section 5.5, “add_rr_param(param)”
check_route_param() - see Section 5.6, “check_route_param(re)”

Example 1.1. Dialog support in RR module

  
UAC                       Kamailio PROXY                          UAS

---- INVITE ------>       record_route()          ----- INVITE ---->
                     add_rr_param(";foo=true")

--- reINVITE ----->        loose_route()          ---- reINVITE --->
                    check_route_param(";foo=true")

<-- reINVITE ------        loose_route()          <--- reINVITE ----
                    check_route_param(";foo=true")

<------ BYE -------        loose_route()          <----- BYE -------
                    check_route_param(";foo=true")

3. Dependencies

3.1. Kamailio Modules

The following modules must be loaded before this module:

(optional) The "outbound" module is needed for outbound routing as per RFC 5626.

3.2. External Libraries or Applications

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

None.

4. Parameters

4.1. `enable_full_lr` (integer)

If set to 1 then “;lr=on” instead of just “;lr” will be used. This is to overcome problems with broken UAs which strip “;lr” parameter when generating Route header fields from Record-Route (“;lr=on” seems to help).

Default value is 0 (no).

Example 1.2. Set enable_full_lr parameter

...
modparam("rr", "enable_full_lr", 1)
...

4.2. `append_fromtag` (integer)

If turned on, request's from-tag is appended to record-route; that's useful for understanding whether subsequent requests (such as BYE) come from caller (route's from-tag==BYE's from-tag) or callee (route's from-tag==BYE's to-tag)

Default value is 1 (yes).

Example 1.3. Set append_fromtag parameter

...
modparam("rr", "append_fromtag", 0)
...

4.3. `enable_double_rr` (integer)

There are some situations when the server needs to insert two Record-Route header fields instead of one. For example when using two disconnected networks or doing cross-protocol forwarding from UDP->TCP. This parameter enables inserting of 2 Record-Routes. The server will later remove both of them.

Double record-routing does not occur when outbound is used for a request.

Default value is 1 (yes).

Example 1.4. Set enable_double_rr parameter

...
modparam("rr", "enable_double_rr", 0)
...

4.4. `add_username` (integer)

If set to a non 0 value (which means yes), the username part will be also added in the Record-Route URI.

This option cannot be set when the “outbound” module is loaded before this module as outbound uses the username part of Record-Route URIs to store flow-tokens.

Default value is 0 (no).

Example 1.5. Set add_username parameter

...
modparam("rr", "add_username", 1)
...

4.5. `enable_socket_mismatch_warning` (integer)

When a preset record-route header is forced in Kamailio config and the host from the record-route header is not the same as the host server, a warning will be printed out in the logs. The 'enable_socket_mismatch_warning' parameter enables or disables the warning. When Kamailio is behind a NATed firewall, we don't want this warning to be printed for every bridged call.

Default value is 1 (yes).

Example 1.6. enable_socket_mismatch_warning usage

...
modparam("rr", "enable_socket_mismatch_warning", 0)
...

4.6. `custom_user_avp` (avp string)

When enable_username is enabled, a call to record_route will add the username of the RequestURI to the Record-Route URI. This parameter allows you to setup an AVP with which you can customise the username to be added in the Record-Route URI.

Default value: if not set, the std add_username behaviour is used - i.e. Request URI username.

Example 1.7. custom_user_avp usage

...
modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")

#usage in cfg file
$avp(RR_CUSTOM_USER_AVP)="mo";
record_route();

...

5. Functions

5.1. `loose_route()`

The function performs routing of SIP requests which contain a route set. The name is a little bit confusing, as this function also routes requests which are in the “strict router” format.

This function is usually used to route in-dialog requests (like ACK, BYE, reINVITE). Nevertheless also out-of-dialog requests can have a “pre-loaded route set” and my be routed with loose_route. It also takes care of translating between strict-routers and loose-router.

The loose_route function analyzes the Route: headers in the requests. If there is no Route: header, the function returns FALSE and routing should be done with normal lookup functions. If a Route: header is found, the function returns 1 and behaves as described in section 16.12 of RFC 3261. There is only one exception: If the request is out-of-dialog (no to-tag) and there is only one Route: header indicating the local proxy, then the Route: header is removed and the function returns FALSE.

When the “outbound” module was loaded before this module and the Route: header contains a username part this function will attempt to use the username part as a flow-token for routing.

Make sure your loose_routing function can't be used by attackers to bypass proxy authorization.

The loose_routing topic is very complex. See the RFC3261 for more details (grep for “route set” is a good starting point in this comprehensive RFC).

Return codes:

1 - route calculation has been successful
-1 - route calculation has been unsuccessful
-2 - outbound flow-token shows evidence of tampering

This function can be used from REQUEST_ROUTE.

Example 1.8. loose_route usage

...
loose_route();
...

5.2. `record_route()` and `record_route(string)`

The function adds a new Record-Route header field. The header field will be inserted in the message before any other Record-Route header fields.

If any string is passed as parameter, it will be appended as URI parameter to the Record-Route header. The string must follow the “;name=value” scheme and it may contain pseudo-variables.

When the “outbound” module was loaded before this module this function will determine whether outbound is required for the request and generate and add a flow-token as the username part of the Record-Route-URI.

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

Example 1.9. record_route usage

...
record_route();
...

5.3. `record_route_preset(string [,string2])`

This function will put the string into Record-Route, don't use unless you know what you are doing.

Meaning of the parameters is as follows:

string - String to be inserted into the first header field; it may contain pseudo-variables.
string2 - String to be inserted into the second header field; it may contain pseudo-variables.

Note: If 'string2' is present, then the 'string' param is pointing to the outbound interface and the 'string2' param is pointing to the inbound interface.

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

Example 1.10. record_route_preset usage

...
record_route_preset("1.2.3.4:5090");
...

5.4. `record_route_advertised_address(address)`

The function adds a new Record-Route header field using the address given. The header field will be inserted in the message before any other Record-Route header fields.

Meaning of the parameter is as follows:

address - Advertised address to use in the header; it may contain pseudo-variables.

If double record-routing is enabled two Record-Route headers will be inserted with the same given address with different transports if the transport changes.

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

Example 1.11. record_route_advertised_address usage

...
record_route_advertised_address("1.2.3.4:5080");
...

5.5. `add_rr_param(param)`

Adds a parameter to the Record-Route URI (param must be in “;name=value” format. The function may be called also before or after the record_route() or record_route_advertised_address() calls (see Section 5.2, “record_route() and record_route(string)” or Section 5.4, “record_route_advertised_address(address)”)).

Meaning of the parameters is as follows:

param - String containing the URI parameter to be added. It must follow the “;name=value” scheme; it may contain pseudo-variables.

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

Example 1.12. add_rr_param usage

...
add_rr_param(";nat=yes");
...

5.6. `check_route_param(re)`

The function checks if the URI parameters of the local Route header (corresponding to the local server) matches the given regular expression. It must be call after loose_route() (see Section 5.1, “loose_route()”).

Meaning of the parameters is as follows:

re - regular expression to check against the Route URI parameters.

This function can be used from REQUEST_ROUTE.

Example 1.13. check_route_param usage

...
if (check_route_param("nat=yes")) {
    setflag(6);
}
...

5.7. `is_direction(dir)`

The function checks the flow direction of in-dialog requests. This function uses the “ftag” prameter from the Route header, therefore the append_fromtag (see Section 4.2, “append_fromtag (integer)” module parameter must be enabled. Also this must be called only after loose_route() (see Section 5.1, “loose_route()”).

The function returns true if the “dir” is the same with the request's flow direction.

The “downstream” direction means that the request is in the same direction as the initial request that created the dialog.

Meaning of the parameters is as follows:

dir - string containing the direction to be checked. It may be “upstream” (from callee to caller) or “downstream” (caller to callee).

This function can be used from REQUEST_ROUTE.

Example 1.14. is_direction usage

...
if (is_direction("downstream")) {
    xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
} else {
    xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
}
...

6. Exported Pseudo Variables

6.1. `$route_uri`

Returns the URI of the top route-header.

Example 1.15. $route_uri

...
    xdbg("Route-URI is: $route_uri\n");
...

Chapter 2. Developer Guide

Table of Contents

1. Available Functions

1.1. record_route(string)
1.2. record_route_advertised_address(string)
1.3. add_rr_param( msg, param)
1.4. check_route_param( msg, re)
1.5. is_direction( msg, dir)
1.6. get_route_param( msg, name, val)
1.7. register_rrcb( callback, param)

2. Examples

The RR module provides an internal API to be used by other Kamailio modules. The API offers support for SIP dialog based functionalities - for more about the dialog support offered by RR module, see Section 2, “Dialog support”.

For internal(non-script) usage, the RR module offers to other module the possibility to register callback functions to be executed each time a local Route header is processed. The callback function will receive as parameter the register parameter and the Route header parameter string.

1. Available Functions

1.1. `record_route(string)`

The function adds a new Record-Route header field. The header field will be inserted in the message before any other Record-Route header fields.

If any string is passed as parameter, it will be appended as URI parameter to the Record-Route header. The string must follow the “;name=value” scheme and it may contain pseudo-variables.

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

Example 2.1. record_route usage

...
record_route();
...

1.2. `record_route_advertised_address(string)`

This function will add the string into a new Record-Route header field. Don't use unless you know what you are doing. The header field will be inserted in the message before any other Record-Route header fields.

Meaning of the parameters is as follows:

string - String to be inserted into the header field.

Calls to add_rr_param() will add parameters to the Record-Route header. Note: A second Record-Route will be inserted if the transport used on the inbound and outbound interfaces changes.

Example 2.2. record_route_advertised_address usage

...
record_route_advertised_address("1.2.3.4:5090");
...

1.3. `add_rr_param( msg, param)`

Adds a parameter to the requests's Record-Route URI (param must be in “;name=value” format).

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

struct sip_msg* msg - request that will has the parameter “param” added to its Record-Route header.
str* param - parameter to be added to the Record-Route header - it must be in “;name=value” format.

1.4. `check_route_param( msg, re)`

The function checks for the request “msg” if the URI parameters of the local Route header (corresponding to the local server) matches the given regular expression “re”. It must be call after the loose_route was done.

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

struct sip_msg* msg - request that will has the Route header parameters checked.
regex_t* param - compiled regular expression to be checked against the Route header parameters.

1.5. `is_direction( msg, dir)`

The function checks the flow direction of the request “msg”. As for checking it's used the “ftag” Route header parameter, the append_fromtag (see Section 4.2, “append_fromtag (integer)” module parameter must be enables. Also this must be call only after the loose_route is done.

The function returns 0 if the “dir” is the same with the request's flow direction. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

struct sip_msg* msg - request that will have the direction checked.
int dir - direction to be checked against. It may be “RR_FLOW_UPSTREAM” or “RR_FLOW_DOWNSTREAM”.

1.6. `get_route_param( msg, name, val)`

The function search in to the “msg”'s Route header parameters the parameter called “name” and returns its value into “val”. It must be call only after the loose_route is done.

The function returns 0 if parameter was found (even if it has no value). Otherwise, -1 is returned.

Meaning of the parameters is as follows:

struct sip_msg* msg - request that will have the Route header parameter searched.
str *name - contains the Route header parameter to be serached.
str *val - returns the value of the searched Route header parameter if found. It might be empty string if the parameter had no value.

1.7. `register_rrcb( callback, param)`

The function register a new callback (along with its parameter). The callback will be called when a loose route will be performed for the local address.

The function returns 0 on success. Otherwise, -1 is returned.

Meaning of the parameters is as follows:

rr_cb_t callback - callback function to be registered.
void *param - parameter to be passed to the callback function.

2. Examples

Example 2.3. Loading RR module's API from another module

...
#include "../rr/api.h"
...
struct rr_binds my_rrb;
...
...
/* load the RR API */
if (load_rr_api( &my_rrb )!=0) {
    LM_ERR("can't load RR API\n");
    goto error;
}
...
...
/* register a RR callback */
if (my_rrb.register_rrcb(my_callback,0))!=0) {
    LM_ERR("can't register RR callback\n");
    goto error;
}
...

rr Module

Jan Janak

Bogdan-Andrei Iancu

Carsten Bock

Edited by

Jan Janak

Edited by

Bogdan-Andrei Iancu

Chapter 1. Admin Guide

1. Overview

2. Dialog support

3. Dependencies

3.1. Kamailio Modules

3.2. External Libraries or Applications

4. Parameters

4.1. enable_full_lr (integer)

4.2. append_fromtag (integer)

4.3. enable_double_rr (integer)

4.4. add_username (integer)

4.5. enable_socket_mismatch_warning (integer)

4.6. custom_user_avp (avp string)

5. Functions

5.1. loose_route()

5.2. record_route() and record_route(string)

5.3. record_route_preset(string [,string2])

5.4. record_route_advertised_address(address)

5.5. add_rr_param(param)

5.6. check_route_param(re)

5.7. is_direction(dir)

6. Exported Pseudo Variables

6.1. $route_uri

Chapter 2. Developer Guide

1. Available Functions

1.1. record_route(string)

1.2. record_route_advertised_address(string)

1.3. add_rr_param( msg, param)

1.4. check_route_param( msg, re)

1.5. is_direction( msg, dir)

1.6. get_route_param( msg, name, val)

1.7. register_rrcb( callback, param)

2. Examples

4.1. `enable_full_lr` (integer)

4.2. `append_fromtag` (integer)

4.3. `enable_double_rr` (integer)

4.4. `add_username` (integer)

4.5. `enable_socket_mismatch_warning` (integer)

4.6. `custom_user_avp` (avp string)

5.1. `loose_route()`

5.2. `record_route()` and `record_route(string)`

5.3. `record_route_preset(string [,string2])`

5.4. `record_route_advertised_address(address)`

5.5. `add_rr_param(param)`

5.6. `check_route_param(re)`

5.7. `is_direction(dir)`

6.1. `$route_uri`

1.1. `record_route(string)`

1.2. `record_route_advertised_address(string)`

1.3. `add_rr_param( msg, param)`

1.4. `check_route_param( msg, re)`

1.5. `is_direction( msg, dir)`

1.6. `get_route_param( msg, name, val)`

1.7. `register_rrcb( callback, param)`