modules_k/rr: updated documentation for outbound support

modules_k/rr/README

@@ -20,11 +20,11 @@ Edited by
 
 Bogdan-Andrei Iancu
 
-   Copyright © 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
 
-   Copyright © 2005 Voice Sistem SRL
+   Copyright © 2005 Voice Sistem SRL
 
-   Copyright © 2011 Carsten Bock, [email protected]
+   Copyright © 2011 Carsten Bock, [email protected]
      __________________________________________________________________
 
    Table of Contents
@@ -159,8 +159,8 @@ Chapter 1. Admin Guide
    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) "
+     * 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
@@ -185,7 +185,8 @@ UAC                       Kamailio PROXY                          UAS
 3.1. Kamailio Modules
 
    The following modules must be loaded before this module:
-     * No dependencies on other Kamailio modules.
+     * (optional) The "outbound" module is needed for outbound routing as
+       per RFC 5626.
 
 3.2. External Libraries or Applications
 
@@ -203,9 +204,9 @@ UAC                       Kamailio PROXY                          UAS
 
 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
+   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).
@@ -237,6 +238,9 @@ modparam("rr", "append_fromtag", 0)
    This parameter enables inserting of 2 Record-Routes. The server will
    later remove both of them.
 
+   Double record-routing does not occur when outbound is used for a
+   request.
+
    Default value is 1 (yes).
 
    Example 1.4. Set enable_double_rr parameter
@@ -249,6 +253,10 @@ modparam("rr", "enable_double_rr", 0)
    If set to a non 0 value (which means yes), the username part will be
    also added in the Record-Route URI.
 
+   This option cannot be set when the “outbound� module is loaded before
+   this module as outbound uses the username part of Record-Route URIs to
+   store flow-tokens.
+
    Default value is 0 (no).
 
    Example 1.5. Set add_username parameter
@@ -282,15 +290,15 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
    5.6. check_route_param(re)
    5.7. is_direction(dir)
 
-5.1. loose_route()
+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.
+   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
+   “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.
@@ -302,11 +310,15 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
    indicating the local proxy, then the Route: header is removed and the
    function returns FALSE.
 
+   When the “outbound� module was loaded before this module and the Route:
+   header contains a username part this function will attempt to use the
+   username part as a flow-token for routing.
+
    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
+   details (grep for “route set� is a good starting point in this
    comprehensive RFC).
 
    This function can be used from REQUEST_ROUTE.
@@ -316,7 +328,7 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
 loose_route();
 ...
 
-5.2. record_route() and record_route(string)
+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
@@ -324,7 +336,12 @@ loose_route();
 
    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.
+   “;name=value� scheme and it may contain pseudo-variables.
+
+   When the “outbound� module was loaded before this module this function
+   will determine whether outbound is required for the request and
+   generate and add a flow-token as the username part of the
+   Record-Route-URI.
 
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
@@ -334,7 +351,7 @@ loose_route();
 record_route();
 ...
 
-5.3. record_route_preset(string [,string2])
+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.
@@ -349,6 +366,11 @@ record_route();
    the outbound interface and the 'string2' param is pointing to the
    inbound interface.
 
+   When the “outbound� module was loaded before this module this function
+   will determine whether outbound is required for the request and
+   generate and add a flow-token as the username part of the
+   Record-Route-URI.
+
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
 
@@ -357,12 +379,17 @@ record_route();
 record_route_preset("1.2.3.4:5090");
 ...
 
-5.4. record_route_advertised_address(address)
+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.
 
+   When the “outbound� module was loaded before this module this function
+   will determine whether outbound is required for the request and
+   generate and add a flow-token as the username part of the
+   Record-Route-URI.
+
    Meaning of the parameter is as follows:
      * address - Advertised address to use in the header; it may contain
        pseudo-variables.
@@ -379,17 +406,17 @@ record_route_preset("1.2.3.4:5090");
 record_route_advertised_address("1.2.3.4:5080");
 ...
 
-5.5. add_rr_param(param)
+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
+   “;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) ")).
+   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.
+       follow the “;name=value� scheme; it may contain pseudo-variables.
 
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
@@ -399,12 +426,12 @@ record_route_advertised_address("1.2.3.4:5080");
 add_rr_param(";nat=yes");
 ...
 
-5.6. check_route_param(re)
+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() ").
+   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.
@@ -418,23 +445,23 @@ if (check_route_param("nat=yes")) {
 }
 ...
 
-5.7. is_direction(dir)
+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
+   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() ").
+   loose_route() (see Section 5.1, “ loose_route() �).
 
-   The function returns true if the "dir" is the same with the request's
+   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
+   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
+       “upstream� (from callee to caller) or “downstream� (caller to
        callee).
 
    This function can be used from REQUEST_ROUTE.
