Merge pull request #1424 from kamailio/eschmidbauer/pua_json
[sip-router] / src / modules / rr / doc / rr_admin.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4 <!-- Include general documentation entities -->
5 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
6 %docentities;
7 ]>
8 <!-- Module User's Guide -->
9 <chapter>
10   <title>&adminguide;</title>
11
12   <section>
13     <title>Overview</title>
14
15     <para>The module contains record routing logic</para>
16   </section>
17
18   <section id="RR-dialog-id">
19     <title>Dialog support</title>
20
21     <para>&kamailio; is basically <emphasis>only</emphasis> a transaction
22     statefull proxy, without any dialog support build in. There are many
23     features/services which actually requires a dialog awareness, like storing
24     the information in the dialog creation stage, information which will be
25     used during the whole dialog existence.</para>
26
27     <para>The most urging example is NAT traversal, in dealing with the within
28     the dialog INVITEs (re-INVITEs). When processing the initial INVITE, the
29     proxy detects if the caller or callee is behind some NAT and fixes the
30     signalling and media parts - since not all the detection mechanism are
31     available for within the dialog requests (like usrloc), to be able to fix
32     correspondingly the sequential requests, the proxy must remember that the
33     original request was NAT processed. There are many other cases where
34     dialog awareness fixes or helps.</para>
35
36     <para>The solution is to store additional dialog-related information in
37     the routing set (Record-Route/Route headers), headers which show up in all
38     sequential requests. So any information added to the Record-Route header
39     will be found (with no direction dependencies) in Route header
40     (corresponding to the proxy address).</para>
41
42     <para>As storage container, the parameters of the Record-Route / Route
43     header will be used - Record-Route parameters mirroring are reinforced by
44     RFC 3261 (see 12.1.1 UAS behavior).</para>
45
46     <para>For this purpose, the modules offers the following functions:</para>
47
48     <itemizedlist>
49       <listitem>
50         <para>add_rr_param() - see <xref linkend="add-rr-param-id"/></para>
51       </listitem>
52
53       <listitem>
54         <para>check_route_param() - see <xref
55         linkend="check-route-param-id"/></para>
56       </listitem>
57     </itemizedlist>
58
59     <example>
60       <title>Dialog support in RR module</title>
61
62       <programlisting format="linespecific">
63 ...
64 UAC                       &kamailio; PROXY                          UAS
65
66 ---- INVITE ------&gt;       record_route()          ----- INVITE ----&gt;
67                      add_rr_param(";foo=true")
68
69 --- reINVITE -----&gt;        loose_route()          ---- reINVITE ---&gt;
70                     check_route_param(";foo=true")
71
72 &lt;-- reINVITE ------        loose_route()          &lt;--- reINVITE ----
73                     check_route_param(";foo=true")
74
75 &lt;------ BYE -------        loose_route()          &lt;----- BYE -------
76                     check_route_param(";foo=true")
77 ...
78 </programlisting>
79     </example>
80   </section>
81
82   <section>
83     <title>Dependencies</title>
84
85     <section>
86       <title>&kamailio; Modules</title>
87
88       <para>The following modules must be loaded before this module:
89       <itemizedlist>
90           <listitem>
91             <para>(optional) The "outbound" module is needed for outbound
92             routing as per RFC 5626.</para>
93           </listitem>
94         </itemizedlist></para>
95     </section>
96
97     <section>
98       <title>External Libraries or Applications</title>
99
100       <para>The following libraries or applications must be installed before
101       running &kamailio; with this module loaded: <itemizedlist>
102           <listitem>
103             <para><emphasis>None</emphasis>.</para>
104           </listitem>
105         </itemizedlist></para>
106     </section>
107   </section>
108
109   <section>
110     <title>Parameters</title>
111
112     <section>
113       <title><varname>enable_full_lr</varname> (integer)</title>
114
115       <para>If set to 1 then <quote>;lr=on</quote> instead of just
116       <quote>;lr</quote> will be used. This is to overcome problems with
117       broken &ua;s which strip <quote>;lr</quote> parameter when generating
118       Route header fields from Record-Route (<quote>;lr=on</quote> seems to
119       help).</para>
120
121       <para><emphasis> Default value is 0 (no). </emphasis></para>
122
123       <example>
124         <title>Set <varname>enable_full_lr</varname> parameter</title>
125
126         <programlisting format="linespecific">
127 ...
128 modparam("rr", "enable_full_lr", 1)
129 ...
130 </programlisting>
131       </example>
132     </section>
133
134     <section id="append-fromtag-id">
135       <title><varname>append_fromtag</varname> (integer)</title>
136
137       <para>If turned on, request's from-tag is appended to record-route;
138       that's useful for understanding whether subsequent requests (such as
139       BYE) come from caller (route's from-tag==BYE's from-tag) or callee
140       (route's from-tag==BYE's to-tag)</para>
141
142       <para><emphasis> Default value is 1 (yes). </emphasis></para>
143
144       <example>
145         <title>Set <varname>append_fromtag</varname> parameter</title>
146
147         <programlisting format="linespecific">
148 ...
149 modparam("rr", "append_fromtag", 0)
150 ...
151 </programlisting>
152       </example>
153     </section>
154
155     <section>
156       <title><varname>enable_double_rr</varname> (integer)</title>
157
158       <para>There are some situations when the server needs to insert two
159       Record-Route header fields instead of one. For example when using two
160       disconnected networks or doing cross-protocol forwarding from
161       UDP-&gt;TCP. This parameter enables inserting of 2 Record-Routes. The
162       server will later remove both of them.</para>
163
164       <para>Double record-routing does not occur when outbound is used for a
165       request.</para>
166
167       <para><emphasis> Default value is 1 (yes). </emphasis></para>
168
169       <example>
170         <title>Set <varname>enable_double_rr</varname> parameter</title>
171
172         <programlisting format="linespecific">
173 ...
174 modparam("rr", "enable_double_rr", 0)
175 ...
176 </programlisting>
177       </example>
178       <para>Some useragents (e. g. Linphone) incorrectly use UDP transport for
179       subsequent requests in dialog, despite being configured to use another
180       SIP transport protocol. This can be worked around by setting Record-Route
181       header with explicit transport attribute. But enable_double_rr enabled in
182       default mode omits transport attribute from being added to header if it
183       detects that both sender and receiver use same protocol (e. g. TCP or
184       TLS), and this results in UDP being used by such broken clients. Set
185       enable_double_rr to value 2 to always have two RR headers with transport
186       attributes expicitly set.</para>
187
188       <example>
189         <title>Set <varname>enable_double_rr</varname> to 2 to always have two explicit RR headers</title>
190
191         <programlisting format="linespecific">
192 ...
193 modparam("rr", "enable_double_rr", 2)
194 ...
195 </programlisting>
196       </example>
197     </section>
198
199     <section>
200       <title><varname>add_username</varname> (integer)</title>
201
202       <para>If set to a non 0 value (which means yes), the username part will
203       be also added in the Record-Route URI.</para>
204
205       <para>This option cannot be set when the <quote>outbound</quote> module
206       is loaded before this module as outbound uses the username part of
207       Record-Route URIs to store flow-tokens.</para>
208
209       <para><emphasis> Default value is 0 (no). </emphasis></para>
210
211       <example>
212         <title>Set <varname>add_username</varname> parameter</title>
213
214         <programlisting format="linespecific">
215 ...
216 modparam("rr", "add_username", 1)
217 ...
218 </programlisting>
219       </example>
220     </section>
221
222     <section>
223       <title><varname>enable_socket_mismatch_warning</varname>
224       (integer)</title>
225
226       <para>When a preset record-route header is forced in &kamailio; config
227       and the host from the record-route header is not the same as the host
228       server, a warning will be printed out in the logs. The
229       'enable_socket_mismatch_warning' parameter enables or disables the
230       warning. When &kamailio; is behind a NATed firewall, we don't want this
231       warning to be printed for every bridged call.</para>
232
233       <para><emphasis> Default value is 1 (yes). </emphasis></para>
234
235       <example>
236         <title><varname>enable_socket_mismatch_warning</varname> usage</title>
237
238         <programlisting format="linespecific">
239 ...
240 modparam("rr", "enable_socket_mismatch_warning", 0)
241 ...
242 </programlisting>
243       </example>
244     </section>
245
246     <section>
247       <title><varname>custom_user_avp</varname> (avp string)</title>
248
249       <para>When enable_username is enabled, a call to record_route will add
250       the username of the RequestURI to the Record-Route URI. This parameter
251       allows you to setup an AVP with which you can customise the username to
252       be added in the Record-Route URI.</para>
253
254       <para><emphasis> Default value: if not set, the std add_username
255       behaviour is used - i.e. Request URI username. </emphasis></para>
256
257       <example>
258         <title><varname>custom_user_avp</varname> usage</title>
259
260         <programlisting format="linespecific">
261 ...
262 modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")
263
264 #usage in cfg file
265 $avp(RR_CUSTOM_USER_AVP)="mo";
266 record_route();
267 ...
268 </programlisting>
269       </example>
270     </section>
271     <section id="rr.p.force_send_socket">
272       <title><varname>force_send_socket</varname> (int)</title>
273
274           <para>
275                   If set to 1, local socket is forced even for single Record-Route,
276                   otherwise is done on double Record-Route (should that be enabled).
277           </para>
278
279           <para>
280                   When use of <quote>outbound</quote> is enabled, the socket is not
281                   forced.
282           </para>
283
284       <para><emphasis>Default value is 0.</emphasis></para>
285
286       <example>
287         <title>Set <varname>force_send_socket</varname> parameter</title>
288
289         <programlisting format="linespecific">
290 ...
291 modparam("rr", "force_send_socket", 1)
292 ...
293 </programlisting>
294       </example>
295     </section>
296   </section>
297
298   <section>
299     <title>Functions</title>
300
301     <section id="loose-route-id">
302       <title><function moreinfo="none">loose_route()</function></title>
303
304       <para>The function performs routing of SIP requests which contain a
305       route set. The name is a little bit confusing, as this function also
306       routes requests which are in the <quote>strict router</quote>
307       format.</para>
308
309       <para>This function is usually used to route in-dialog requests (like
310       ACK, BYE, reINVITE). Nevertheless also out-of-dialog requests can have a
311       <quote>pre-loaded route set</quote> and my be routed with loose_route.
312       It also takes care of translating between strict-routers and
313       loose-router.</para>
314
315       <para>The loose_route function analyzes the Route: headers in the
316       requests. If there is no Route: header, the function returns FALSE and
317       routing should be done with normal lookup functions. If a Route: header
318       is found, the function returns 1 and behaves as described in section
319       16.12 of RFC 3261. There is only one exception: If the request is
320       out-of-dialog (no to-tag) and there is only one Route: header indicating
321       the local proxy, then the Route: header is removed and the function
322       returns FALSE.</para>
323
324       <para>When the <quote>outbound</quote> module was loaded before this
325       module and the Route: header contains a username part this function will
326       attempt to use the username part as a flow-token for routing.  If route
327       calculation based on flow-token succeeds, function returns TRUE even
328       if there is only one Route: header indicating the local proxy.</para>
329
330       <para>Make sure your loose_routing function can't be used by attackers
331       to bypass proxy authorization.</para>
332
333       <para>The loose_routing topic is very complex. See the RFC3261 for more
334       details (grep for <quote>route set</quote> is a good starting point in
335       this comprehensive RFC).</para>
336
337       <para>Return codes:</para>
338
339       <itemizedlist>
340         <listitem>
341           <para><emphasis>1</emphasis> - route calculation has been
342           successful</para>
343         </listitem>
344
345         <listitem>
346           <para><emphasis>2</emphasis> - route calculation based on
347           flow-token has been successful</para>
348         </listitem>
349
350         <listitem>
351           <para><emphasis>-1</emphasis> - route calculation has been
352           unsuccessful</para>
353         </listitem>
354
355         <listitem>
356           <para><emphasis>-2</emphasis> - outbound flow-token shows evidence
357           of tampering</para>
358         </listitem>
359       </itemizedlist>
360
361       <para>This function can be used from REQUEST_ROUTE.</para>
362
363       <example>
364         <title><function>loose_route</function> usage</title>
365
366         <programlisting format="linespecific">
367 ...
368 loose_route();
369 ...
370 </programlisting>
371       </example>
372     </section>
373
374     <section id="record-route-id">
375       <title><function moreinfo="none">record_route()</function> and <function
376       moreinfo="none">record_route(string)</function></title>
377
378       <para>The function adds a new Record-Route header field. The header
379       field will be inserted in the message before any other Record-Route
380       header fields.</para>
381
382       <para>If any string is passed as parameter, it will be appended as URI
383       parameter to the Record-Route header. The string must follow the
384       <quote>;name=value</quote> scheme and it may contain
385       pseudo-variables.</para>
386
387       <para>When the <quote>outbound</quote> module was loaded before this
388       module this function will determine whether outbound is required for the
389       request and generate and add a flow-token as the username part of the
390       Record-Route-URI.</para>
391
392       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
393       FAILURE_ROUTE.</para>
394
395       <example>
396         <title><function>record_route</function> usage</title>
397
398         <programlisting format="linespecific">
399 ...
400 record_route();
401 ...
402 </programlisting>
403       </example>
404     </section>
405
406     <section id="remove-record-route-id">
407                 <title><function moreinfo="none">remove_record_route()</function></title>
408
409                 <para>The function removes the internal lumps added by
410                         record_route() functions.
411                 </para>
412
413                 <para>
414                         Can be used to revert adding Record-Route header(s).
415                 </para>
416                 <para>
417                         This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
418                 </para>
419
420       <example>
421         <title><function>remove_record_route</function> usage</title>
422
423         <programlisting format="linespecific">
424 ...
425 remove_record_route();
426 ...
427 </programlisting>
428       </example>
429     </section>
430
431     <section>
432       <title><function moreinfo="none">record_route_preset(string
433       [,string2])</function></title>
434
435       <para>This function will put the string into Record-Route, don't use
436       unless you know what you are doing.</para>
437
438       <para>Meaning of the parameters is as follows:</para>
439
440       <itemizedlist>
441         <listitem>
442           <para><emphasis>string</emphasis> - String to be inserted into the
443           first header field; it may contain pseudo-variables.</para>
444         </listitem>
445
446         <listitem>
447           <para><emphasis>string2</emphasis> - String to be inserted into the
448           second header field; it may contain pseudo-variables.</para>
449         </listitem>
450       </itemizedlist>
451
452       <para>Note: If 'string2' is present, then the 'string' param is pointing
453       to the outbound interface and the 'string2' param is pointing to the
454       inbound interface.</para>
455
456       <para>When the <quote>outbound</quote> module was loaded before this
457       module this function will determine whether outbound is required for the
458       request and generate and add a flow-token as the username part of the
459       Record-Route-URI.</para>
460
461       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
462       FAILURE_ROUTE.</para>
463
464       <example>
465         <title><function>record_route_preset</function> usage</title>
466
467         <programlisting format="linespecific">
468 ...
469 record_route_preset("1.2.3.4:5090");
470 ...
471 </programlisting>
472       </example>
473     </section>
474
475     <section id="record-route-adv-addr-id">
476       <title><function
477       moreinfo="none">record_route_advertised_address(address)</function></title>
478
479       <para>The function adds a new Record-Route header field using the
480       address given. The header field will be inserted in the message before
481       any other Record-Route header fields.</para>
482
483       <para>When the <quote>outbound</quote> module was loaded before this
484       module this function will determine whether outbound is required for the
485       request and generate and add a flow-token as the username part of the
486       Record-Route-URI.</para>
487
488       <para>Meaning of the parameter is as follows:</para>
489
490       <itemizedlist>
491         <listitem>
492           <para><emphasis>address</emphasis> - Advertised address to use in
493           the header; it may contain pseudo-variables.</para>
494         </listitem>
495       </itemizedlist>
496
497       <para>If double record-routing is enabled two Record-Route headers will
498       be inserted with the same given address with different transports if the
499       transport changes.</para>
500
501       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
502       FAILURE_ROUTE.</para>
503
504       <example>
505         <title><function>record_route_advertised_address</function>
506         usage</title>
507
508         <programlisting format="linespecific">
509 ...
510 record_route_advertised_address("1.2.3.4:5080");
511 ...
512 </programlisting>
513       </example>
514     </section>
515
516     <section id="add-rr-param-id">
517       <title><function moreinfo="none">add_rr_param(param)</function></title>
518
519       <para>Adds a parameter to the Record-Route URI (param must be in
520       <quote>;name=value</quote> format. The function may be called also
521       before or after the record_route() or record_route_advertised_address()
522       calls (see <xref linkend="record-route-id"/> or <xref
523       linkend="record-route-adv-addr-id"/>)).</para>
524
525       <para>Meaning of the parameters is as follows:</para>
526
527       <itemizedlist>
528         <listitem>
529           <para><emphasis>param</emphasis> - String containing the URI
530           parameter to be added. It must follow the <quote>;name=value</quote>
531           scheme; it may contain pseudo-variables.</para>
532         </listitem>
533       </itemizedlist>
534
535       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
536       FAILURE_ROUTE.</para>
537
538       <example>
539         <title><function>add_rr_param</function> usage</title>
540
541         <programlisting format="linespecific">
542 ...
543 add_rr_param(";nat=yes");
544 ...
545 </programlisting>
546       </example>
547     </section>
548
549     <section id="check-route-param-id">
550       <title><function
551       moreinfo="none">check_route_param(re)</function></title>
552
553       <para>The function checks if the URI parameters of the local Route
554       header (corresponding to the local server) matches the given regular
555       expression. It must be call after loose_route() (see <xref
556       linkend="loose-route-id"/>).</para>
557
558       <para>Meaning of the parameters is as follows:</para>
559
560       <itemizedlist>
561         <listitem>
562           <para><emphasis>re</emphasis> - regular expression to check against
563           the Route URI parameters.</para>
564         </listitem>
565       </itemizedlist>
566
567       <para>This function can be used from REQUEST_ROUTE.</para>
568
569       <example>
570         <title><function>check_route_param</function> usage</title>
571
572         <programlisting format="linespecific">
573 ...
574 if (check_route_param("nat=yes")) {
575     setflag(6);
576 }
577 ...
578 </programlisting>
579       </example>
580     </section>
581
582     <section>
583       <title><function moreinfo="none">is_direction(dir)</function></title>
584
585       <para>The function checks the flow direction of in-dialog requests. This
586       function uses the <quote>ftag</quote> prameter from the Route header,
587       therefore the append_fromtag (see <xref linkend="append-fromtag-id"/>
588       module parameter must be enabled. Also this must be called only after
589       loose_route() (see <xref linkend="loose-route-id"/>).</para>
590
591       <para>The function returns true if the <quote>dir</quote> is the same
592       with the request's flow direction.</para>
593
594       <para>The <quote>downstream</quote> direction means that the request is
595       in the same direction as the initial request that created the
596       dialog.</para>
597
598       <para>Meaning of the parameters is as follows:</para>
599
600       <itemizedlist>
601         <listitem>
602           <para><emphasis>dir</emphasis> - string containing the direction to
603           be checked. It may be <quote>upstream</quote> (from callee to
604           caller) or <quote>downstream</quote> (caller to callee).</para>
605         </listitem>
606       </itemizedlist>
607
608       <para>This function can be used from REQUEST_ROUTE.</para>
609
610       <example>
611         <title><function>is_direction</function> usage</title>
612
613         <programlisting format="linespecific">
614 ...
615 if (is_direction("downstream")) {
616     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
617 } else {
618     xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
619 }
620 ...
621 </programlisting>
622       </example>
623     </section>
624   </section>
625
626   <section>
627     <title>Exported Pseudo Variables</title>
628
629     <section>
630       <title><function moreinfo="none">$route_uri</function></title>
631
632       <para>Returns the URI of the top route-header.</para>
633
634       <example>
635         <title>$route_uri</title>
636
637         <programlisting format="linespecific">
638 ...
639     xdbg("Route-URI is: $route_uri\n");
640 ...
641                 </programlisting>
642       </example>
643     </section>
644   </section>
645 </chapter>