rr Module
Jan Janak
FhG FOKUS
Bogdan-Andrei Iancu
voice-system.ro
Edited by
Jan Janak
Edited by
Bogdan-Andrei Iancu
Copyright © 2003 FhG FOKUS
Copyright © 2005 voice-system.ro
Revision History
Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300
(Tue, 21 Jul 2009) $
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Dialog support
1.3. Dependencies
1.3.1. OpenSIPS Modules
1.3.2. External Libraries or Applications
1.4. Exported Parameters
1.4.1. enable_full_lr (integer)
1.4.2. append_fromtag (integer)
1.4.3. enable_double_rr (integer)
1.4.4. add_username (integer)
1.5. Exported Functions
1.5.1. loose_route()
1.5.2. record_route() and record_route(string)
1.5.3. record_route_preset(string)
1.5.4. add_rr_param(param)
1.5.5. check_route_param(re)
1.5.6. is_direction(dir)
1.5.7. Exported pseudo-variables
2. Developer Guide
2.1. Available Functions
2.1.1. add_rr_param( msg, param)
2.1.2. check_route_param( msg, re)
2.1.3. is_direction( msg, dir)
2.1.4. get_route_param( msg, name, val)
2.1.5. register_rrcb( callback, param)
2.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. loose_route usage
1.7. record_route usage
1.8. record_route_preset usage
1.9. add_rr_param usage
1.10. check_route_param usage
1.11. is_direction usage
2.1. Loading RR module's API from another module
Chapter 1. Admin Guide
1.1. Overview
The module contains record routing logic
1.2. Dialog support
OpenSIPS 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 1.5.4, " add_rr_param(param) "
* check_route_param() - see Section 1.5.5, "
check_route_param(re) "
Example 1.1. Dialog support in RR module
UAC OpenSIPS 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")
1.3. Dependencies
1.3.1. OpenSIPS Modules
The following modules must be loaded before this module:
* No dependencies on other OpenSIPS modules.
1.3.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* None.
1.4. Exported Parameters
1.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)
...
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)
...
1.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)
...
1.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)
...
1.5. Exported Functions
1.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.6. loose_route usage
...
loose_route();
...
1.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.7. record_route usage
...
record_route();
...
1.5.3. record_route_preset(string)
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 header field; it
may contain pseudo-variables.
This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
FAILURE_ROUTE.
Example 1.8. record_route_preset usage
...
record_route_preset("1.2.3.4:5090");
...
1.5.4. 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() call (see Section 1.5.2, "
record_route() and record_route(string) ").
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.9. add_rr_param usage
...
add_rr_param(";nat=yes");
...
1.5.5. 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 1.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.10. check_route_param usage
...
if (check_route_param("nat=yes")) {
setflag(6);
}
...
1.5.6. is_direction(dir)
The function checks the flow direction of the request. As for
checking it's used the "ftag" Route header parameter, the
append_fromtag (see Section 1.4.2, "append_fromtag (integer)"
module parameter must be enabled. Also this must be called only
after loose_route() (see Section 1.5.1, " loose_route() ").
The function returns true if the "dir" is the same with the
request's flow direction.
The "downstream" (UAC to UAS) direction is relative to 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 UAS to UAC) or "downstream" (UAC to
UAS).
This function can be used from REQUEST_ROUTE.
Example 1.11. is_direction usage
...
if (is_direction("upstream")) {
xdbg("upstream request ($rm)\n");
}
...
1.5.7. Exported pseudo-variables
Exported pseudo-variables are listed in the next sections.
1.5.7.1. $rr_params
$rr_params - the whole string of the Route paramters - this is
available only after calling loose_route()
Chapter 2. Developer Guide
The RR module provides an internal API to be used by other
OpenSIPS modules. The API offers support for SIP dialog based
functionalities - for more about the dialog support offered by
RR module, see Section 1.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.
2.1. Available Functions
2.1.1. 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.
2.1.2. 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.
2.1.3. 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 1.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".
2.1.4. 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.
2.1.5. 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.2. Examples
Example 2.1. 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;
}
...