@@ -480,7 +507,7 @@ Chapter 2. Developer Guide
    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".
+   “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
@@ -498,7 +525,7 @@ Chapter 2. Developer Guide
    1.6. get_route_param( msg, name, val)
    1.7. register_rrcb( callback, param)
 
-1.1. record_route(string)
+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
@@ -506,7 +533,7 @@ Chapter 2. Developer Guide
 
    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.
+   “;name=value� scheme and it may contain pseudo-variables.
 
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
    FAILURE_ROUTE.
@@ -516,7 +543,7 @@ Chapter 2. Developer Guide
 record_route();
 ...
 
-1.2. record_route_advertised_address(string)
+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
@@ -534,24 +561,24 @@ record_route();
 record_route_advertised_address("1.2.3.4:5090");
 ...
 
-1.3. add_rr_param( msg, param)
+1.3.  add_rr_param( msg, param)
 
    Adds a parameter to the requests's Record-Route URI (param must be in
-   ";name=value" format).
+   “;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"
+     * 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.
+       must be in “;name=value� format.
 
-1.4. check_route_param( msg, re)
+1.4.  check_route_param( msg, re)
 
-   The function checks for the request "msg" if the URI parameters of the
+   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
+   given regular expression “re�. It must be call after the loose_route
    was done.
 
    The function returns 0 on success. Otherwise, -1 is returned.
@@ -562,26 +589,26 @@ record_route_advertised_address("1.2.3.4:5090");
      * regex_t* param - compiled regular expression to be checked against
        the Route header parameters.
 
-1.5. is_direction( msg, dir)
+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
+   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
+   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".
+       “RR_FLOW_UPSTREAM� or “RR_FLOW_DOWNSTREAM�.
 
-1.6. get_route_param( msg, name, val)
+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
+   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
@@ -594,7 +621,7 @@ record_route_advertised_address("1.2.3.4:5090");
      * 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)
+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

modules_k/rr/doc/rr_admin.xml

@@ -95,7 +95,7 @@ UAC                       &kamailio; PROXY                          UAS
 			<itemizedlist>
 			<listitem>
 			<para>
-				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
+				(optional) The "outbound" module is needed for outbound routing as per RFC 5626.
 			</para>
 			</listitem>
 			</itemizedlist>
@@ -178,6 +178,10 @@ modparam("rr", "append_fromtag", 0)
 		Record-Routes. The server will later remove both of them.
 		</para>
 		<para>
+		Double record-routing does not occur when outbound is used for
+		a request.
+		</para>
+		<para>
 		<emphasis>
 			Default value is 1 (yes).
 		</emphasis>
@@ -199,6 +203,11 @@ modparam("rr", "enable_double_rr", 0)
 		be also added in the Record-Route URI.
 		</para>
 		<para>
+		This option cannot be set when the <quote>outbound</quote>
+		module is loaded before this module as outbound uses the
+		username part of Record-Route URIs to store flow-tokens.
+		</para>
+		<para>
 		<emphasis>
 			Default value is 0 (no).
 		</emphasis>
@@ -269,6 +278,11 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
 		the function returns FALSE.
 		</para>
 		<para>
+		When the <quote>outbound</quote> module was loaded before this module
+		and the Route: header contains a username part this function will
+		attempt to use the username part as a flow-token for routing.
+		</para>
+		<para>
 		Make sure your loose_routing function can't be used by attackers to 
 		bypass proxy authorization.
 		</para>
@@ -306,6 +320,12 @@ loose_route();
 		<quote>;name=value</quote> scheme and it may contain pseudo-variables.
 		</para>
 		<para>
+		When the <quote>outbound</quote> module was loaded before this module
+		this function will determine whether outbound is required for the
+		request and generate and add a flow-token as the username part of the
+		Record-Route-URI.
+		</para>
+		<para>
 		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
 		FAILURE_ROUTE.
 		</para>
@@ -347,6 +367,12 @@ record_route();
 		outbound interface and the 'string2' param is pointing to the inbound interface.
 		</para>
 		<para>
+		When the <quote>outbound</quote> module was loaded before this module
+		this function will determine whether outbound is required for the
+		request and generate and add a flow-token as the username part of the
+		Record-Route-URI.
+		</para>
+		<para>
 		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
 		FAILURE_ROUTE.
 		</para>
@@ -369,6 +395,12 @@ record_route_preset("1.2.3.4:5090");
 		header field will be inserted in the message before any other Record-Route header
 		fields.
 		</para>
+		<para>
+		When the <quote>outbound</quote> module was loaded before this module
+		this function will determine whether outbound is required for the
+		request and generate and add a flow-token as the username part of the
+		Record-Route-URI.
+		</para>
 		<para>Meaning of the parameter is as follows:</para>
 		<itemizedlist>
 		<listitem>