<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;
]>
<!-- Module User's Guide -->
<chapter>
  <title>&adminguide;</title>

  <section>
    <title>Overview</title>

    <para>The module contains record routing logic.</para>
  </section>

  <section id="RR-dialog-id">
    <title>Dialog support</title>

    <para>&kamailio; is basically <emphasis>only</emphasis> a transaction
    stateful proxy, without any dialog support build in. There are many
    features/services which actually require a 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 module offers the following functions:</para>

    <itemizedlist>
      <listitem>
        <para>add_rr_param() - see <xref linkend="rr.f.add_rr_param"/></para>
      </listitem>

      <listitem>
        <para>check_route_param() - see <xref
        linkend="rr.f.check_route_param"/></para>
      </listitem>
    </itemizedlist>

    <example>
      <title>Dialog support in RR module</title>

      <programlisting format="linespecific">
...
UAC                       &kamailio; 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>
    <title>Dependencies</title>

    <section>
      <title>&kamailio; Modules</title>

      <para>The following modules must be loaded before this module:
      <itemizedlist>
          <listitem>
            <para>(optional) The "outbound" module is needed for outbound
            routing as per RFC 5626.</para>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <title>External Libraries or Applications</title>

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

  <section>
    <title>Parameters</title>

    <section id="rr.p.enable_full_lr">
      <title><varname>enable_full_lr</varname> (integer)</title>

      <para>If set to 1 then <quote>;lr=on</quote> instead of just
      <quote>;lr</quote> will be used. This is to overcome problems with
      broken &ua;s which strip <quote>;lr</quote> parameter when generating
      Route header fields from Record-Route (<quote>;lr=on</quote> seems to
      help).</para>

      <para><emphasis> Default value is 0 (no). </emphasis></para>

      <example>
        <title>Set <varname>enable_full_lr</varname> parameter</title>

        <programlisting format="linespecific">
...
modparam("rr", "enable_full_lr", 1)
...
</programlisting>
      </example>
    </section>

    <section id="rr.p.append_fromtag_id">
      <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="rr.p.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-&gt;TCP. This parameter enables inserting of 2 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></para>

      <example>
        <title>Set <varname>enable_double_rr</varname> parameter</title>

        <programlisting format="linespecific">
...
modparam("rr", "enable_double_rr", 0)
...
</programlisting>
      </example>
      <para>Some useragents (e. g. Linphone) incorrectly use UDP transport for
      subsequent requests in dialog, despite being configured to use another
      SIP transport protocol. This can be worked around by setting Record-Route
      header with explicit transport attribute. But enable_double_rr enabled in
      default mode omits transport attribute from being added to header if it
      detects that both sender and receiver use same protocol (e. g. TCP or
      TLS), and this results in UDP being used by such broken clients. Set
      enable_double_rr to value 2 to always have two RR headers with transport
      attributes explicitly set.</para>

      <example>
        <title>Set <varname>enable_double_rr</varname> to 2 to always have two explicit RR headers</title>

        <programlisting format="linespecific">
...
modparam("rr", "enable_double_rr", 2)
...
</programlisting>
      </example>
    </section>

    <section id="rr.p.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>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></para>

      <example>
        <title>Set <varname>add_username</varname> parameter</title>

        <programlisting format="linespecific">
...
modparam("rr", "add_username", 1)
...
</programlisting>
      </example>
    </section>

    <section id="rr.p.enable_socket_warning">
      <title><varname>enable_socket_mismatch_warning</varname>
      (integer)</title>

      <para>When a preset record-route header is forced in &kamailio; 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 &kamailio; 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 id="rr.p.custom_user_avp">
      <title><varname>custom_user_avp</varname> (avp string)</title>

      <para>When add_username is enabled, a call to record_route will add
      the username of the RequestURI to the Record-Route URI. This parameter
      allows you to setup an AVP with which you can customise the username to
      be added in the Record-Route URI.</para>

      <para><emphasis> Default value: if not set, the std add_username
      behaviour is used - i.e. Request URI username. </emphasis></para>

      <example>
        <title><varname>custom_user_avp</varname> usage</title>

        <programlisting format="linespecific">
...
modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")

