---
title: "rr Module"
description: "The module contains record routing logic"
---

## Admin Guide


### Overview


The module contains record routing logic


### Dialog support


OpenSIPS is basically *only* a transaction statefull 
	proxy, without any dialog support build in. There are many features/services
	which actually require 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 [add rr param](#func_add_rr_param)
- check_route_param() - see 
				[check route param](#func_check_route_param)


```c title="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")
  
```


### Dependencies


#### OpenSIPS Modules


The following modules must be loaded before this module:


- *No dependencies on other OpenSIPS modules*.


#### External Libraries or Applications


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


- *None*.


### Exported Parameters


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


```c title="Set append_fromtag parameter"
...
modparam("rr", "append_fromtag", 0)
...
```


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


```c title="Set enable_double_rr parameter"
...
modparam("rr", "enable_double_rr", 0)
...
```


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


```c title="Set add_username parameter"
...
modparam("rr", "add_username", 1)
...
```


#### enable_socket_mismatch_warning (integer)


When a preset record-route header is forced in OpenSIPS 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 OpenSIPS is behind a NATed firewall, we don't want this warning
		to be printed for every bridged call.


*Default value is 1 (yes).*


```c title="enable_socket_mismatch_warning usage"
...
modparam("rr", "enable_socket_mismatch_warning", 0)
...
```


### Exported Functions


#### 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 exclusivly via RURI. If a Route header is 
		found, the function returns TRUE and behaves as described in section 
		16.12 of RFC 3261. The only exception is for requests with preload
		Route headers (intial requests, carrying a Route header): if there is 
		only one Route header indicating the local proxy, then the Route 
		header is removed and the function returns FALSE.


The function is able to automatically detecting if it deals with a
		'strict' or 'loose' routing scenario (the difference is how the SIP
		path is stored across the RURI and Route hdrs). To make the difference
		between the two scenarios OpenSIPS has to determine which SIP URI
		holds its address/domain - the RURI (then it is a strict routing
		scenario) or the top Route URI (then it is a loose route scenario).
		In order to check if the SIP URI holds its address/domain, OpenSIPS 
		checks the host URI against the listening IPs/interfaces (as a static
		component) and the domains listed from the "domain" module/table (as 
		the dynamic component).


If there is a Route header but other parsing errors occur ( like
		parsing the TO header to get the TAG ), the function also 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.


```c title="loose_route usage"
...
loose_route();
...
```


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


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


```c title="record_route usage"
...
record_route();
...
```


#### 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* (optional) - String to be inserted into the 
				second header field.


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.


```c title="record_route_preset usage"
...
record_route_preset("1.2.3.4:5090");
...
```


#### 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 [record route](#func_record_route)).


Meaning of the parameters is as follows:


- *param* (string) - the URI parameter to
			be added. It must follow the ";name=value" scheme.


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


```c title="add_rr_param usage"
...
add_rr_param(";nat=yes");
...
```


#### 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 [loose route](#func_loose_route)).


Meaning of the parameters is as follows:


- *re* (string) - regular expression to check against the
			Route URI parameters.


This function can be used from REQUEST_ROUTE.


```c title="check_route_param usage"
...
if (check_route_param("nat=yes")) {
    setflag(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 [append fromtag](#param_append_fromtag) 
		module parameter must be enabled. Also this must be called only after 
		loose_route() (see [loose route](#func_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) - 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.


```c title="is_direction usage"
...
if (is_direction("upstream")) {
    xdbg("upstream request ($rm)\n");
}
...
```


#### Exported Pseudo-Variables


Exported pseudo-variables are listed in the next sections.


##### $rr_params


*$rr_params* - the whole string of the Route
			parameters - this is available only after calling loose_route()


## 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 [RR dialog id](#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.


### Available Functions


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


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


#### 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 
		[append fromtag](#param_append_fromtag) 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".


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


#### register_rrcb( callback, param, prior)


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.
- *short prior* - parameter to set the priority. 
				If the callback depends on another module, this parameter should be greater
				than that module's priority. Otherwise, it should be 0.


### Examples


```c title="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))!=0) {
    LM_ERR("can't register RR callback\n");
    goto error;
}
...
```


## Frequently Asked Questions


**Q: What happened with old enable_full_lr parameter**


The parameter is considered obsolete. It was only introduced to
			allow compatibility with older SIP entities, that complained
			about a lr parameter without a value. 
			This behavior breaks RFC 3261, and since nowadays most SIP stacks
			are fixed to conform with the RFC, the parameter was removed.


**Q: Where can I find more about OpenSIPS?**


Take a look at [https://opensips.org/](https://opensips.org/).


**Q: Where can I post a question about this module?**


First at all check if your question was already answered on one of
			our mailing lists:

E-mails regarding any stable OpenSIPS release should be sent to 
			users@lists.opensips.org and e-mails regarding development versions
			should be sent to devel@lists.opensips.org.

If you want to keep the mail private, send it to 
			users@lists.opensips.org.


**Q: How can I report a bug?**


Please follow the guidelines provided at:
			[https://github.com/OpenSIPS/opensips/issues](https://github.com/OpenSIPS/opensips/issues).
<!-- CONTRIBUTORS -->

### License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0
