modules: readme files regenerated - call_control ... [skip ci]
[sip-router] / src / modules / uac / README
1 UAC Module
2
3 Ramona-Elena Modroiu
4
5    <ramona@rosdev.ro>
6
7 Daniel-Constantin Mierla
8
9    <miconda@gmail.com>
10
11 Edited by
12
13 Ramona-Elena Modroiu
14
15    <ramona@rosdev.ro>
16
17    Copyright © 2009-2010 asipto.com
18
19    Copyright © 2005 Voice Sistem
20      __________________________________________________________________
21
22    Table of Contents
23
24    1. Admin Guide
25
26         1. Overview
27         2. Dependencies
28
29               2.1. Kamailio Modules
30               2.2. External Libraries or Applications
31
32         3. Parameters
33
34               3.1. rr_from_store_param (string)
35               3.2. rr_to_store_param (string)
36               3.3. restore_mode (string)
37               3.4. restore_dlg (int)
38               3.5. restore_passwd (string)
39               3.6. restore_from_avp (string)
40               3.7. restore_to_avp (string)
41               3.8. credential (string)
42               3.9. auth_realm_avp (string)
43               3.10. auth_username_avp (string)
44               3.11. auth_password_avp (string)
45               3.12. reg_db_url (string)
46               3.13. reg_timer_interval (int)
47               3.14. reg_retry_interval (int)
48               3.15. reg_random_delay (int)
49               3.16. reg_db_table (string)
50               3.17. reg_contact_addr (string)
51               3.18. reg_keep_callid (int)
52               3.19. reg_active (int)
53               3.20. reg_gc_interval (int)
54
55         4. Functions
56
57               4.1. uac_replace_from(display,uri)
58               4.2. uac_replace_from(uri)
59               4.3. uac_restore_from()
60               4.4. uac_replace_to(display,uri)
61               4.5. uac_replace_to(uri)
62               4.6. uac_restore_to()
63               4.7. uac_auth()
64               4.8. uac_req_send()
65               4.9. uac_reg_lookup(uuid, dst)
66               4.10. uac_reg_status(uuid)
67               4.11. uac_reg_request_to(user, mode)
68               4.12. uac_reg_enable(attr, val)
69               4.13. uac_reg_disable(attr, val)
70               4.14. uac_reg_refresh(luuid)
71
72         5. Pseudo Variables
73         6. Event Routes
74
75               6.1. event_route[uac:reply]
76
77         7. Counters
78         8. RPC Commands
79
80               8.1. uac.reg_dump
81               8.2. uac.reg_info
82               8.3. uac.reg_enable
83               8.4. uac.reg_disable
84               8.5. uac.reg_reload
85               8.6. uac.reg_refresh
86               8.7. uac.reg_active
87
88         9. Remote Registration
89
90    List of Examples
91
92    1.1. Set rr_from_store_param parameter
93    1.2. Set rr_to_store_param parameter
94    1.3. Set restore_mode parameter
95    1.4. Set restore_dlg parameter
96    1.5. Set restore_passwd parameter
97    1.6. Set restore_from_avp parameter
98    1.7. Set restore_to_avp parameter
99    1.8. Set credential parameter
100    1.9. Set auth_realm_avp parameter
101    1.10. Set auth_username_avp parameter
102    1.11. Set auth_password_avp parameter
103    1.12. Set reg_db_url parameter
104    1.13. Set reg_timer_interval parameter
105    1.14. Set reg_retry_interval parameter
106    1.15. Set reg_random_delay parameter
107    1.16. Set reg_db_table parameter
108    1.17. Set reg_contact_addr parameter
109    1.18. Set reg_keep_callid parameter
110    1.19. Set reg_active parameter
111    1.20. Set reg_gc_interval parameter
112    1.21. uac_replace_from usage
113    1.22. uac_replace_from usage
114    1.23. uac_restore_from usage
115    1.24. uac_replace_to usage
116    1.25. uac_replace_to usage
117    1.26. uac_restore_to usage
118    1.27. uac_auth usage
119    1.28. uac_req_send usage
120    1.29. uac_reg_lookup usage
121    1.30. uac_reg_status usage
122    1.31. uac_reg_request_to usage
123    1.32. uac_reg_enable usage
124    1.33. uac_reg_disable usage
125    1.34. uac_reg_refresh usage
126    1.35. event_route[uac:reply] usage
127    1.36. uac.reg_dump usage
128    1.37. uac.reg_info usage
129    1.38. uac.reg_enable usage
130    1.39. uac.reg_disable usage
131    1.40. uac.reg_reload usage
132    1.41. uac.reg_refresh usage
133    1.42. uac.reg_active usage
134    1.43. lookup remote registrations usage
135
136 Chapter 1. Admin Guide
137
138    Table of Contents
139
140    1. Overview
141    2. Dependencies
142
143         2.1. Kamailio Modules
144         2.2. External Libraries or Applications
145
146    3. Parameters
147
148         3.1. rr_from_store_param (string)
149         3.2. rr_to_store_param (string)
150         3.3. restore_mode (string)
151         3.4. restore_dlg (int)
152         3.5. restore_passwd (string)
153         3.6. restore_from_avp (string)
154         3.7. restore_to_avp (string)
155         3.8. credential (string)
156         3.9. auth_realm_avp (string)
157         3.10. auth_username_avp (string)
158         3.11. auth_password_avp (string)
159         3.12. reg_db_url (string)
160         3.13. reg_timer_interval (int)
161         3.14. reg_retry_interval (int)
162         3.15. reg_random_delay (int)
163         3.16. reg_db_table (string)
164         3.17. reg_contact_addr (string)
165         3.18. reg_keep_callid (int)
166         3.19. reg_active (int)
167         3.20. reg_gc_interval (int)
168
169    4. Functions
170
171         4.1. uac_replace_from(display,uri)
172         4.2. uac_replace_from(uri)
173         4.3. uac_restore_from()
174         4.4. uac_replace_to(display,uri)
175         4.5. uac_replace_to(uri)
176         4.6. uac_restore_to()
177         4.7. uac_auth()
178         4.8. uac_req_send()
179         4.9. uac_reg_lookup(uuid, dst)
180         4.10. uac_reg_status(uuid)
181         4.11. uac_reg_request_to(user, mode)
182         4.12. uac_reg_enable(attr, val)
183         4.13. uac_reg_disable(attr, val)
184         4.14. uac_reg_refresh(luuid)
185
186    5. Pseudo Variables
187    6. Event Routes
188
189         6.1. event_route[uac:reply]
190
191    7. Counters
192    8. RPC Commands
193
194         8.1. uac.reg_dump
195         8.2. uac.reg_info
196         8.3. uac.reg_enable
197         8.4. uac.reg_disable
198         8.5. uac.reg_reload
199         8.6. uac.reg_refresh
200         8.7. uac.reg_active
201
202    9. Remote Registration
203
204 1. Overview
205
206    The UAC (User Agent Client) module provides some basic UAC
207    functionalities like sending SIP requests, registering with a remote
208    service, From: header manipulation (anonymization) and client
209    authentication.
210
211    The UAC module also supports sending a SIP request from the
212    configuration file. See variable $uac_req(name) and the function
213    uac_req_send().
214
215    In addition, the module supports database-driven SIP registration
216    functionality. See the uac_reg_lookup() function and dedicated section
217    for remote registration configuration.
218
219    Known limitations in this version:
220      * Authentication does not support qop auth-int, just qop auth;
221      * CSeq is not increased automatically by uac_auth() during
222        authentication - the follow up request may be rejected. CSeq can be
223        increased when authenticating INVITE requests - dialog module has
224        to be used, with CSeq tracking feature enabled (see the readme of
225        dialog module).
226      * The “uac_replace_*” functions can only be run once on the same SIP
227        request. Try to save needed changes in a pseudovariable and apply
228        them once.
229        There is also a limitation regarding the use of the
230        “msg_apply_changes()” function together with the “uac_replace_*”
231        functions for messages that are loose-routed (e.g. Re-INVITE
232        requests). In this case you need to call the “loose_route()”
233        function after the replace and msg_apply_changes. Otherwise
234        Kamailio can create replies with wrong From/To headers (e.g. for
235        the 100 - Trying reply in the Re-INVITE example).
236
237 2. Dependencies
238
239    2.1. Kamailio Modules
240    2.2. External Libraries or Applications
241
242 2.1. Kamailio Modules
243
244    The following modules must be loaded before this module:
245      * TM - Transaction Module
246      * RR - Record-Route Module, but only if restore mode for From: URI is
247        set to “auto”.
248      * Dialog Module, but only if restore mode for From: URI is set to
249        “auto” and you want uac_replace_from or uac_replace_to to store the
250        values of the URIs as dialog variables.
251
252 2.2. External Libraries or Applications
253
254    The following libraries or applications must be installed before
255    running Kamailio with this module loaded:
256      * None
257
258 3. Parameters
259
260    3.1. rr_from_store_param (string)
261    3.2. rr_to_store_param (string)
262    3.3. restore_mode (string)
263    3.4. restore_dlg (int)
264    3.5. restore_passwd (string)
265    3.6. restore_from_avp (string)
266    3.7. restore_to_avp (string)
267    3.8. credential (string)
268    3.9. auth_realm_avp (string)
269    3.10. auth_username_avp (string)
270    3.11. auth_password_avp (string)
271    3.12. reg_db_url (string)
272    3.13. reg_timer_interval (int)
273    3.14. reg_retry_interval (int)
274    3.15. reg_random_delay (int)
275    3.16. reg_db_table (string)
276    3.17. reg_contact_addr (string)
277    3.18. reg_keep_callid (int)
278    3.19. reg_active (int)
279    3.20. reg_gc_interval (int)
280
281 3.1. rr_from_store_param (string)
282
283    Name of Record-Route header parameter that will be used to store an
284    encoded version of the original FROM URI.
285
286    This parameter is optional, it's default value being “vsf”.
287
288    Example 1.1. Set rr_from_store_param parameter
289 ...
290 modparam("uac","rr_from_store_param","my_param")
291 ...
292
293 3.2. rr_to_store_param (string)
294
295    Name of Record-Route header parameter that will be used to store
296    (encoded) the original TO URI.
297
298    This parameter is optional, it's default value being “vst”.
299
300    Example 1.2. Set rr_to_store_param parameter
301 ...
302 modparam("uac","rr_to_store_param","my_param")
303 ...
304
305 3.3. restore_mode (string)
306
307    There are 3 modes of restoring the original FROM URI and the original
308    TO URI:
309      * “none” - no information about original URI is stored; restoration
310        is not possible.
311      * “manual” - all following replies will be restored, but not also the
312        sequential requests - this must be manually updated based on
313        original URI.
314      * “auto” - all sequential requests and replies will be automatically
315        updated based on stored original URI. For this option you have to
316        set “modparam("rr", "append_fromtag", 1)”.
317
318    This parameter is optional, it's default value being “auto”.
319
320    Example 1.3. Set restore_mode parameter
321 ...
322 modparam("uac","restore_mode","auto")
323 ...
324
325 3.4. restore_dlg (int)
326
327    If set to 1, the module uses dialog variables to store initial and new
328    values for From/To headers. The Dialog module has to be loaded and all
329    calls that involve changes to From/To headers must be tracked.
330
331    Default value of this parameter is 0.
332
333    Example 1.4. Set restore_dlg parameter
334 ...
335 modparam("uac", "restore_dlg", 1)
336 ...
337
338 3.5. restore_passwd (string)
339
340    String password to be used to encrypt the RR storing parameters. If
341    empty, no encryption will be used.
342
343    Default value of this parameter is empty.
344
345    Example 1.5. Set restore_passwd parameter
346 ...
347 modparam("uac","restore_passwd","my_secret_passwd")
348 ...
349
350 3.6. restore_from_avp (string)
351
352    If defined and restore_mode is manual or auto, the avp is used to save
353    the original from uri in order to be able to restore it in replies.
354    That makes sense, if the original-uri can not be extracted from the
355    original request, e.g. if msg_apply_changes() was used after calling
356    uac_replace_from() or uac_replace_to().
357
358    If you create a dialog ( with dlg_manage() ) before calling
359    uac_replace_from(), this avp will not be needed. The values of the uris
360    will be stored as dialog variables.
361
362    Default value of this parameter is empty.
363
364    Example 1.6. Set restore_from_avp parameter
365 ...
366 modparam("uac","restore_from_avp","$avp(original_uri_from)")
367 ...
368
369 3.7. restore_to_avp (string)
370
371    If defined and restore_mode is manual or auto, the avp is used to save
372    the original To URI in order to be able to restore it in replies. That
373    makes sense if the original-uri can not be extracted from the original
374    request, e.g. if msg_apply_changes() was used after calling
375    uac_replace_to()
376
377    If you create a dialog ( with dlg_manage() ) before calling or
378    uac_replace_to(), this avp will not be needed. The values of the uris
379    will be stored as dialog variables.
380
381    Default value of this parameter is empty.
382
383    Example 1.7. Set restore_to_avp parameter
384 ...
385 modparam("uac","restore_to_avp","$avp(original_uri_to)")
386 ...
387
388 3.8. credential (string)
389
390    Contains a multiple definition of credentials used to perform
391    authentication.
392
393    This parameter is required if UAC authentication is used.
394
395    Example 1.8. Set credential parameter
396 ...
397 modparam("uac","credential","username:domain:password")
398 ...
399
400 3.9. auth_realm_avp (string)
401
402    The definition of an PV that might contain the realm to be used to
403    perform authentication.
404
405    When the PV value is an empty string or NULL when uac_auth() is called,
406    the realm is taken from the reply and only username matching is done.
407    This can be used if the realm upstream will be using is not known in
408    advance.
409
410    If you define it, you also need to define “auth_username_avp” (???) and
411    “auth_username_avp” (???).
412
413    Example 1.9. Set auth_realm_avp parameter
414 ...
415 modparam("uac","auth_realm_avp","$avp(i:10)")
416 ...
417
418 3.10. auth_username_avp (string)
419
420    The definition of an AVP that might contain the username to be used to
421    perform authentication.
422
423    If you define it, you also need to define “auth_realm_avp” (???) and
424    “auth_username_avp” (???).
425
426    Example 1.10. Set auth_username_avp parameter
427 ...
428 modparam("uac","auth_username_avp","$avp(i:11)")
429 ...
430
431 3.11. auth_password_avp (string)
432
433    The definition of an AVP that might contain the password to be used to
434    perform authentication.
435
436    If you define it, you also need to define “auth_password_avp” (???) and
437    “auth_username_avp” (???).
438
439    Example 1.11. Set auth_password_avp parameter
440 ...
441 modparam("uac","auth_password_avp","$avp(i:12)")
442 ...
443
444 3.12. reg_db_url (string)
445
446    DB URL to fetch account profiles for registration. This parameter must
447    be set in order to enable remote registrations feature.
448
449    The default value is "" (no value).
450
451    Example 1.12. Set reg_db_url parameter
452 ...
453 modparam("uac", "reg_db_url",
454     "mysql://kamailio:kamailiorw@localhost/kamailio")
455 ...
456
457 3.13. reg_timer_interval (int)
458
459    Timer interval (in seconds) at which registrations are managed, e.g.
460    renewed as needed.
461
462    The default value is 90 seconds.
463
464    Example 1.13. Set reg_timer_interval parameter
465 ...
466 modparam("uac", "reg_timer_interval", 60)
467 ...
468
469 3.14. reg_retry_interval (int)
470
471    Failed registration attempts will be retried after this interval (in
472    seconds). The interval is not exact, retries may be attempted as much
473    as reg_timer_interval secs earlier. If set to 0, failed registrations
474    will be disabled permanently.
475
476    The default value is 0 sec (disabled)
477
478    Example 1.14. Set reg_retry_interval parameter
479 ...
480 modparam("uac", "reg_retry_interval", 300)
481 ...
482
483 3.15. reg_random_delay (int)
484
485    Set a random reg_delay for each registration that has reg_delay set to
486    0 in the database. If set to 0, randomization will be disabled.
487
488    The default value is 0 sec (disabled)
489
490    Example 1.15. Set reg_random_delay parameter
491 ...
492 modparam("uac", "reg_random_delay", 300)
493 ...
494
495 3.16. reg_db_table (string)
496
497    DB table name to fetch user profiles for registration.
498
499    This parameter is optional, it's default value being “uacreg”.
500
501    Example 1.16. Set reg_db_table parameter
502 ...
503 modparam("uac", "reg_db_table", "uacreg")
504 ...
505
506 3.17. reg_contact_addr (string)
507
508    Address to be used to build contact address. Must be at least host
509    part, can have port and parameters. Must not include 'sip:'. The
510    username part of the Contact: URI will be the L_UUID field in the
511    database.
512
513    Example 1.17. Set reg_contact_addr parameter
514 ...
515 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
516 ...
517
518 3.18. reg_keep_callid (int)
519
520    If set to 0 (default), a new Call-Id will be generated for each
521    registration attempt. If set to non-zero, the same Call-Id will be used
522    for re-registrations, as recommended by RFC3261 section 10.2.4. A new
523    Call-Id will be generated when a previous registration had failed.
524
525    Example 1.18. Set reg_keep_callid parameter
526 ...
527 modparam("uac", "reg_keep_callid", 1)
528 ...
529
530 3.19. reg_active (int)
531
532    If set to 0, no remote regisrations are done. In other words, it can
533    control at once if the module should do remote registratios or not. It
534    can be changed at runtime via rpc command 'uac.reg_active 0|1'.
535
536    The default value is 1 (active).
537
538    Example 1.19. Set reg_active parameter
539 ...
540 modparam("uac", "reg_active", 0)
541 ...
542
543 3.20. reg_gc_interval (int)
544
545    Timer interval (in seconds) at which remote registrations are cleaned
546    up in case of failure or removed. When setting it take in consideration
547    the maximum value for retransmission timeout, this param should be
548    greater than it. This value also impacts how ofter the reload for
549    remote registrations table can be executed -- the RPC command will fail
550    if executed in less than reg_gc_interval value since the last reload.
551
552    The default value is 150 seconds.
553
554    Example 1.20. Set reg_gc_interval parameter
555 ...
556 modparam("uac", "reg_gc_interval", 60)
557 ...
558
559 4. Functions
560
561    4.1. uac_replace_from(display,uri)
562    4.2. uac_replace_from(uri)
563    4.3. uac_restore_from()
564    4.4. uac_replace_to(display,uri)
565    4.5. uac_replace_to(uri)
566    4.6. uac_restore_to()
567    4.7. uac_auth()
568    4.8. uac_req_send()
569    4.9. uac_reg_lookup(uuid, dst)
570    4.10. uac_reg_status(uuid)
571    4.11. uac_reg_request_to(user, mode)
572    4.12. uac_reg_enable(attr, val)
573    4.13. uac_reg_disable(attr, val)
574    4.14. uac_reg_refresh(luuid)
575
576 4.1.  uac_replace_from(display,uri)
577
578    Replace in FROM header the display name and the URI part.
579
580    display and URI parameters can include pseudo-variables.
581
582    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
583
584    NOTE: Previous versions of this function added double quotes
585    automatically to display variable. That is no longer the case, if you
586    expect that behavior, you will have to add the quotes by yourself.
587
588    If you set restore_mode to AUTO, the URI will be modified automatically
589    in all subsequent requests and replies in that dialog.
590
591    There are two ways in which the AUTO mode can be achieved.
592
593    One uses the rr module and appends to the Record-Route header a
594    parameter containing some strings from which the original and new URI
595    can be computed. The problem with this mode is that it relies on the
596    fact the parties will send the Route exactly as it was received. In
597    case there is a change, the resulting URIs will not be correct.
598
599    The other one uses the dialog module to store the original and new URI.
600    If you already use dialog module in your configuration, this is the
601    advisable mode. All you need to do to use this is to call dlg_manage()
602    before calling uac_replace_from(). It works by storing the URIs as
603    dialog variables and registering callbacks in dialog module for in
604    dialog requests.
605
606    Example 1.21. uac_replace_from usage
607 ...
608 # replace both display and uri
609 uac_replace_from("$avp(s:display)","$avp(s:uri)");
610 # replace only display and do not touch uri
611 uac_replace_from("batman","");   # display is replaced with: batman
612 uac_replace_from("\"batman\"","");  # display is replaced with: "batman"
613 # remove display and replace uri
614 uac_replace_from("","sip:robin@gotham.org");
615 # remove display and do not touch uri
616 uac_replace_from("","");
617 ...
618
619 4.2.  uac_replace_from(uri)
620
621    Replace in FROM header the URI part without altering the display name.
622
623    URI parameter can include pseudo-variables.
624
625    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
626
627    Example 1.22. uac_replace_from usage
628 ...
629 uac_replace_from("sip:batman@gotham.org");
630 ...
631
632 4.3.  uac_restore_from()
633
634    This function will check if the FROM URI was modified and will use the
635    information stored in header parameter to restore the original FROM URI
636    value.
637
638    This function can be used from REQUEST_ROUTE.
639
640    Example 1.23. uac_restore_from usage
641 ...
642 uac_restore_from();
643 ...
644
645 4.4.  uac_replace_to(display,uri)
646
647    Replace in TO header the display name and the URI part.
648
649    display and URI parameters can include pseudo-variables.
650
651    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
652
653    NOTE: Previous versions of this function added double quotes
654    automatically to display variable. That is no longer the case, if you
655    expect that behavior, you will have to add the quotes by yourself.
656
657    Example 1.24. uac_replace_to usage
658 ...
659 # replace both display and uri
660 uac_replace_to("$avp(display)","$avp(uri)");
661 # replace only display and do not touch uri
662 uac_replace_to("batman","");   # display is replaced with: batman
663 uac_replace_to("\"batman\"","");  # display is replaced with: "batman"
664 # remove display and replace uri
665 uac_replace_to("","sip:robin@gotham.org");
666 # remove display and do not touch uri
667 uac_replace_to("","");
668 ...
669
670 4.5.  uac_replace_to(uri)
671
672    Replace in TO header the URI part without altering the display name.
673
674    URI parameter can include pseudo-variables.
675
676    This function can be used from REQUEST_ROUTE and from BRANCH_ROUTE.
677
678    If you set restore_mode to AUTO, the URI will be modified automatically
679    in all subsequent requests and replies in that dialog.
680
681    There are two ways in which the AUTO mode can be achieved.
682
683    One uses the rr module and appends to the Record-Route header a
684    parameter containing some strings from which the original and new URI
685    can be computed. The problem with this mode is that it relies on the
686    fact the parties will send the Route exactly as it was received. In
687    case there is a change, the resulting URIs will not be correct.
688
689    The other one uses the dialog module to store the original and new URI.
690    If you already use dialog module in your configuration, this is the
691    advisable mode. All you need to do to use this is to call dlg_manage()
692    before calling uac_replace_to(). It works by storing the URIs as dialog
693    variables and registering callbacks in dialog module for in dialog
694    requests.
695
696    Example 1.25. uac_replace_to usage
697 ...
698 uac_replace_to("sip:batman@gotham.org");
699 ...
700
701 4.6.  uac_restore_to()
702
703    This function will check if the TO URI was modified and will use the
704    information stored in header parameter to restore the original TO URI
705    value.
706
707    This function can be used from REQUEST_ROUTE.
708
709    Example 1.26. uac_restore_to usage
710 ...
711 uac_restore_to();
712 ...
713
714 4.7.  uac_auth()
715
716    This function can be called only from failure route and will build the
717    authentication response header and insert it into the request without
718    sending anything.
719
720    This function can be used from FAILURE_ROUTE.
721
722    Example 1.27. uac_auth usage
723 ...
724 modparam("uac","auth_username_avp","$avp(auser)")
725 modparam("uac","auth_password_avp","$avp(apass)")
726 modparam("uac","auth_realm_avp","$avp(arealm)")
727
728 request_route {
729    ...
730    if(is_method("INVITE")) {
731       t_on_failure("TRUNKAUTH");
732    }
733    ...
734 }
735
736 failure_route[TRUNKAUTH] {
737
738     if (t_is_canceled()) {
739         exit;
740     }
741     if(t_check_status("401|407")) {
742         $avp(auser) = "test";
743         $avp(apass) = "test";
744         uac_auth();
745         t_relay();
746         exit;
747     }
748 }
749 ...
750
751 4.8.  uac_req_send()
752
753    This function sends a SIP message from the configuration file. The
754    message is built out of $uac_req(...) pseudo-variable.
755
756    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
757    BRANCH_ROUTE, ONREPLY_ROUTE, LOCAL_ROUTE.
758
759    Example 1.28. uac_req_send usage
760 ...
761 $uac_req(method)="OPTIONS";
762 $uac_req(ruri)="sip:kamailio.org";
763 $uac_req(furi)="sip:kamailio.org";
764 $uac_req(turi)="sip:kamailio.org";
765 $uac_req(callid)=$(mb{s.md5});
766 uac_req_send();
767 ...
768
769 4.9.  uac_reg_lookup(uuid, dst)
770
771    This function sets the PV dst to SIP URI that correspond to uuid in uac
772    registrations table. uuid and dst must be pseudo-variables.
773
774    This function can be used from ANY_ROUTE.
775
776    Example 1.29. uac_reg_lookup usage
777 ...
778
779 if(uac_reg_lookup("$rU", "$ru"))
780 {
781     lookup("location");
782 }
783 ...
784
785 4.10.  uac_reg_status(uuid)
786
787    This function returns the current registration status for the uuid.
788
789    Return values:
790      * 1 - a valid registration exists.
791      * -1 - uuid does not exist or an error occurred while executing the
792        function.
793      * -2 - a registration attempt is ongoing (and currently there is no
794        valid registration).
795      * -3 - registration is disabled.
796      * -99 - no valid registration, waiting for new registration attempt.
797
798    This function can be used from ANY_ROUTE.
799
800    Example 1.30. uac_reg_status usage
801 ...
802 $var(status) = uac_reg_status("$rU");
803 ...
804
805 4.11.  uac_reg_request_to(user, mode)
806
807    This function can be used to send an authenticated request to a remote
808    user in the uac registrations table. It sets the request-uri, dst-uri
809    and auth_*_avp pv's to the values that correspond to the supplied user.
810
811    The mode indicates whether the user should match the local uuid
812    (mode=0), or the username (mode=1).
813
814    The auth_*_avp module parameters must be set to valid pv's.
815
816    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
817    BRANCH_ROUTE.
818
819    Example 1.31. uac_reg_request_to usage
820 ...
821
822 if(uac_reg_request_to("$fU", 0))
823 {
824         xlog("L_NOTICE", "Found remote user [$rU] on [$rd] via [$du]");
825         t_on_failure("REMOTE_AUTH");
826
827         t_relay()
828 }
829 ...
830 failure_route[REMOTE_AUTH] {
831         if ($T_reply_code == 401 or $T_reply_code == 407) {
832                 xlog("L_NOTICE", "Remote asked for authentication");
833                 uac_auth()
834         }
835 }
836 ...
837
838 4.12.  uac_reg_enable(attr, val)
839
840    Enable a remote registration record based on a filter specified by
841    attribute and value. The attribute can be: l_uuid, l_username,
842    r_username or auth_username. The value is what should be matched
843    against the value of the attribute in the remote registration record.
844
845    The SIP processing is done on the next timer routine.
846
847    Example 1.32. uac_reg_enable usage
848 ...
849    uac_reg_enable("l_uuid", "account123");
850 ...
851
852 4.13.  uac_reg_disable(attr, val)
853
854    Disable a remote registration record based on a filter specified by
855    attribute and value. The attribute can be: l_uuid, l_username,
856    r_username or auth_username. The value is what should be matched
857    against the value of the attribute in the remote registration record.
858
859    The SIP processing is done on the next timer routine.
860
861    Example 1.33. uac_reg_disable usage
862 ...
863    uac_reg_disable("l_uuid", "account123");
864 ...
865
866 4.14.  uac_reg_refresh(luuid)
867
868    Refresh the uac remote registration record based on local uuid. If the
869    record was already loaded, new values are taken from database,
870    otherwise a new record is created.
871
872    Example 1.34. uac_reg_refresh usage
873 ...
874    uac_reg_refresh("account123");
875 ...
876
877 5. Pseudo Variables
878
879      * $uac_req(key)
880
881    Exported pseudo-variables are documented at
882    https://www.kamailio.org/wiki/.
883
884 6. Event Routes
885
886    6.1. event_route[uac:reply]
887
888 6.1.  event_route[uac:reply]
889
890    Event route executed for the final reply of the branch for the request
891    sent with uac_req_send(). The associated $uac_req(evroute) has to be
892    set to 1. If the request is challenged for authentication with 401/407,
893    then the event_route is executed twice, first for 401/407 and second
894    for final reply of the transaction.
895
896    Example 1.35. event_route[uac:reply] usage
897 ...
898 $uac_req(method)="OPTIONS";
899 $uac_req(ruri)="sip:kamailio.org";
900 $uac_req(furi)="sip:kamailio.org";
901 $uac_req(turi)="sip:kamailio.org";
902 $uac_req(callid)=$(mb{s.md5});
903 $uac_req(evroute)=1;
904 uac_req_send();
905 ...
906 event_route[uac:reply] {
907     xlog("received reply code is: $uac_req(evcode)\n");
908 }
909 ...
910
911 7. Counters
912
913      * regtotal: Total number of registrations
914      * regactive: Total number of active registrations (successfully
915        registered with service)
916      * regdisabled: Total number of disabled registrations (no longer
917        active)
918
919 8. RPC Commands
920
921    8.1. uac.reg_dump
922    8.2. uac.reg_info
923    8.3. uac.reg_enable
924    8.4. uac.reg_disable
925    8.5. uac.reg_reload
926    8.6. uac.reg_refresh
927    8.7. uac.reg_active
928
929 8.1.  uac.reg_dump
930
931    Dump the content of remote registration table from memory.
932
933    Example 1.36. uac.reg_dump usage
934 ...
935    kamcmd uac.reg_dump
936 ...
937
938 8.2.  uac.reg_info
939
940    Return the details of a remote registration record based on a filter.
941    The command has two parameter: attribute and value. The attribute can
942    be: l_uuid, l_username, r_username or auth_username. The value is what
943    should be matched against the value of the attribute in the remote
944    registration record.
945
946    The state of the registration is reflected in the flags field:
947      * 1 (2^0) - registration profile is disabled
948      * 2 (2^1) - registration in progress
949      * 4 (2^2) - registration succeeded
950      * 8 (2^3) - registration in progres with authentication
951      * 16 (2^4) - registration initialized (after loading from database,
952        the registration process was initialized)
953
954    Example 1.37. uac.reg_info usage
955 ...
956    kamcmd uac.reg_info l_uuid account123
957    kamcmd uac.reg_info l_uuid s:12345678
958 ...
959
960 8.3.  uac.reg_enable
961
962    Enable a remote registration record based on a filter. The command has
963    two parameter: attribute and value. The attribute can be: l_uuid,
964    l_username, r_username or auth_username. The value is what should be
965    matched against the value of the attribute in the remote registration
966    record.
967
968    Example 1.38. uac.reg_enable usage
969 ...
970    kamcmd uac.reg_enable l_uuid account123
971    kamcmd uac.reg_enable l_uuid s:12345678
972 ...
973
974 8.4.  uac.reg_disable
975
976    Disable a remote registration record based on a filter. The command has
977    two parameter: attribute and value. The attribute can be: l_uuid,
978    l_username, r_username or auth_username. The value is what should be
979    matched against the value of the attribute in the remote registration
980    record.
981
982    Example 1.39. uac.reg_disable usage
983 ...
984    kamcmd uac.reg_disable l_uuid account123
985    kamcmd uac.reg_disable l_uuid s:12345678
986 ...
987
988 8.5.  uac.reg_reload
989
990    Reload the records from database for remote registrations.
991
992    Example 1.40. uac.reg_reload usage
993 ...
994    kamcmd uac.reg_reload
995 ...
996
997 8.6.  uac.reg_refresh
998
999    Load one record by l_uuid from database for remote registrations. If
1000    the record exists in memory, it will be replaced with the new values
1001    loaded from database.
1002
1003    Example 1.41. uac.reg_refresh usage
1004 ...
1005    kamcmd uac.reg_refresh account123
1006    kamcmd uac.reg_refresh s:12345678
1007 ...
1008
1009 8.7.  uac.reg_active
1010
1011    Control if the module should do remote registrations or not. Setting to
1012    1 enables remote registrations for all records and 0 disables doing
1013    them.
1014
1015    Example 1.42. uac.reg_active usage
1016 ...
1017    kamctl rpc uac.reg_active 0
1018    kamctl rpc uac.reg_active 1
1019 ...
1020
1021 9. Remote Registration
1022
1023    The module can register contact addresses to remote REGISTRAR servers.
1024    You have to add records to uacreg table. The table stores following
1025    attributes:
1026      * l_uuid - local unique user id, e.g.,: 12345678
1027
1028      * l_username - local user name, e.g.,: test
1029
1030      * l_domain - local domain, e.g.,: mysipserver.com
1031
1032      * r_username - remote username, e.g.,: test123
1033
1034      * r_domain - remote domain, e.g.,: sipprovider.com
1035
1036      * realm - remote relam, e.g.,: sipprovider.com
1037
1038      * auth_username - authentication username, e.g.,: test123
1039
1040      * auth_password - authentication password, e.g.,: xxxxxx
1041
1042      * auth_proxy - SIP address of authentication proxy, e.g.,:
1043        sip:sipprovider.com
1044
1045      * expires - expiration time for registration, in seconds, e.g.,: 360
1046
1047      * flags - the state of the registration, see Section 8.2, “
1048        uac.reg_info ”
1049
1050      * reg_delay - delay initial registration with at least reg_delay
1051        seconds, e.g.,: 3
1052
1053    The module takes care of sending REGISTER and refresh registrations
1054    before they expire.
1055
1056    When calls come in, you have to run uac_reg_lookup() that will detect
1057    if the call is coming from a remote SIP provider and can change the
1058    R-URI to local username@domain. Afterwards you can run location lookup.
1059
1060    Example 1.43. lookup remote registrations usage
1061 ...
1062     if(uac_reg_lookup("$rU", "$ru")) {
1063         xlog("request from a remote SIP provider [$ou => $ru]\n");
1064     }
1065     lookup("location");
1066 ...