#usage in cfg file
$avp(RR_CUSTOM_USER_AVP)="mo";
record_route();
...
</programlisting>
      </example>
    </section>
    <section id="rr.p.force_send_socket">
      <title><varname>force_send_socket</varname> (int)</title>

	  <para>
	  	  If set to 1, local socket is forced even for single Record-Route,
		  otherwise is done on double Record-Route (should that be enabled).
	  </para>

	  <para>
	  	  When use of <quote>outbound</quote> is enabled, the socket is not
		  forced.
	  </para>

      <para><emphasis>Default value is 0.</emphasis></para>

      <example>
        <title>Set <varname>force_send_socket</varname> parameter</title>

        <programlisting format="linespecific">
...
modparam("rr", "force_send_socket", 1)
...
</programlisting>
      </example>
    </section>
    <section id="rr.p.ignore_sips">
      <title><varname>ignore_sips</varname> (int)</title>

	  <para>
		  If set to 1, the Record-Route header are build with 'sip' schema
		  always, ignoring the presence of 'sips' schema in request URI.
	  </para>

      <para><emphasis>Default value is 0 (use 'sips' if present in R-URI).</emphasis></para>

      <example>
        <title>Set <varname>ignore_sips</varname> parameter</title>

        <programlisting format="linespecific">
...
modparam("rr", "ignore_sips", 1)
...
</programlisting>
      </example>
    </section>
	<section id="rr.p.sockname_mode">
		<title><varname>sockname_mode</varname> (int)</title>
		<para>
		If set to 1, the Record-Route URI is built to contain socket name in 'sn'
		parameter and then it is used to lookup the local socket for Route header
		processing.
		</para>
		<para>
		<emphasis>
			Default value is 0.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sockname_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("rr", "sockname_mode", 1)
...
</programlisting>
		</example>
	</section>
  </section>

  <section>
    <title>Functions</title>

    <section id="rr.f.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 with normal lookup functions. If a Route: header
      is found, the function returns 1 and behaves as described in section
      16.12 of RFC 3261. There is only one exception: If the request is
      out-of-dialog (no to-tag) and there is only one Route: header indicating
      the local proxy, then the Route: header is removed and 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.  If route
      calculation based on flow-token succeeds, function returns TRUE even
      if there is only one Route: header indicating the local proxy.</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>Return codes:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>1</emphasis> - route calculation has been
          successful</para>
        </listitem>

        <listitem>
          <para><emphasis>2</emphasis> - route calculation based on
          flow-token has been successful</para>
        </listitem>

        <listitem>
          <para><emphasis>-1</emphasis> - route calculation has been
          unsuccessful</para>
        </listitem>

        <listitem>
          <para><emphasis>-2</emphasis> - outbound flow-token shows evidence
          of tampering</para>
        </listitem>

        <listitem>
          <para><emphasis>-3</emphasis> - next hop is taken from
          a preloaded route set</para>
        </listitem>
      </itemizedlist>

      <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="rr.f.loose_route_preloaded">
      <title><function moreinfo="none">loose_route_preloaded()</function></title>

	  <para>The function is similar to `loose_route()`, but it returns 1 (true)
	  when the Route header is preloaded (is in an initial request) and -1
	  (false) if processing of the Route header failed or it is for requests
	  within dialog.</para>
      <para>It is a convenient function to use for routing initial requests on
      an edge proxy that adds Path header to REGISTER requests.
      </para>
      <para>This function can be used from REQUEST_ROUTE.</para>

      <example>
        <title><function>loose_route_preloaded</function> usage</title>

        <programlisting format="linespecific">
...
if(!loose_route_preloaded()) {
   sl_send_reply("404" "Preloaded route expected");
   exit;
}
...
</programlisting>
      </example>
    </section>

	<section id="rr.f.loose_route_mode">
      <title><function moreinfo="none">loose_route_mode(vmode)</function></title>

	  <para>The function is similar to `loose_route()`, but it does only
	  loose routing processing if vmode==1, skipping the testing of r-uri==myself
	  for performing strict routing. If vmode==0, it behaves like loose_route().
      </para>
      <para>It is a convenient function to use with application servers that
      set the Contact URI to SIP server address.
      </para>
      <para>This function can be used from REQUEST_ROUTE.</para>

      <example>
        <title><function>loose_route_mode</function> usage</title>

        <programlisting format="linespecific">
