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