rr Module

Jan Janak

   FhG FOKUS

Bogdan-Andrei Iancu

   Voice Sistem SRL

Carsten Bock

   ng-voice.com

Edited by

Jan Janak

Bogdan-Andrei Iancu

   Copyright © 2003 FhG FOKUS

   Copyright © 2005 Voice Sistem SRL

   Copyright © 2011 Carsten Bock, carsten@ng-voice.com
     __________________________________________________________________

   Table of Contents

   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)
              4.7. force_send_socket (int)
              4.8. ignore_sips (int)
              4.9. sockname_mode (int)
              4.10. loose_route_mode (int)

        5. Functions

              5.1. loose_route()
              5.2. loose_route_preloaded()
              5.3. loose_route_mode(vmode)
              5.4. record_route([sparams])
              5.5. remove_record_route()
              5.6. record_route_preset(string [,string2])
              5.7. record_route_advertised_address(address)
              5.8. add_rr_param(param)
              5.9. check_route_param(re)
              5.10. is_direction(dir)
              5.11. rr_next_hop_route()

        6. Exported Pseudo Variables

              6.1. $route_uri

   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

   List of Examples

   1.1. Dialog support in RR module
   1.2. Set enable_full_lr parameter
   1.3. Set append_fromtag parameter
   1.4. Set enable_double_rr parameter
   1.5. Set enable_double_rr to 2 to always have two explicit RR headers
   1.6. Set add_username parameter
   1.7. enable_socket_mismatch_warning usage
   1.8. custom_user_avp usage
   1.9. Set force_send_socket parameter
   1.10. Set ignore_sips parameter
   1.11. Set sockname_mode parameter
   1.12. Set loose_route_mode parameter
   1.13. loose_route usage
   1.14. loose_route_preloaded usage
   1.15. loose_route_mode usage
   1.16. record_route usage
   1.17. remove_record_route usage
   1.18. record_route_preset usage
   1.19. record_route_advertised_address usage
   1.20. add_rr_param usage
   1.21. check_route_param usage
   1.22. is_direction usage
   1.23. rr_next_hop_route usage
   1.24. $route_uri
   2.1. record_route usage
   2.2. record_route_advertised_address usage
   2.3. Loading RR module's API from another module

Chapter 1. Admin Guide

   Table of Contents

   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)
        4.7. force_send_socket (int)
        4.8. ignore_sips (int)
        4.9. sockname_mode (int)
        4.10. loose_route_mode (int)

   5. Functions

        5.1. loose_route()
        5.2. loose_route_preloaded()
        5.3. loose_route_mode(vmode)
        5.4. record_route([sparams])
        5.5. remove_record_route()
        5.6. record_route_preset(string [,string2])
        5.7. record_route_advertised_address(address)
        5.8. add_rr_param(param)
        5.9. check_route_param(re)
        5.10. is_direction(dir)
        5.11. rr_next_hop_route()

   6. Exported Pseudo Variables

        6.1. $route_uri

1. Overview

   The module contains record routing logic.

2. Dialog support

   Kamailio is basically only a transaction stateful proxy, without any
   dialog support build in. There are many features/services which
   actually require 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 module offers the following functions:
     * add_rr_param() - see Section 5.8, “add_rr_param(param)”
     * check_route_param() - see Section 5.9, “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
   3.2. External Libraries or Applications

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)
   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)
   4.7. force_send_socket (int)
   4.8. ignore_sips (int)
   4.9. sockname_mode (int)
   4.10. loose_route_mode (int)

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

   Some useragents (e. g. Linphone) incorrectly use UDP transport for
   subsequent requests in dialog, despite being configured to use another
   SIP transport protocol. This can be worked around by setting
   Record-Route header with explicit transport attribute. But
   enable_double_rr enabled in default mode omits transport attribute from
   being added to header if it detects that both sender and receiver use
   same protocol (e. g. TCP or TLS), and this results in UDP being used by
   such broken clients. Set enable_double_rr to value 2 to always have two
   RR headers with transport attributes explicitly set.

   Example 1.5. Set enable_double_rr to 2 to always have two explicit RR
   headers
...
modparam("rr", "enable_double_rr", 2)
...

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.6. 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.7. enable_socket_mismatch_warning usage
...
modparam("rr", "enable_socket_mismatch_warning", 0)
...

4.6. custom_user_avp (avp string)

   When add_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 set up 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.8. 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();
...

4.7. force_send_socket (int)

   If set to 1, local socket is forced even for single Record-Route,
   otherwise is done on double Record-Route (should that be enabled).

   When use of “outbound” is enabled, the socket is not forced.

   Default value is 0.

   Example 1.9. Set force_send_socket parameter
...
modparam("rr", "force_send_socket", 1)
...

4.8. ignore_sips (int)

   If set to 1, the Record-Route header are build with 'sip' schema
   always, ignoring the presence of 'sips' schema in request URI.

   Default value is 0 (use 'sips' if present in R-URI).

   Example 1.10. Set ignore_sips parameter
...
modparam("rr", "ignore_sips", 1)
...