...
if(has_totag() and uri==myself) {
    if(loose_route_mode("1")) {
        rewritehostport("my.app.server:5090");
        t_relay();
        exit;
    }
}
...
</programlisting>
      </example>
    </section>

    <section id="rr.f.record_route">
      <title><function moreinfo="none">record_route([sparams])</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 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>Note: if append From-tag is enabled and the function is used for requests
      within dialog, it must be executed after loose_route() in order to detect
      properly the direction.</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="rr.f.remove_record_route">
		<title><function moreinfo="none">remove_record_route()</function></title>

		<para>The function removes the internal lumps added by
			record_route() functions.
		</para>

		<para>
			Can be used to revert adding Record-Route header(s).
		</para>
		<para>
			This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>

      <example>
        <title><function>remove_record_route</function> usage</title>

        <programlisting format="linespecific">
...
remove_record_route();
...
</programlisting>
      </example>
    </section>

    <section id="rr.f.record_route_preset">
      <title><function moreinfo="none">record_route_preset(string
      [,string2])</function></title>

      <para>This function will put the string params into Record-Route, avoid
      to use it 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> - String to be inserted into the
          second header field; it may contain pseudo-variables.</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>Note: The value of parameters must not contain the SIP protocol
	  scheme (sip: or sips:), one is added based on routing requirements. Thus
	  the value has to be like "address:port;parameters", the port and
	  parameters are optional. If the second parameter is provided, do not
	  forget to add the parameter "r2=on" so the proxy processes both
	  corresponding Route headers at once.</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>

      <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="rr.f.record_route_adv_addr">
      <title><function
      moreinfo="none">record_route_advertised_address(address)</function></title>

      <para>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.</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>
          <para><emphasis>address</emphasis> - Advertised address to use in
          the header; it may contain pseudo-variables.</para>
        </listitem>
      </itemizedlist>

      <para>If double record-routing is enabled two Record-Route headers will
      be inserted with the same given address with different transports if the
      transport changes.</para>

      <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
      FAILURE_ROUTE.</para>

      <example>
        <title><function>record_route_advertised_address</function>
        usage</title>

        <programlisting format="linespecific">
...
record_route_advertised_address("1.2.3.4:5080");
...
</programlisting>
      </example>
    </section>

    <section  id="rr.f.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(),
      record_route_advertised_address(), and record_route_preset()
      calls (see <xref linkend="rr.f.record_route"/> or <xref
      linkend="rr.f.record_route_adv_addr"/>)).</para>

      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>param</emphasis> - String containing the URI
          parameter to be added. It must follow the <quote>;name=value</quote>
          scheme; it may contain pseudo-variables.</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="rr.f.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 called after loose_route() (see <xref
      linkend="rr.f.loose_route"/>).</para>

      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>re</emphasis> - 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="rr.f.is_direction">
      <title><function moreinfo="none">is_direction(dir)</function></title>

      <para>The function checks the flow direction of in-dialog requests. This
      function uses the <quote>ftag</quote> parameter from the Route header,
      therefore the append_fromtag (see <xref linkend="rr.p.append_fromtag"/>
      module parameter must be enabled. Also this must be called only after
      loose_route() (see <xref linkend="rr.f.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> direction means that the request is
      in the same direction as the initial request that created the
      dialog.</para>

      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>dir</emphasis> - string containing the direction to
          be checked. It may be <quote>upstream</quote> (from callee to
          caller) or <quote>downstream</quote> (caller to callee).</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("downstream")) {
    xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
} else {
    xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
}
...
</programlisting>
      </example>
    </section>

    <section id="rr.f.rr_next_hop_route">
		<title><function moreinfo="none">rr_next_hop_route()</function></title>

		<para>The function returns 1 (true) if there is a Route header for the
			next hop address. It has to be used after loose_route(), when the
			local Route headers are processed.
		</para>

		<para>
			This function can be used from ANY_ROUTE.
		</para>

      <example>
        <title><function>rr_next_hop_route</function> usage</title>

        <programlisting format="linespecific">
...
if(loose_route) {
    if(rr_next_hop_route()) {
        # next hop address is from Route header
    }

}
...
</programlisting>
      </example>
  </section>

  </section>

  <section>
    <title>Exported Pseudo Variables</title>

    <section>
      <title><function moreinfo="none">$route_uri</function></title>

      <para>Returns the URI of the top route-header.</para>

      <example>
        <title>$route_uri</title>

        <programlisting format="linespecific">
...
    xdbg("Route-URI is: $route_uri\n");
...
		</programlisting>
      </example>
    </section>
  </section>
</chapter>
