rr Module
     __________________________________________________________

   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. append_fromtag (integer)
              1.4.2. enable_double_rr (integer)
              1.4.3. add_username (integer)
              1.4.4. enable_socket_mismatch_warning (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 [, string2])
              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, prior)

        2.2. Examples

   3. Frequently Asked Questions
   4. Contributors

        4.1. By Commit Statistics
        4.2. By Commit Activity

   5. Documentation

        5.1. Contributors

   List of Tables

   4.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   4.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Dialog support in RR module
   1.2. Set append_fromtag parameter
   1.3. Set enable_double_rr parameter
   1.4. Set add_username parameter
   1.5. enable_socket_mismatch_warning usage
   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 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")


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. 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.2. Set append_fromtag parameter
...
modparam("rr", "append_fromtag", 0)
...

1.4.2. 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.3. Set enable_double_rr parameter
...
modparam("rr", "enable_double_rr", 0)
...

1.4.3. 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.4. Set add_username parameter
...
modparam("rr", "add_username", 1)
...

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

   Example 1.5. enable_socket_mismatch_warning usage
...
modparam("rr", "enable_socket_mismatch_warning", 0)
...

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

   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.

   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.

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

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

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

   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 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");
}
...

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

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

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

Chapter 3. Frequently Asked Questions

   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 http://www.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:
         * User Mailing List -
           http://lists.opensips.org/cgi-bin/mailman/listinfo/users
         * Developer Mailing List -
           http://lists.opensips.org/cgi-bin/mailman/listinfo/devel

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

   3.4.

       How can I report a bug?

       Please follow the guidelines provided at:
       https://github.com/OpenSIPS/opensips/issues.

Chapter 4. Contributors

4.1. By Commit Statistics

   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) 144 59 4374 2763
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 92 62 1898 838
   3. Daniel-Constantin Mierla (@miconda) 18 14 244 92
   4. Liviu Chircu (@liviuchircu) 16 13 62 99
   5. Vlad Paiu (@vladpaiu) 15 10 333 88
   6. Jiri Kuthan (@jiriatipteldotorg) 14 10 250 64
   7. Andrei Pelinescu-Onciul 12 9 61 92
   8. Razvan Crainea (@razvancrainea) 10 8 79 44
   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

4.2. By Commit Activity

   Table 4.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2002 - May 2019
   2.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   3.  Liviu Chircu (@liviuchircu)         Oct 2013 - Feb 2019
   4.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   5.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   6.  Razvan Crainea (@razvancrainea)     Aug 2010 - Oct 2015
   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

Chapter 5. Documentation

5.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Razvan Crainea
   (@razvancrainea), Bogdan-Andrei Iancu (@bogdan-iancu), 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
