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