Table of Contents
List of Tables
List of Examples
append_fromtag parameterenable_double_rr parameteradd_username parameterenable_socket_mismatch_warning usageloose_route usagerecord_route usagerecord_route_preset usageadd_rr_param usagecheck_route_param usageis_direction usageOpenSIPS 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()
check_route_param() - see check_route_param()
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")
The following modules must be loaded before this module:
No dependencies on other OpenSIPS modules.
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).
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).
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).
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).
Example 1.5. enable_socket_mismatch_warning usage
...
modparam("rr", "enable_socket_mismatch_warning", 0)
...
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.
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.
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.
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()).
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.
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()).
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.
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 module parameter must be enabled. Also this must be called only after loose_route() (see 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.
Example 1.11. is_direction usage
...
if (is_direction("upstream")) {
xdbg("upstream request ($rm)\n");
}
...
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.
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.
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.
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 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”.
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.
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.
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))!=0) {
LM_ERR("can't register RR callback\n");
goto error;
}
...
3.1. | 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. | |
3.2. | Where can I find more about OpenSIPS? |
Take a look at https://opensips.org/. | |
3.3. | 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
If you want to keep the mail private, send it to
| |
3.4. | How can I report a bug? |
Please follow the guidelines provided at: https://github.com/OpenSIPS/opensips/issues. |
Table 4.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
| Name | DevScore | Commits | Lines ++ | Lines -- | |
|---|---|---|---|---|---|
| 1. | Jan Janak (@janakj) | 141 | 59 | 4374 | 2763 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | 95 | 65 | 1915 | 843 |
| 3. | Liviu Chircu (@liviuchircu) | 19 | 16 | 72 | 105 |
| 4. | Daniel-Constantin Mierla (@miconda) | 18 | 14 | 244 | 92 |
| 5. | Vlad Paiu (@vladpaiu) | 15 | 10 | 333 | 88 |
| 6. | Jiri Kuthan (@jiriatipteldotorg) | 15 | 10 | 250 | 64 |
| 7. | Razvan Crainea (@razvancrainea) | 14 | 12 | 83 | 47 |
| 8. | Andrei Pelinescu-Onciul | 12 | 9 | 61 | 92 |
| 9. | Anca Vamanu | 9 | 3 | 191 | 206 |
| 10. | Henning Westerholt (@henningw) | 7 | 4 | 115 | 73 |
All remaining contributors: Vlad Patrascu (@rvlad-patrascu), Ovidiu Sas (@ovidiusas), Dan Pascu (@danpascu), Konstantin Bokarius, Saúl Ibarra Corretgé (@saghul), Jesus Rodrigues, Julián Moreno Patiño, Norman Brandinger (@NormB), Peter Lemenkov (@lemenkov), Edson Gellert Schubert, Elena-Ramona Modroiu.
(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated files
Table 4.2. Most recently active contributors(1) to this module
| Name | Commit Activity | |
|---|---|---|
| 1. | Liviu Chircu (@liviuchircu) | Oct 2013 - May 2024 |
| 2. | Bogdan-Andrei Iancu (@bogdan-iancu) | Jan 2002 - Nov 2022 |
| 3. | Razvan Crainea (@razvancrainea) | Aug 2010 - Sep 2019 |
| 4. | Vlad Patrascu (@rvlad-patrascu) | May 2017 - Apr 2019 |
| 5. | Peter Lemenkov (@lemenkov) | Jun 2018 - Jun 2018 |
| 6. | Julián Moreno Patiño | Feb 2016 - Feb 2016 |
| 7. | Ovidiu Sas (@ovidiusas) | Oct 2010 - Jan 2015 |
| 8. | Norman Brandinger (@NormB) | Sep 2014 - Sep 2014 |
| 9. | Saúl Ibarra Corretgé (@saghul) | Mar 2012 - Mar 2012 |
| 10. | Vlad Paiu (@vladpaiu) | Nov 2010 - Aug 2011 |
All remaining contributors: Anca Vamanu, Dan Pascu (@danpascu), Henning Westerholt (@henningw), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Jesus Rodrigues, Elena-Ramona Modroiu, Jan Janak (@janakj), Andrei Pelinescu-Onciul, Jiri Kuthan (@jiriatipteldotorg).
(1) including any documentation-related commits, excluding merge commits
Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov (@lemenkov), Liviu Chircu (@liviuchircu), Razvan Crainea (@razvancrainea), Vlad Paiu (@vladpaiu), Ovidiu Sas (@ovidiusas), Dan Pascu (@danpascu), Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson Gellert Schubert, Elena-Ramona Modroiu, Jan Janak (@janakj).
Documentation Copyrights:
Copyright © 2005 Voice Sistem SRL
Copyright © 2003 FhG FOKUS