Merge pull request #924 from linuxmaniac/vseva/fix_app_python
[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>
272
273   <section>
274     <title>Functions</title>
275
276     <section id="loose-route-id">
277       <title><function moreinfo="none">loose_route()</function></title>
278
279       <para>The function performs routing of SIP requests which contain a
280       route set. The name is a little bit confusing, as this function also
281       routes requests which are in the <quote>strict router</quote>
282       format.</para>
283
284       <para>This function is usually used to route in-dialog requests (like
285       ACK, BYE, reINVITE). Nevertheless also out-of-dialog requests can have a
286       <quote>pre-loaded route set</quote> and my be routed with loose_route.
287       It also takes care of translating between strict-routers and
288       loose-router.</para>
289
290       <para>The loose_route function analyzes the Route: headers in the
291       requests. If there is no Route: header, the function returns FALSE and
292       routing should be done with normal lookup functions. If a Route: header
293       is found, the function returns 1 and behaves as described in section
294       16.12 of RFC 3261. There is only one exception: If the request is
295       out-of-dialog (no to-tag) and there is only one Route: header indicating
296       the local proxy, then the Route: header is removed and the function
297       returns FALSE.</para>
298
299       <para>When the <quote>outbound</quote> module was loaded before this
300       module and the Route: header contains a username part this function will
301       attempt to use the username part as a flow-token for routing.  If route
302       calculation based on flow-token succeeds, function returns TRUE even
303       if there is only one Route: header indicating the local proxy.</para>
304
305       <para>Make sure your loose_routing function can't be used by attackers
306       to bypass proxy authorization.</para>
307
308       <para>The loose_routing topic is very complex. See the RFC3261 for more
309       details (grep for <quote>route set</quote> is a good starting point in
310       this comprehensive RFC).</para>
311
312       <para>Return codes:</para>
313
314       <itemizedlist>
315         <listitem>
316           <para><emphasis>1</emphasis> - route calculation has been
317           successful</para>
318         </listitem>
319
320         <listitem>
321           <para><emphasis>2</emphasis> - route calculation based on
322           flow-token has been successful</para>
323         </listitem>
324
325         <listitem>
326           <para><emphasis>-1</emphasis> - route calculation has been
327           unsuccessful</para>
328         </listitem>
329
330         <listitem>
331           <para><emphasis>-2</emphasis> - outbound flow-token shows evidence
332           of tampering</para>
333         </listitem>
334       </itemizedlist>
335
336       <para>This function can be used from REQUEST_ROUTE.</para>
337
338       <example>
339         <title><function>loose_route</function> usage</title>
340
341         <programlisting format="linespecific">
342 ...
343 loose_route();
344 ...
345 </programlisting>
346       </example>
347     </section>
348
349     <section id="record-route-id">
350       <title><function moreinfo="none">record_route()</function> and <function
351       moreinfo="none">record_route(string)</function></title>
352
353       <para>The function adds a new Record-Route header field. The header
354       field will be inserted in the message before any other Record-Route
355       header fields.</para>
356
357       <para>If any string is passed as parameter, it will be appended as URI
358       parameter to the Record-Route header. The string must follow the
359       <quote>;name=value</quote> scheme and it may contain
360       pseudo-variables.</para>
361
362       <para>When the <quote>outbound</quote> module was loaded before this
363       module this function will determine whether outbound is required for the
364       request and generate and add a flow-token as the username part of the
365       Record-Route-URI.</para>
366
367       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
368       FAILURE_ROUTE.</para>
369
370       <example>
371         <title><function>record_route</function> usage</title>
372
373         <programlisting format="linespecific">
374 ...
375 record_route();
376 ...
377 </programlisting>
378       </example>
379     </section>
380
381     <section id="remove-record-route-id">
382                 <title><function moreinfo="none">remove_record_route()</function></title>
383
384                 <para>The function removes the internal lumps added by
385                         record_route() functions.
386                 </para>
387
388                 <para>
389                         Can be used to revert adding Record-Route header(s).
390                 </para>
391                 <para>
392                         This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
393                 </para>
394
395       <example>
396         <title><function>remove_record_route</function> usage</title>
397
398         <programlisting format="linespecific">
399 ...
400 remove_record_route();
401 ...
402 </programlisting>
403       </example>
404     </section>
405
406     <section>
407       <title><function moreinfo="none">record_route_preset(string
408       [,string2])</function></title>
409
410       <para>This function will put the string into Record-Route, don't use
411       unless you know what you are doing.</para>
412
413       <para>Meaning of the parameters is as follows:</para>
414
415       <itemizedlist>
416         <listitem>
417           <para><emphasis>string</emphasis> - String to be inserted into the
418           first header field; it may contain pseudo-variables.</para>
419         </listitem>
420
421         <listitem>
422           <para><emphasis>string2</emphasis> - String to be inserted into the
423           second header field; it may contain pseudo-variables.</para>
424         </listitem>
425       </itemizedlist>
426
427       <para>Note: If 'string2' is present, then the 'string' param is pointing
428       to the outbound interface and the 'string2' param is pointing to the
429       inbound interface.</para>
430
431       <para>When the <quote>outbound</quote> module was loaded before this
432       module this function will determine whether outbound is required for the
433       request and generate and add a flow-token as the username part of the
434       Record-Route-URI.</para>
435
436       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
437       FAILURE_ROUTE.</para>
438
439       <example>
440         <title><function>record_route_preset</function> usage</title>
441
442         <programlisting format="linespecific">
443 ...
444 record_route_preset("1.2.3.4:5090");
445 ...
446 </programlisting>
447       </example>
448     </section>
449
450     <section id="record-route-adv-addr-id">
451       <title><function
452       moreinfo="none">record_route_advertised_address(address)</function></title>
453
454       <para>The function adds a new Record-Route header field using the
455       address given. The header field will be inserted in the message before
456       any other Record-Route header fields.</para>
457
458       <para>When the <quote>outbound</quote> module was loaded before this
459       module this function will determine whether outbound is required for the
460       request and generate and add a flow-token as the username part of the
461       Record-Route-URI.</para>
462
463       <para>Meaning of the parameter is as follows:</para>
464
465       <itemizedlist>
466         <listitem>
467           <para><emphasis>address</emphasis> - Advertised address to use in
468           the header; it may contain pseudo-variables.</para>
469         </listitem>
470       </itemizedlist>
471
472       <para>If double record-routing is enabled two Record-Route headers will
473       be inserted with the same given address with different transports if the
474       transport changes.</para>
475
476       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
477       FAILURE_ROUTE.</para>
478
479       <example>
480         <title><function>record_route_advertised_address</function>
481         usage</title>
482
483         <programlisting format="linespecific">
484 ...
485 record_route_advertised_address("1.2.3.4:5080");
486 ...
487 </programlisting>
488       </example>
489     </section>
490
491     <section id="add-rr-param-id">
492       <title><function moreinfo="none">add_rr_param(param)</function></title>
493
494       <para>Adds a parameter to the Record-Route URI (param must be in
495       <quote>;name=value</quote> format. The function may be called also
496       before or after the record_route() or record_route_advertised_address()
497       calls (see <xref linkend="record-route-id"/> or <xref
498       linkend="record-route-adv-addr-id"/>)).</para>
499
500       <para>Meaning of the parameters is as follows:</para>
501
502       <itemizedlist>
503         <listitem>
504           <para><emphasis>param</emphasis> - String containing the URI
505           parameter to be added. It must follow the <quote>;name=value</quote>
506           scheme; it may contain pseudo-variables.</para>
507         </listitem>
508       </itemizedlist>
509
510       <para>This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
511       FAILURE_ROUTE.</para>
512
513       <example>
514         <title><function>add_rr_param</function> usage</title>
515
516         <programlisting format="linespecific">
517 ...
518 add_rr_param(";nat=yes");
519 ...
520 </programlisting>
521       </example>
522     </section>
523
524     <section id="check-route-param-id">
525       <title><function
526       moreinfo="none">check_route_param(re)</function></title>
527
528       <para>The function checks if the URI parameters of the local Route
529       header (corresponding to the local server) matches the given regular
530       expression. It must be call after loose_route() (see <xref
531       linkend="loose-route-id"/>).</para>
532
533       <para>Meaning of the parameters is as follows:</para>
534
535       <itemizedlist>
536         <listitem>
537           <para><emphasis>re</emphasis> - regular expression to check against
538           the Route URI parameters.</para>
539         </listitem>
540       </itemizedlist>
541
542       <para>This function can be used from REQUEST_ROUTE.</para>
543
544       <example>
545         <title><function>check_route_param</function> usage</title>
546
547         <programlisting format="linespecific">
548 ...
549 if (check_route_param("nat=yes")) {
550     setflag(6);
551 }
552 ...
553 </programlisting>
554       </example>
555     </section>
556
557     <section>
558       <title><function moreinfo="none">is_direction(dir)</function></title>
559
560       <para>The function checks the flow direction of in-dialog requests. This
561       function uses the <quote>ftag</quote> prameter from the Route header,
562       therefore the append_fromtag (see <xref linkend="append-fromtag-id"/>
563       module parameter must be enabled. Also this must be called only after
564       loose_route() (see <xref linkend="loose-route-id"/>).</para>
565
566       <para>The function returns true if the <quote>dir</quote> is the same
567       with the request's flow direction.</para>
568
569       <para>The <quote>downstream</quote> direction means that the request is
570       in the same direction as the initial request that created the
571       dialog.</para>
572
573       <para>Meaning of the parameters is as follows:</para>
574
575       <itemizedlist>
576         <listitem>
577           <para><emphasis>dir</emphasis> - string containing the direction to
578           be checked. It may be <quote>upstream</quote> (from callee to
579           caller) or <quote>downstream</quote> (caller to callee).</para>
580         </listitem>
581       </itemizedlist>
582
583       <para>This function can be used from REQUEST_ROUTE.</para>
584
585       <example>
586         <title><function>is_direction</function> usage</title>
587
588         <programlisting format="linespecific">
589 ...
590 if (is_direction("downstream")) {
591     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
592 } else {
593     xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
594 }
595 ...
596 </programlisting>
597       </example>
598     </section>
599   </section>
600
601   <section>
602     <title>Exported Pseudo Variables</title>
603
604     <section>
605       <title><function moreinfo="none">$route_uri</function></title>
606
607       <para>Returns the URI of the top route-header.</para>
608
609       <example>
610         <title>$route_uri</title>
611
612         <programlisting format="linespecific">
613 ...
614     xdbg("Route-URI is: $route_uri\n");
615 ...
616                 </programlisting>
617       </example>
618     </section>
619   </section>
620 </chapter>