4.9. sockname_mode (int)

   If set to 1, the Record-Route URI is built to contain socket name in
   'sn' parameter and then it is used to lookup the local socket for Route
   header processing.

   Default value is 0.

   Example 1.11. Set sockname_mode parameter
...
modparam("rr", "sockname_mode", 1)
...

4.10. loose_route_mode (int)

   Controls the behaviour of loose_route() in the same manner as the value
   of the parameter for for function loose_route_mode(val), in a global
   manner.

   Default value is 0.

   Example 1.12. Set loose_route_mode parameter
...
modparam("rr", "loose_route_mode", 1)
...

5. Functions

   5.1. loose_route()
   5.2. loose_route_preloaded()
   5.3. loose_route_mode(vmode)
   5.4. record_route([sparams])
   5.5. remove_record_route()
   5.6. record_route_preset(string [,string2])
   5.7. record_route_advertised_address(address)
   5.8. add_rr_param(param)
   5.9. check_route_param(re)
   5.10. is_direction(dir)
   5.11. rr_next_hop_route()

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. If route calculation based
   on flow-token succeeds, function returns TRUE even if there is only one
   Route: header indicating the local proxy.

   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
     * 2 - route calculation based on flow-token has been successful
     * -1 - route calculation has been unsuccessful
     * -2 - outbound flow-token shows evidence of tampering
     * -3 - next hop is taken from a preloaded route set

   This function can be used from REQUEST_ROUTE.

   Example 1.13. loose_route usage
...
loose_route();
...

5.2. loose_route_preloaded()

   The function is similar to `loose_route()`, but it returns 1 (true)
   when the Route header is preloaded (is in an initial request) and -1
   (false) if processing of the Route header failed or it is for requests
   within dialog.

   It is a convenient function to use for routing initial requests on an
   edge proxy that adds Path header to REGISTER requests.

   This function can be used from REQUEST_ROUTE.

   Example 1.14. loose_route_preloaded usage
...
if(!loose_route_preloaded()) {
   sl_send_reply("404" "Preloaded route expected");
   exit;
}
...

5.3. loose_route_mode(vmode)

   The function is similar to `loose_route()`, but it accepts route mode
   bitmask as vmode parameter.

   If bit one is set, then do only loose routing processing, skipping the
   testing of r-uri==myself for performing strict routing. If not, behave
   like loose_route(). If bit two is set, then skip flow tokens
   processing.

   First bit is convenient to use with application servers that set the
   Contact URI to SIP server address.

   This function can be used from REQUEST_ROUTE.

   Example 1.15. loose_route_mode usage
...
if(has_totag() and uri==myself) {
    if(loose_route_mode("1")) {
        rewritehostport("my.app.server:5090");
        t_relay();
        exit;
    }
}
...

5.4. record_route([sparams])

   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.

   Note: if append From-tag is enabled and the function is used for
   requests within dialog, it must be executed after loose_route() in
   order to detect properly the direction.

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

   Example 1.16. record_route usage
...
record_route();
...

5.5. remove_record_route()

   The function removes the internal lumps added by record_route()
   functions.

   Can be used to revert adding Record-Route header(s).

   This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.

   Example 1.17. remove_record_route usage
...
remove_record_route();
...

5.6. record_route_preset(string [,string2])

   This function will put the string params into Record-Route, avoid to
   use it 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.

   Note: The value of parameters must not contain the SIP protocol scheme
   (sip: or sips:), one is added based on routing requirements. Thus the
   value has to be like "address:port;parameters", the port and parameters
   are optional. If the second parameter is provided, do not forget to add
   the parameter "r2=on" so the proxy processes both corresponding Route
   headers at once.

   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.18. record_route_preset usage
...
record_route_preset("1.2.3.4:5090");
...

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

   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.

   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.19. record_route_advertised_address usage
...
record_route_advertised_address("1.2.3.4:5080");
...

5.8. 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(), record_route_advertised_address(), and
   record_route_preset() calls (see Section 5.4, “record_route([sparams])”
   or Section 5.7, “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.20. add_rr_param usage
...
add_rr_param(";nat=yes");
...

5.9. 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 called 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.21. check_route_param usage
...
if (check_route_param("nat=yes")) {
    setflag(6);
}
...

5.10. is_direction(dir)

   The function checks the flow direction of in-dialog requests. This
   function uses the “ftag” parameter from the Route header, therefore the
   append_fromtag (see ??? 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.22. 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");
}
...

5.11. rr_next_hop_route()

   The function returns 1 (true) if there is a Route header for the next
   hop address. It has to be used after loose_route(), when the local
   Route headers are processed.

   This function can be used from ANY_ROUTE.

   Example 1.23. rr_next_hop_route usage
...
if(loose_route) {
    if(rr_next_hop_route()) {
        # next hop address is from Route header
    }

}
...

6. Exported Pseudo Variables

   6.1. $route_uri

6.1. $route_uri

   Returns the URI of the top route-header.

   Example 1.24. $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)
   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)

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' 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 called 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 ??? module parameter must be enables. Also this
   must be called 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 searches in the “msg”'s Route header parameters the
   parameter called “name” and returns its value into “val”. It must be
   called 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 searched.
     * 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 registers 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;
}
...
