<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>The module contains record routing logic</para>
	</section>


	<section id="RR-dialog-id">
	<title>Dialog support</title>
	<para>&osips; is basically <emphasis>only</emphasis> 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.
	</para>
	<para>
	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.
	</para>
	<para>
	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).
	</para>
	<para>
	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).
	</para>
	<para>
	For this purpose, the modules offers the following functions:
	</para>
	<itemizedlist>
		<listitem>
			<para>add_rr_param() - see <xref linkend="func_add_rr_param"/>
			</para>
		</listitem>
		<listitem>
			<para>check_route_param() - see 
				<xref linkend="func_check_route_param"/>
			</para>
		</listitem>
	</itemizedlist>
	<example>
		<title>Dialog support in RR module</title>
		<programlisting format="linespecific">
  
UAC                       OpenSIPS PROXY                          UAS

---- INVITE ------&gt;       record_route()          ----- INVITE ----&gt;
                     add_rr_param(";foo=true")

--- reINVITE -----&gt;        loose_route()          ---- reINVITE ---&gt;
                    check_route_param(";foo=true")

&lt;-- reINVITE ------        loose_route()          &lt;--- reINVITE ----
                    check_route_param(";foo=true")

&lt;------ BYE -------        loose_route()          &lt;----- BYE -------
                    check_route_param(";foo=true")
  
</programlisting>
		</example>
	</section>


	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &osips; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_append_fromtag" xreflabel="append_fromtag">
		<title><varname>append_fromtag</varname> (integer)</title>
		<para>
		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)
		</para>
		<para>
		<emphasis>
			Default value is 1 (yes).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>append_fromtag</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rr", "append_fromtag", 0)
...
</programlisting>
		</example>
	</section>

	<section id="param_enable_double_rr" xreflabel="enable_double_rr">
		<title><varname>enable_double_rr</varname> (integer)</title>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is 1 (yes).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>enable_double_rr</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rr", "enable_double_rr", 0)
...
</programlisting>
		</example>
	</section>

	<section id="param_add_username" xreflabel="add_username">
		<title><varname>add_username</varname> (integer)</title>
		<para>
		If set to a non 0 value (which means yes), the username part will
		be also added in the Record-Route URI.
		</para>
		<para>
		<emphasis>
			Default value is 0 (no).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>add_username</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rr", "add_username", 1)
...
</programlisting>
		</example>
	</section>

	<section id="param_enable_socket_mismatch_warning" xreflabel="enable_socket_mismatch_warning">
		<title><varname>enable_socket_mismatch_warning</varname> (integer)</title>
		<para>
		When a preset record-route header is forced in &osips; 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 &osips; is behind a NATed firewall, we don't want this warning
		to be printed for every bridged call.
		</para>
		<para>
		<emphasis>
			Default value is 1 (yes).
		</emphasis>
		</para>
		<example>
		<title><varname>enable_socket_mismatch_warning</varname> usage</title>
		<programlisting format="linespecific">
...
modparam("rr", "enable_socket_mismatch_warning", 0)
...
</programlisting>
		</example>
	</section>
	</section>


	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_loose_route" xreflabel="loose_route()">
		<title>
		<function moreinfo="none">loose_route()</function>
		</title>
		<para>
		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 <quote>strict router</quote> format.
		</para>
		<para>
		This function is usually used to route in-dialog requests (like ACK, 
		BYE, reINVITE). Nevertheless also out-of-dialog requests can have a 
		<quote>pre-loaded route set</quote> and my be routed with loose_route. 
		It also takes care of translating between strict-routers and 
		loose-router.
		</para>
		<para>
		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.
		</para>
		<para>
		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).
		</para>
		<para>
		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.
		</para>
		<para>
		Make sure your loose_routing function can't be used by attackers to 
		bypass proxy authorization.
		</para>
		<para>
		The loose_routing topic is very complex. See the RFC3261 for more 
		details (grep for <quote>route set</quote> is a good starting point in 
		this comprehensive RFC).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>loose_route</function> usage</title>
		<programlisting format="linespecific">
