modules: readme files regenerated - rr ... [skip ci]
[kamailio] / src / modules / rr / README
1 rr Module
2
3 Jan Janak
4
5    FhG FOKUS
6
7 Bogdan-Andrei Iancu
8
9    Voice Sistem SRL
10
11 Carsten Bock
12
13    ng-voice.com
14
15 Edited by
16
17 Jan Janak
18
19 Bogdan-Andrei Iancu
20
21    Copyright © 2003 FhG FOKUS
22
23    Copyright © 2005 Voice Sistem SRL
24
25    Copyright © 2011 Carsten Bock, carsten@ng-voice.com
26      __________________________________________________________________
27
28    Table of Contents
29
30    1. Admin Guide
31
32         1. Overview
33         2. Dialog support
34         3. Dependencies
35
36               3.1. Kamailio Modules
37               3.2. External Libraries or Applications
38
39         4. Parameters
40
41               4.1. enable_full_lr (integer)
42               4.2. append_fromtag (integer)
43               4.3. enable_double_rr (integer)
44               4.4. add_username (integer)
45               4.5. enable_socket_mismatch_warning (integer)
46               4.6. custom_user_avp (avp string)
47               4.7. force_send_socket (int)
48               4.8. ignore_sips (int)
49
50         5. Functions
51
52               5.1. loose_route()
53               5.2. record_route([sparams])
54               5.3. remove_record_route()
55               5.4. record_route_preset(string [,string2])
56               5.5. record_route_advertised_address(address)
57               5.6. add_rr_param(param)
58               5.7. check_route_param(re)
59               5.8. is_direction(dir)
60
61         6. Exported Pseudo Variables
62
63               6.1. $route_uri
64
65    2. Developer Guide
66
67         1. Available Functions
68
69               1.1. record_route(string)
70               1.2. record_route_advertised_address(string)
71               1.3. add_rr_param( msg, param)
72               1.4. check_route_param( msg, re)
73               1.5. is_direction( msg, dir)
74               1.6. get_route_param( msg, name, val)
75               1.7. register_rrcb( callback, param)
76
77         2. Examples
78
79    List of Examples
80
81    1.1. Dialog support in RR module
82    1.2. Set enable_full_lr parameter
83    1.3. Set append_fromtag parameter
84    1.4. Set enable_double_rr parameter
85    1.5. Set enable_double_rr to 2 to always have two explicit RR headers
86    1.6. Set add_username parameter
87    1.7. enable_socket_mismatch_warning usage
88    1.8. custom_user_avp usage
89    1.9. Set force_send_socket parameter
90    1.10. Set ignore_sips parameter
91    1.11. loose_route usage
92    1.12. record_route usage
93    1.13. remove_record_route usage
94    1.14. record_route_preset usage
95    1.15. record_route_advertised_address usage
96    1.16. add_rr_param usage
97    1.17. check_route_param usage
98    1.18. is_direction usage
99    1.19. $route_uri
100    2.1. record_route usage
101    2.2. record_route_advertised_address usage
102    2.3. Loading RR module's API from another module
103
104 Chapter 1. Admin Guide
105
106    Table of Contents
107
108    1. Overview
109    2. Dialog support
110    3. Dependencies
111
112         3.1. Kamailio Modules
113         3.2. External Libraries or Applications
114
115    4. Parameters
116
117         4.1. enable_full_lr (integer)
118         4.2. append_fromtag (integer)
119         4.3. enable_double_rr (integer)
120         4.4. add_username (integer)
121         4.5. enable_socket_mismatch_warning (integer)
122         4.6. custom_user_avp (avp string)
123         4.7. force_send_socket (int)
124         4.8. ignore_sips (int)
125
126    5. Functions
127
128         5.1. loose_route()
129         5.2. record_route([sparams])
130         5.3. remove_record_route()
131         5.4. record_route_preset(string [,string2])
132         5.5. record_route_advertised_address(address)
133         5.6. add_rr_param(param)
134         5.7. check_route_param(re)
135         5.8. is_direction(dir)
136
137    6. Exported Pseudo Variables
138
139         6.1. $route_uri
140
141 1. Overview
142
143    The module contains record routing logic
144
145 2. Dialog support
146
147    Kamailio is basically only a transaction stateful proxy, without any
148    dialog support build in. There are many features/services which
149    actually requires a dialog awareness, like storing the information in
150    the dialog creation stage, information which will be used during the
151    whole dialog existence.
152
153    The most urging example is NAT traversal, in dealing with the within
154    the dialog INVITEs (re-INVITEs). When processing the initial INVITE,
155    the proxy detects if the caller or callee is behind some NAT and fixes
156    the signalling and media parts - since not all the detection mechanism
157    are available for within the dialog requests (like usrloc), to be able
158    to fix correspondingly the sequential requests, the proxy must remember
159    that the original request was NAT processed. There are many other cases
160    where dialog awareness fixes or helps.
161
162    The solution is to store additional dialog-related information in the
163    routing set (Record-Route/Route headers), headers which show up in all
164    sequential requests. So any information added to the Record-Route
165    header will be found (with no direction dependencies) in Route header
166    (corresponding to the proxy address).
167
168    As storage container, the parameters of the Record-Route / Route header
169    will be used - Record-Route parameters mirroring are reinforced by RFC
170    3261 (see 12.1.1 UAS behavior).
171
172    For this purpose, the modules offers the following functions:
173      * add_rr_param() - see ???
174      * check_route_param() - see ???
175
176    Example 1.1. Dialog support in RR module
177 ...
178 UAC                       Kamailio PROXY                          UAS
179
180 ---- INVITE ------>       record_route()          ----- INVITE ---->
181                      add_rr_param(";foo=true")
182
183 --- reINVITE ----->        loose_route()          ---- reINVITE --->
184                     check_route_param(";foo=true")
185
186 <-- reINVITE ------        loose_route()          <--- reINVITE ----
187                     check_route_param(";foo=true")
188
189 <------ BYE -------        loose_route()          <----- BYE -------
190                     check_route_param(";foo=true")
191 ...
192
193 3. Dependencies
194
195    3.1. Kamailio Modules
196    3.2. External Libraries or Applications
197
198 3.1. Kamailio Modules
199
200    The following modules must be loaded before this module:
201      * (optional) The "outbound" module is needed for outbound routing as
202        per RFC 5626.
203
204 3.2. External Libraries or Applications
205
206    The following libraries or applications must be installed before
207    running Kamailio with this module loaded:
208      * None.
209
210 4. Parameters
211
212    4.1. enable_full_lr (integer)
213    4.2. append_fromtag (integer)
214    4.3. enable_double_rr (integer)
215    4.4. add_username (integer)
216    4.5. enable_socket_mismatch_warning (integer)
217    4.6. custom_user_avp (avp string)
218    4.7. force_send_socket (int)
219    4.8. ignore_sips (int)
220
221 4.1. enable_full_lr (integer)
222
223    If set to 1 then “;lr=on” instead of just “;lr” will be used. This is
224    to overcome problems with broken UAs which strip “;lr” parameter when
225    generating Route header fields from Record-Route (“;lr=on” seems to
226    help).
227
228    Default value is 0 (no).
229
230    Example 1.2. Set enable_full_lr parameter
231 ...
232 modparam("rr", "enable_full_lr", 1)
233 ...
234
235 4.2. append_fromtag (integer)
236
237    If turned on, request's from-tag is appended to record-route; that's
238    useful for understanding whether subsequent requests (such as BYE) come
239    from caller (route's from-tag==BYE's from-tag) or callee (route's
240    from-tag==BYE's to-tag)
241
242    Default value is 1 (yes).
243
244    Example 1.3. Set append_fromtag parameter
245 ...
246 modparam("rr", "append_fromtag", 0)
247 ...
248
249 4.3. enable_double_rr (integer)
250
251    There are some situations when the server needs to insert two
252    Record-Route header fields instead of one. For example when using two
253    disconnected networks or doing cross-protocol forwarding from UDP->TCP.
254    This parameter enables inserting of 2 Record-Routes. The server will
255    later remove both of them.
256
257    Double record-routing does not occur when outbound is used for a
258    request.
259
260    Default value is 1 (yes).
261
262    Example 1.4. Set enable_double_rr parameter
263 ...
264 modparam("rr", "enable_double_rr", 0)
265 ...
266
267    Some useragents (e. g. Linphone) incorrectly use UDP transport for
268    subsequent requests in dialog, despite being configured to use another
269    SIP transport protocol. This can be worked around by setting
270    Record-Route header with explicit transport attribute. But
271    enable_double_rr enabled in default mode omits transport attribute from
272    being added to header if it detects that both sender and receiver use
273    same protocol (e. g. TCP or TLS), and this results in UDP being used by
274    such broken clients. Set enable_double_rr to value 2 to always have two
275    RR headers with transport attributes explicitly set.
276
277    Example 1.5. Set enable_double_rr to 2 to always have two explicit RR
278    headers
279 ...
280 modparam("rr", "enable_double_rr", 2)
281 ...
282
283 4.4. add_username (integer)
284
285    If set to a non 0 value (which means yes), the username part will be
286    also added in the Record-Route URI.
287
288    This option cannot be set when the “outbound” module is loaded before
289    this module as outbound uses the username part of Record-Route URIs to
290    store flow-tokens.
291
292    Default value is 0 (no).
293
294    Example 1.6. Set add_username parameter
295 ...
296 modparam("rr", "add_username", 1)
297 ...
298
299 4.5. enable_socket_mismatch_warning (integer)
300
301    When a preset record-route header is forced in Kamailio config and the
302    host from the record-route header is not the same as the host server, a
303    warning will be printed out in the logs. The
304    'enable_socket_mismatch_warning' parameter enables or disables the
305    warning. When Kamailio is behind a NATed firewall, we don't want this
306    warning to be printed for every bridged call.
307
308    Default value is 1 (yes).
309
310    Example 1.7. enable_socket_mismatch_warning usage
311 ...
312 modparam("rr", "enable_socket_mismatch_warning", 0)
313 ...
314
315 4.6. custom_user_avp (avp string)
316
317    When enable_username is enabled, a call to record_route will add the
318    username of the RequestURI to the Record-Route URI. This parameter
319    allows you to setup an AVP with which you can customise the username to
320    be added in the Record-Route URI.
321
322    Default value: if not set, the std add_username behaviour is used -
323    i.e. Request URI username.
324
325    Example 1.8. custom_user_avp usage
326 ...
327 modparam("rr", "custom_user_avp", "$avp(RR_CUSTOMER_USER_AVP)")
328
329 #usage in cfg file
330 $avp(RR_CUSTOM_USER_AVP)="mo";
331 record_route();
332 ...
333
334 4.7. force_send_socket (int)
335
336    If set to 1, local socket is forced even for single Record-Route,
337    otherwise is done on double Record-Route (should that be enabled).
338
339    When use of “outbound” is enabled, the socket is not forced.
340
341    Default value is 0.
342
343    Example 1.9. Set force_send_socket parameter
344 ...
345 modparam("rr", "force_send_socket", 1)
346 ...
347
348 4.8. ignore_sips (int)
349
350    If set to 1, the Record-Route header are build with 'sip' schema
351    always, ignoring the presence of 'sips' schema in request URI.
352
353    Default value is 0 (use 'sips' if present in R-URI).
354
355    Example 1.10. Set ignore_sips parameter
356 ...
357 modparam("rr", "ignore_sips", 1)
358 ...
359
360 5. Functions
361
362    5.1. loose_route()
363    5.2. record_route([sparams])
364    5.3. remove_record_route()
365    5.4. record_route_preset(string [,string2])
366    5.5. record_route_advertised_address(address)
367    5.6. add_rr_param(param)
368    5.7. check_route_param(re)
369    5.8. is_direction(dir)
370
371 5.1. loose_route()
372
373    The function performs routing of SIP requests which contain a route
374    set. The name is a little bit confusing, as this function also routes
375    requests which are in the “strict router” format.
376
377    This function is usually used to route in-dialog requests (like ACK,
378    BYE, reINVITE). Nevertheless also out-of-dialog requests can have a
379    “pre-loaded route set” and my be routed with loose_route. It also takes
380    care of translating between strict-routers and loose-router.
381
382    The loose_route function analyzes the Route: headers in the requests.
383    If there is no Route: header, the function returns FALSE and routing
384    should be done with normal lookup functions. If a Route: header is
385    found, the function returns 1 and behaves as described in section 16.12
386    of RFC 3261. There is only one exception: If the request is
387    out-of-dialog (no to-tag) and there is only one Route: header
388    indicating the local proxy, then the Route: header is removed and the
389    function returns FALSE.
390
391    When the “outbound” module was loaded before this module and the Route:
392    header contains a username part this function will attempt to use the
393    username part as a flow-token for routing. If route calculation based
394    on flow-token succeeds, function returns TRUE even if there is only one
395    Route: header indicating the local proxy.
396
397    Make sure your loose_routing function can't be used by attackers to
398    bypass proxy authorization.
399
400    The loose_routing topic is very complex. See the RFC3261 for more
401    details (grep for “route set” is a good starting point in this
402    comprehensive RFC).
403
404    Return codes:
405      * 1 - route calculation has been successful
406      * 2 - route calculation based on flow-token has been successful
407      * -1 - route calculation has been unsuccessful
408      * -2 - outbound flow-token shows evidence of tampering
409      * -3 - next hop is taken from a preloaded route set
410
411    This function can be used from REQUEST_ROUTE.
412
413    Example 1.11. loose_route usage
414 ...
415 loose_route();
416 ...
417
418 5.2. record_route([sparams])
419
420    The function adds a new Record-Route header field. The header field
421    will be inserted in the message before any other Record-Route header
422    fields.
423
424    If any string is passed as parameter, it will be appended as URI
425    parameter to the Record-Route header. The string must follow the
426    “;name=value” scheme and it may contain pseudo-variables.
427
428    When the “outbound” module was loaded before this module this function
429    will determine whether outbound is required for the request and
430    generate and add a flow-token as the username part of the
431    Record-Route-URI.
432
433    Note: if append From-tag is enabled and the function is used for
434    requests within dialog, it must be executed after loose_route() in
435    order to detect properly the direction.
436
437    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
438    FAILURE_ROUTE.
439
440    Example 1.12. record_route usage
441 ...
442 record_route();
443 ...
444
445 5.3. remove_record_route()
446
447    The function removes the internal lumps added by record_route()
448    functions.
449
450    Can be used to revert adding Record-Route header(s).
451
452    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
453
454    Example 1.13. remove_record_route usage
455 ...
456 remove_record_route();
457 ...
458
459 5.4. record_route_preset(string [,string2])
460
461    This function will put the string into Record-Route, don't use unless
462    you know what you are doing.
463
464    Meaning of the parameters is as follows:
465      * string - String to be inserted into the first header field; it may
466        contain pseudo-variables.
467      * string2 - String to be inserted into the second header field; it
468        may contain pseudo-variables.
469
470    Note: If 'string2' is present, then the 'string' param is pointing to
471    the outbound interface and the 'string2' param is pointing to the
472    inbound interface.
473
474    When the “outbound” module was loaded before this module this function
475    will determine whether outbound is required for the request and
476    generate and add a flow-token as the username part of the
477    Record-Route-URI.
478
479    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
480    FAILURE_ROUTE.
481
482    Example 1.14. record_route_preset usage
483 ...
484 record_route_preset("1.2.3.4:5090");
485 ...
486
487 5.5. record_route_advertised_address(address)
488
489    The function adds a new Record-Route header field using the address
490    given. The header field will be inserted in the message before any
491    other Record-Route header fields.
492
493    When the “outbound” module was loaded before this module this function
494    will determine whether outbound is required for the request and
495    generate and add a flow-token as the username part of the
496    Record-Route-URI.
497
498    Meaning of the parameter is as follows:
499      * address - Advertised address to use in the header; it may contain
500        pseudo-variables.
501
502    If double record-routing is enabled two Record-Route headers will be
503    inserted with the same given address with different transports if the
504    transport changes.
505
506    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
507    FAILURE_ROUTE.
508
509    Example 1.15. record_route_advertised_address usage
510 ...
511 record_route_advertised_address("1.2.3.4:5080");
512 ...
513
514 5.6. add_rr_param(param)
515
516    Adds a parameter to the Record-Route URI (param must be in
517    “;name=value” format. The function may be called also before or after
518    the record_route() or record_route_advertised_address() calls (see ???
519    or ???)).
520
521    Meaning of the parameters is as follows:
522      * param - String containing the URI parameter to be added. It must
523        follow the “;name=value” scheme; it may contain pseudo-variables.
524
525    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
526    FAILURE_ROUTE.
527
528    Example 1.16. add_rr_param usage
529 ...
530 add_rr_param(";nat=yes");
531 ...
532
533 5.7. check_route_param(re)
534
535    The function checks if the URI parameters of the local Route header
536    (corresponding to the local server) matches the given regular
537    expression. It must be call after loose_route() (see ???).
538
539    Meaning of the parameters is as follows:
540      * re - regular expression to check against the Route URI parameters.
541
542    This function can be used from REQUEST_ROUTE.
543
544    Example 1.17. check_route_param usage
545 ...
546 if (check_route_param("nat=yes")) {
547     setflag(6);
548 }
549 ...
550
551 5.8. is_direction(dir)
552
553    The function checks the flow direction of in-dialog requests. This
554    function uses the “ftag” parameter from the Route header, therefore the
555    append_fromtag (see ??? module parameter must be enabled. Also this
556    must be called only after loose_route() (see ???).
557
558    The function returns true if the “dir” is the same with the request's
559    flow direction.
560
561    The “downstream” direction means that the request is in the same
562    direction as the initial request that created the dialog.
563
564    Meaning of the parameters is as follows:
565      * dir - string containing the direction to be checked. It may be
566        “upstream” (from callee to caller) or “downstream” (caller to
567        callee).
568
569    This function can be used from REQUEST_ROUTE.
570
571    Example 1.18. is_direction usage
572 ...
573 if (is_direction("downstream")) {
574     xdbg("in-dialog request from caller to callee (downstream) ($rm)\n");
575 } else {
576     xdbg("in-dialog request from callee to caller (upstream) ($rm)\n");
577 }
578 ...
579
580 6. Exported Pseudo Variables
581
582    6.1. $route_uri
583
584 6.1. $route_uri
585
586    Returns the URI of the top route-header.
587
588    Example 1.19. $route_uri
589 ...
590     xdbg("Route-URI is: $route_uri\n");
591 ...
592
593 Chapter 2. Developer Guide
594
595    Table of Contents
596
597    1. Available Functions
598
599         1.1. record_route(string)
600         1.2. record_route_advertised_address(string)
601         1.3. add_rr_param( msg, param)
602         1.4. check_route_param( msg, re)
603         1.5. is_direction( msg, dir)
604         1.6. get_route_param( msg, name, val)
605         1.7. register_rrcb( callback, param)
606
607    2. Examples
608
609    The RR module provides an internal API to be used by other Kamailio
610    modules. The API offers support for SIP dialog based functionalities -
611    for more about the dialog support offered by RR module, see Section 2,
612    “Dialog support”.
613
614    For internal(non-script) usage, the RR module offers to other module
615    the possibility to register callback functions to be executed each time
616    a local Route header is processed. The callback function will receive
617    as parameter the register parameter and the Route header parameter
618    string.
619
620 1. Available Functions
621
622    1.1. record_route(string)
623    1.2. record_route_advertised_address(string)
624    1.3. add_rr_param( msg, param)
625    1.4. check_route_param( msg, re)
626    1.5. is_direction( msg, dir)
627    1.6. get_route_param( msg, name, val)
628    1.7. register_rrcb( callback, param)
629
630 1.1.  record_route(string)
631
632    The function adds a new Record-Route header field. The header field
633    will be inserted in the message before any other Record-Route header
634    fields.
635
636    If any string is passed as parameter, it will be appended as URI
637    parameter to the Record-Route header. The string must follow the
638    “;name=value” scheme and it may contain pseudo-variables.
639
640    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE and
641    FAILURE_ROUTE.
642
643    Example 2.1. record_route usage
644 ...
645 record_route();
646 ...
647
648 1.2.  record_route_advertised_address(string)
649
650    This function will add the string into a new Record-Route header field.
651    Don't use unless you know what you are doing. The header field will be
652    inserted in the message before any other Record-Route header fields.
653
654    Meaning of the parameters is as follows:
655      * string - String to be inserted into the header field.
656
657    Calls to add_rr_param() will add parameters to the Record-Route header.
658    Note: A second Record-Route will be inserted if the transport used on
659    the inbound and outbound interfaces changes.
660
661    Example 2.2. record_route_advertised_address usage
662 ...
663 record_route_advertised_address("1.2.3.4:5090");
664 ...
665
666 1.3.  add_rr_param( msg, param)
667
668    Adds a parameter to the requests's Record-Route URI (param must be in
669    “;name=value” format).
670
671    The function returns 0 on success. Otherwise, -1 is returned.
672
673    Meaning of the parameters is as follows:
674      * struct sip_msg* msg - request that will has the parameter “param”
675        added to its Record-Route header.
676      * str* param - parameter to be added to the Record-Route header - it
677        must be in “;name=value” format.
678
679 1.4.  check_route_param( msg, re)
680
681    The function checks for the request “msg” if the URI parameters of the
682    local Route header (corresponding to the local server) matches the
683    given regular expression “re”. It must be call after the loose_route
684    was done.
685
686    The function returns 0 on success. Otherwise, -1 is returned.
687
688    Meaning of the parameters is as follows:
689      * struct sip_msg* msg - request that will has the Route header
690        parameters checked.
691      * regex_t* param - compiled regular expression to be checked against
692        the Route header parameters.
693
694 1.5.  is_direction( msg, dir)
695
696    The function checks the flow direction of the request “msg”. As for
697    checking it's used the “ftag” Route header parameter, the
698    append_fromtag (see ??? module parameter must be enables. Also this
699    must be call only after the loose_route is done.
700
701    The function returns 0 if the “dir” is the same with the request's flow
702    direction. Otherwise, -1 is returned.
703
704    Meaning of the parameters is as follows:
705      * struct sip_msg* msg - request that will have the direction checked.
706      * int dir - direction to be checked against. It may be
707        “RR_FLOW_UPSTREAM” or “RR_FLOW_DOWNSTREAM”.
708
709 1.6.  get_route_param( msg, name, val)
710
711    The function search in to the “msg”'s Route header parameters the
712    parameter called “name” and returns its value into “val”. It must be
713    call only after the loose_route is done.
714
715    The function returns 0 if parameter was found (even if it has no
716    value). Otherwise, -1 is returned.
717
718    Meaning of the parameters is as follows:
719      * struct sip_msg* msg - request that will have the Route header
720        parameter searched.
721      * str *name - contains the Route header parameter to be searched.
722      * str *val - returns the value of the searched Route header parameter
723        if found. It might be empty string if the parameter had no value.
724
725 1.7.  register_rrcb( callback, param)
726
727    The function register a new callback (along with its parameter). The
728    callback will be called when a loose route will be performed for the
729    local address.
730
731    The function returns 0 on success. Otherwise, -1 is returned.
732
733    Meaning of the parameters is as follows:
734      * rr_cb_t callback - callback function to be registered.
735      * void *param - parameter to be passed to the callback function.
736
737 2. Examples
738
739    Example 2.3. Loading RR module's API from another module
740 ...
741 #include "../rr/api.h"
742 ...
743 struct rr_binds my_rrb;
744 ...
745 ...
746 /* load the RR API */
747 if (load_rr_api( &my_rrb )!=0) {
748     LM_ERR("can't load RR API\n");
749     goto error;
750 }
751 ...
752 ...
753 /* register a RR callback */
754 if (my_rrb.register_rrcb(my_callback,0))!=0) {
755     LM_ERR("can't register RR callback\n");
756     goto error;
757 }
758 ...