rr: docs - note about use of record_route() for requests within dialog
[sip-router] / src / modules / rr / doc / rr_admin.xml
index d8b9ce7..362edd4 100644 (file)
@@ -19,7 +19,7 @@
     <title>Dialog support</title>
 
     <para>&kamailio; is basically <emphasis>only</emphasis> a transaction
-    statefull proxy, without any dialog support build in. There are many
+    stateful proxy, without any dialog support build in. There are many
     features/services which actually requires a dialog awareness, like storing
     the information in the dialog creation stage, information which will be
     used during the whole dialog existence.</para>
@@ -109,7 +109,7 @@ UAC                       &kamailio; PROXY                          UAS
   <section>
     <title>Parameters</title>
 
-    <section>
+    <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
@@ -131,7 +131,7 @@ modparam("rr", "enable_full_lr", 1)
       </example>
     </section>
 
-    <section id="append-fromtag-id">
+    <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;
@@ -152,7 +152,7 @@ modparam("rr", "append_fromtag", 0)
       </example>
     </section>
 
-    <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
@@ -183,7 +183,7 @@ modparam("rr", "enable_double_rr", 0)
       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 expicitly set.</para>
+      attributes explicitly set.</para>
 
       <example>
         <title>Set <varname>enable_double_rr</varname> to 2 to always have two explicit RR headers</title>
@@ -196,7 +196,7 @@ modparam("rr", "enable_double_rr", 2)
       </example>
     </section>
 
-    <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
@@ -219,7 +219,7 @@ modparam("rr", "add_username", 1)
       </example>
     </section>
 
-    <section>
+    <section id="rr.p.enable_socket_warning">
       <title><varname>enable_socket_mismatch_warning</varname>
       (integer)</title>
 
@@ -243,7 +243,7 @@ modparam("rr", "enable_socket_mismatch_warning", 0)
       </example>
     </section>
 
-    <section>
+    <section id="rr.p.custom_user_avp">
       <title><varname>custom_user_avp</varname> (avp string)</title>
 
       <para>When enable_username is enabled, a call to record_route will add
@@ -293,12 +293,32 @@ 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>
 
   <section>
     <title>Functions</title>
 
-    <section id="loose-route-id">
+    <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
@@ -344,7 +364,7 @@ modparam("rr", "force_send_socket", 1)
 
         <listitem>
           <para><emphasis>2</emphasis> - route calculation based on
-         flow-token has been successful</para>
+          flow-token has been successful</para>
         </listitem>
 
         <listitem>
@@ -356,6 +376,11 @@ modparam("rr", "force_send_socket", 1)
           <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>
@@ -371,9 +396,8 @@ loose_route();
       </example>
     </section>
 
-    <section id="record-route-id">
-      <title><function moreinfo="none">record_route()</function> and <function
-      moreinfo="none">record_route(string)</function></title>
+    <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
@@ -389,6 +413,10 @@ loose_route();
       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>
 
@@ -403,7 +431,7 @@ record_route();
       </example>
     </section>
 
-    <section id="remove-record-route-id">
+    <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
@@ -428,7 +456,7 @@ remove_record_route();
       </example>
     </section>
 
-    <section>
+    <section id="rr.f.record_route_preset">
       <title><function moreinfo="none">record_route_preset(string
       [,string2])</function></title>
 
@@ -472,7 +500,7 @@ record_route_preset("1.2.3.4:5090");
       </example>
     </section>
 
-    <section id="record-route-adv-addr-id">
+    <section id="rr.f.record_route_adv_addr">
       <title><function
       moreinfo="none">record_route_advertised_address(address)</function></title>
 
@@ -513,7 +541,7 @@ record_route_advertised_address("1.2.3.4:5080");
       </example>
     </section>
 
-    <section id="add-rr-param-id">
+    <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
@@ -546,7 +574,7 @@ add_rr_param(";nat=yes");
       </example>
     </section>
 
-    <section id="check-route-param-id">
+    <section id="rr.f.check_route_param">
       <title><function
       moreinfo="none">check_route_param(re)</function></title>
 
@@ -579,11 +607,11 @@ if (check_route_param("nat=yes")) {
       </example>
     </section>
 
-    <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> prameter from the Route header,
+      function uses the <quote>ftag</quote> parameter from the Route header,
       therefore the append_fromtag (see <xref linkend="append-fromtag-id"/>
       module parameter must be enabled. Also this must be called only after
       loose_route() (see <xref linkend="loose-route-id"/>).</para>