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