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