...
loose_route();
...
</programlisting>
		</example>
	</section>

	<section id="func_record_route" xreflabel="record_route()">
		<title>
		<function moreinfo="none">record_route()</function> and 
		<function moreinfo="none">record_route(string)</function>
		</title>
		<para>
		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.
		</para>
		<para>
		If any string is passed as parameter, it will be appended as URI
		parameter to the Record-Route header. The string must follow the 
		<quote>;name=value</quote> scheme.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
		FAILURE_ROUTE.
		</para>
		<example>
		<title><function>record_route</function> usage</title>
		<programlisting format="linespecific">
...
record_route();
...
</programlisting>
		</example>
	</section>

	<section id="func_record_route_preset" xreflabel="record_route_preset()">
		<title>
		<function moreinfo="none">record_route_preset(string [, string2])</function>
		</title>
		<para>
		This function will put the string into Record-Route, don't use 
		unless you know what you are doing.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>string</emphasis> - String to be inserted into the 
				first header field; it may contain pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>string2</emphasis> (optional) - String to be inserted into the 
				second header field.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		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.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
		FAILURE_ROUTE.
		</para>
		<example>
		<title><function>record_route_preset</function> usage</title>
		<programlisting format="linespecific">
...
record_route_preset("1.2.3.4:5090");
...
</programlisting>
		</example>
	</section>

	<section id="func_add_rr_param" xreflabel="add_rr_param()">
		<title>
		<function moreinfo="none">add_rr_param(param)</function>
		</title>
		<para>
		Adds a parameter to the Record-Route URI (param must be in 
		<quote>;name=value</quote> format. The function may be called also 
		before or after the record_route() call 
		(see <xref linkend="func_record_route"/>).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>param</emphasis> (string) - the URI parameter to
			be added. It must follow the <quote>;name=value</quote> scheme.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and 
		FAILURE_ROUTE.
		</para>
		<example>
		<title><function>add_rr_param</function> usage</title>
		<programlisting format="linespecific">
...
add_rr_param(";nat=yes");
...
</programlisting>
		</example>
	</section>

	<section id="func_check_route_param" xreflabel="check_route_param()">
		<title>
		<function moreinfo="none">check_route_param(re)</function>
		</title>
		<para>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 <xref linkend="func_loose_route"/>).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>re</emphasis> (string) - regular expression to check against the
			Route URI parameters.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>check_route_param</function> usage</title>
		<programlisting format="linespecific">
...
if (check_route_param("nat=yes")) {
    setflag(6);
}
...
</programlisting>
		</example>
	</section>

	<section id="func_is_direction" xreflabel="is_direction()">
		<title>
		<function moreinfo="none">is_direction(dir)</function>
		</title>
		<para>The function checks the flow direction of the request.
		As for checking it's used the <quote>ftag</quote> Route header 
		parameter, the append_fromtag (see <xref linkend="param_append_fromtag"/> 
		module parameter must be enabled. Also this must be called only after 
		loose_route() (see <xref linkend="func_loose_route"/>).
		</para>
		<para>
		The function returns true if the <quote>dir</quote> is the same with
		the request's flow direction.
		</para>
		<para>
		The <quote>downstream</quote> (UAC to UAS) direction is relative to the
		initial request that created the dialog.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>dir</emphasis> (string) - the direction to be 
				checked. It may be <quote>upstream</quote> (from UAS to UAC) or 
				<quote>downstream</quote> (UAC to UAS).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function>is_direction</function> usage</title>
		<programlisting format="linespecific">
...
if (is_direction("upstream")) {
    xdbg("upstream request ($rm)\n");
}
...
</programlisting>
		</example>
	</section>

	<section id="exported_pseudo_variables">
		<title>Exported Pseudo-Variables</title>
		<para>
		Exported pseudo-variables are listed in the next sections.
		</para>
		<section id="pv_rr_params" xreflabel="$rr_params">
		<title>$rr_params</title>
			<para>
			<emphasis>$rr_params</emphasis> - the whole string of the Route
			parameters - this is available only after calling loose_route()
			</para>
		</section>
	</section>

</section>
</chapter>

