kamailio/modules_k/rr

rr Module

Jan Janak

   FhG FOKUS

Bogdan-Andrei Iancu

   Voice Sistem SRL

Carsten Bock

   ng-voice.com

Edited by

Jan Janak

Edited by

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)

        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

   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 add_username parameter
   1.6. enable_socket_mismatch_warning usage
   1.7. loose_route usage
   1.8. record_route usage
   1.9. record_route_preset usage
   1.10. record_route_advertised_address usage
   1.11. add_rr_param usage
   1.12. check_route_param usage
   1.13. is_direction usage
   1.14. $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)

   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

1. Overview

   The module contains record routing logic

2. Dialog support

   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
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * No dependencies on other Kamailio modules.

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

   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.

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

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) 

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.

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

   This function can be used from REQUEST_ROUTE.

   Example 1.7. 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.

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

   Example 1.8. 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.9. 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.10. 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.11. 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.12. 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.13. 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

6.1. $route_uri

   Returns the URI of the top route-header.

   Example 1.14. $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'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;
}
...