Browse code

modules/uac: update README

Vicente Hernando authored on 17/05/2013 11:31:19
Showing 1 changed files
... ...
@@ -23,46 +23,46 @@ Ramona-Elena Modroiu
23 23
 
24 24
    1. Admin Guide
25 25
 
26
-        1.1. Overview
27
-        1.2. Dependencies
28
-
29
-              1.2.1. Kamailio Modules
30
-              1.2.2. External Libraries or Applications
31
-
32
-        1.3. Parameters
33
-
34
-              1.3.1. rr_from_store_param (string)
35
-              1.3.2. rr_to_store_param (string)
36
-              1.3.3. restore_mode (string)
37
-              1.3.4. restore_dlg (int)
38
-              1.3.5. restore_passwd (string)
39
-              1.3.6. restore_from_avp (string)
40
-              1.3.7. restore_to_avp (string)
41
-              1.3.8. credential (string)
42
-              1.3.9. auth_realm_avp (string)
43
-              1.3.10. auth_username_avp (string)
44
-              1.3.11. auth_password_avp (string)
45
-              1.3.12. reg_db_url (string)
46
-              1.3.13. reg_timer_interval (string)
47
-              1.3.14. reg_retry_interval (int)
48
-              1.3.15. reg_db_table (string)
49
-              1.3.16. reg_contact_addr (string)
50
-
51
-        1.4. Functions
52
-
53
-              1.4.1. uac_replace_from(display,uri)
54
-              1.4.2. uac_replace_from(uri)
55
-              1.4.3. uac_restore_from()
56
-              1.4.4. uac_replace_to(display,uri)
57
-              1.4.5. uac_replace_to(uri)
58
-              1.4.6. uac_restore_to()
59
-              1.4.7. uac_auth()
60
-              1.4.8. uac_req_send()
61
-              1.4.9. uac_reg_lookup(uuid, dst)
62
-              1.4.10. uac_reg_request_to(user, mode)
63
-
64
-        1.5. Exported pseudo-variables
65
-        1.6. Remote Registration
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 (string)
47
+              3.14. reg_retry_interval (int)
48
+              3.15. reg_db_table (string)
49
+              3.16. reg_contact_addr (string)
50
+
51
+        4. Functions
52
+
53
+              4.1. uac_replace_from(display,uri)
54
+              4.2. uac_replace_from(uri)
55
+              4.3. uac_restore_from()
56
+              4.4. uac_replace_to(display,uri)
57
+              4.5. uac_replace_to(uri)
58
+              4.6. uac_restore_to()
59
+              4.7. uac_auth()
60
+              4.8. uac_req_send()
61
+              4.9. uac_reg_lookup(uuid, dst)
62
+              4.10. uac_reg_request_to(user, mode)
63
+
64
+        5. Exported pseudo-variables
65
+        6. Remote Registration
66 66
 
67 67
    List of Examples
68 68
 
... ...
@@ -96,7 +96,50 @@ Ramona-Elena Modroiu
96 96
 
97 97
 Chapter 1. Admin Guide
98 98
 
99
-1.1. Overview
99
+   Table of Contents
100
+
101
+   1. Overview
102
+   2. Dependencies
103
+
104
+        2.1. Kamailio Modules
105
+        2.2. External Libraries or Applications
106
+
107
+   3. Parameters
108
+
109
+        3.1. rr_from_store_param (string)
110
+        3.2. rr_to_store_param (string)
111
+        3.3. restore_mode (string)
112
+        3.4. restore_dlg (int)
113
+        3.5. restore_passwd (string)
114
+        3.6. restore_from_avp (string)
115
+        3.7. restore_to_avp (string)
116
+        3.8. credential (string)
117
+        3.9. auth_realm_avp (string)
118
+        3.10. auth_username_avp (string)
119
+        3.11. auth_password_avp (string)
120
+        3.12. reg_db_url (string)
121
+        3.13. reg_timer_interval (string)
122
+        3.14. reg_retry_interval (int)
123
+        3.15. reg_db_table (string)
124
+        3.16. reg_contact_addr (string)
125
+
126
+   4. Functions
127
+
128
+        4.1. uac_replace_from(display,uri)
129
+        4.2. uac_replace_from(uri)
130
+        4.3. uac_restore_from()
131
+        4.4. uac_replace_to(display,uri)
132
+        4.5. uac_replace_to(uri)
133
+        4.6. uac_restore_to()
134
+        4.7. uac_auth()
135
+        4.8. uac_req_send()
136
+        4.9. uac_reg_lookup(uuid, dst)
137
+        4.10. uac_reg_request_to(user, mode)
138
+
139
+   5. Exported pseudo-variables
140
+   6. Remote Registration
141
+
142
+1. Overview
100 143
 
101 144
    The UAC (User Agent Client) module provides some basic UAC
102 145
    functionalities like sending SIP requests, registering with a remote
... ...
@@ -119,9 +162,12 @@ Chapter 1. Admin Guide
119 119
        request. Try to save needed changes in a pseudovariable and apply
120 120
        them once.
121 121
 
122
-1.2. Dependencies
122
+2. Dependencies
123
+
124
+   2.1. Kamailio Modules
125
+   2.2. External Libraries or Applications
123 126
 
124
-1.2.1. Kamailio Modules
127
+2.1. Kamailio Modules
125 128
 
126 129
    The following modules must be loaded before this module:
127 130
      * TM - Transaction Module
... ...
@@ -131,15 +177,32 @@ Chapter 1. Admin Guide
131 131
        “auto” and you want uac_replace_from or uac_replace_to to store the
132 132
        values of the URIs as dialog variables.
133 133
 
134
-1.2.2. External Libraries or Applications
134
+2.2. External Libraries or Applications
135 135
 
136 136
    The following libraries or applications must be installed before
137 137
    running Kamailio with this module loaded:
138 138
      * None
139 139
 
140
-1.3. Parameters
141
-
142
-1.3.1. rr_from_store_param (string)
140
+3. Parameters
141
+
142
+   3.1. rr_from_store_param (string)
143
+   3.2. rr_to_store_param (string)
144
+   3.3. restore_mode (string)
145
+   3.4. restore_dlg (int)
146
+   3.5. restore_passwd (string)
147
+   3.6. restore_from_avp (string)
148
+   3.7. restore_to_avp (string)
149
+   3.8. credential (string)
150
+   3.9. auth_realm_avp (string)
151
+   3.10. auth_username_avp (string)
152
+   3.11. auth_password_avp (string)
153
+   3.12. reg_db_url (string)
154
+   3.13. reg_timer_interval (string)
155
+   3.14. reg_retry_interval (int)
156
+   3.15. reg_db_table (string)
157
+   3.16. reg_contact_addr (string)
158
+
159
+3.1. rr_from_store_param (string)
143 160
 
144 161
    Name of Record-Route header parameter that will be used to store an
145 162
    encoded version of the original FROM URI.
... ...
@@ -151,7 +214,7 @@ Chapter 1. Admin Guide
151 151
 modparam("uac","rr_from_store_param","my_param")
152 152
 ...
153 153
 
154
-1.3.2. rr_to_store_param (string)
154
+3.2. rr_to_store_param (string)
155 155
 
156 156
    Name of Record-Route header parameter that will be used to store
157 157
    (encoded) the original TO URI.
... ...
@@ -163,7 +226,7 @@ modparam("uac","rr_from_store_param","my_param")
163 163
 modparam("uac","rr_to_store_param","my_param")
164 164
 ...
165 165
 
166
-1.3.3. restore_mode (string)
166
+3.3. restore_mode (string)
167 167
 
168 168
    There are 3 modes of restoring the original FROM URI and the original
169 169
    TO URI:
... ...
@@ -183,7 +246,7 @@ modparam("uac","rr_to_store_param","my_param")
183 183
 modparam("uac","restore_mode","auto")
184 184
 ...
185 185
 
186
-1.3.4. restore_dlg (int)
186
+3.4. restore_dlg (int)
187 187
 
188 188
    If set to 1, the module uses dialog variables to store initial and new
189 189
    values for From/To headers. The Dialog module has to be loaded and all
... ...
@@ -196,7 +259,7 @@ modparam("uac","restore_mode","auto")
196 196
 modparam("uac", "restore_dlg", 1)
197 197
 ...
198 198
 
199
-1.3.5. restore_passwd (string)
199
+3.5. restore_passwd (string)
200 200
 
201 201
    String password to be used to encrypt the RR storing parameters. If
202 202
    empty, no encryption will be used.
... ...
@@ -208,7 +271,7 @@ modparam("uac", "restore_dlg", 1)
208 208
 modparam("uac","restore_passwd","my_secret_passwd")
209 209
 ...
210 210
 
211
-1.3.6. restore_from_avp (string)
211
+3.6. restore_from_avp (string)
212 212
 
213 213
    If defined and restore_mode is manual or auto, the avp is used to save
214 214
    the original from uri in order to be able to restore it in replies.
... ...
@@ -227,7 +290,7 @@ modparam("uac","restore_passwd","my_secret_passwd")
227 227
 modparam("uac","restore_from_avp","$avp(original_uri_from)")
228 228
 ...
229 229
 
230
-1.3.7. restore_to_avp (string)
230
+3.7. restore_to_avp (string)
231 231
 
232 232
    If defined and restore_mode is manual or auto, the avp is used to save
233 233
    the original To URI in order to be able to restore it in replies. That
... ...
@@ -246,7 +309,7 @@ modparam("uac","restore_from_avp","$avp(original_uri_from)")
246 246
 modparam("uac","restore_to_avp","$avp(original_uri_to)")
247 247
 ...
248 248
 
249
-1.3.8. credential (string)
249
+3.8. credential (string)
250 250
 
251 251
    Contains a multiple definition of credentials used to perform
252 252
    authentication.
... ...
@@ -258,7 +321,7 @@ modparam("uac","restore_to_avp","$avp(original_uri_to)")
258 258
 modparam("uac","credential","username:domain:password")
259 259
 ...
260 260
 
261
-1.3.9. auth_realm_avp (string)
261
+3.9. auth_realm_avp (string)
262 262
 
263 263
    The definition of an PV that might contain the realm to be used to
264 264
    perform authentication.
... ...
@@ -269,43 +332,43 @@ modparam("uac","credential","username:domain:password")
269 269
    advance.
270 270
 
271 271
    If you define it, you also need to define “auth_username_avp”
272
-   (Section 1.3.10, “auth_username_avp (string)”) and “auth_username_avp”
273
-   (Section 1.3.11, “auth_password_avp (string)”).
272
+   (Section 3.10, “auth_username_avp (string)”) and “auth_username_avp”
273
+   (Section 3.11, “auth_password_avp (string)”).
274 274
 
275 275
    Example 1.9. Set auth_realm_avp parameter
276 276
 ...
277 277
 modparam("uac","auth_realm_avp","$avp(i:10)")
278 278
 ...
279 279
 
280
-1.3.10. auth_username_avp (string)
280
+3.10. auth_username_avp (string)
281 281
 
282 282
    The definition of an AVP that might contain the username to be used to
283 283
    perform authentication.
284 284
 
285 285
    If you define it, you also need to define “auth_realm_avp”
286
-   (Section 1.3.9, “auth_realm_avp (string)”) and “auth_username_avp”
287
-   (Section 1.3.11, “auth_password_avp (string)”).
286
+   (Section 3.9, “auth_realm_avp (string)”) and “auth_username_avp”
287
+   (Section 3.11, “auth_password_avp (string)”).
288 288
 
289 289
    Example 1.10. Set auth_username_avp parameter
290 290
 ...
291 291
 modparam("uac","auth_username_avp","$avp(i:11)")
292 292
 ...
293 293
 
294
-1.3.11. auth_password_avp (string)
294
+3.11. auth_password_avp (string)
295 295
 
296 296
    The definition of an AVP that might contain the password to be used to
297 297
    perform authentication.
298 298
 
299 299
    If you define it, you also need to define “auth_password_avp”
300
-   (Section 1.3.11, “auth_password_avp (string)”) and “auth_username_avp”
301
-   (Section 1.3.11, “auth_password_avp (string)”).
300
+   (Section 3.11, “auth_password_avp (string)”) and “auth_username_avp”
301
+   (Section 3.11, “auth_password_avp (string)”).
302 302
 
303 303
    Example 1.11. Set auth_password_avp parameter
304 304
 ...
305 305
 modparam("uac","auth_password_avp","$avp(i:12)")
306 306
 ...
307 307
 
308
-1.3.12. reg_db_url (string)
308
+3.12. reg_db_url (string)
309 309
 
310 310
    DB URL to fetch account profiles for registration.
311 311
 
... ...
@@ -315,7 +378,7 @@ modparam("uac", "reg_db_url",
315 315
     "mysql://kamailio:kamailiorw@localhost/kamailio")
316 316
 ...
317 317
 
318
-1.3.13. reg_timer_interval (string)
318
+3.13. reg_timer_interval (string)
319 319
 
320 320
    Timer interval (in seconds) at which registrations are managed, e.g.
321 321
    renewed as needed.
... ...
@@ -327,7 +390,7 @@ modparam("uac", "reg_db_url",
327 327
 modparam("uac", "reg_timer_interval", 60)
328 328
 ...
329 329
 
330
-1.3.14. reg_retry_interval (int)
330
+3.14. reg_retry_interval (int)
331 331
 
332 332
    Failed registration attempts will be retried after this interval (in
333 333
    seconds). The interval is not exact, retries may be attempted as much
... ...
@@ -341,7 +404,7 @@ modparam("uac", "reg_timer_interval", 60)
341 341
 modparam("uac", "reg_retry_interval", 300)
342 342
 ...
343 343
 
344
-1.3.15. reg_db_table (string)
344
+3.15. reg_db_table (string)
345 345
 
346 346
    DB table name to fetch user profiles for registration.
347 347
 
... ...
@@ -352,7 +415,7 @@ modparam("uac", "reg_retry_interval", 300)
352 352
 modparam("uac", "reg_db_table", "uacreg")
353 353
 ...
354 354
 
355
-1.3.16. reg_contact_addr (string)
355
+3.16. reg_contact_addr (string)
356 356
 
357 357
    Address to be used to build contact address. Must be at least host
358 358
    part, can have port and parameters. Must not include 'sip:'. The
... ...
@@ -364,9 +427,20 @@ modparam("uac", "reg_db_table", "uacreg")
364 364
 modparam("uac", "reg_contact_addr", "192.168.1.2:5080")
365 365
 ...
366 366
 
367
-1.4. Functions
367
+4. Functions
368
+
369
+   4.1. uac_replace_from(display,uri)
370
+   4.2. uac_replace_from(uri)
371
+   4.3. uac_restore_from()
372
+   4.4. uac_replace_to(display,uri)
373
+   4.5. uac_replace_to(uri)
374
+   4.6. uac_restore_to()
375
+   4.7. uac_auth()
376
+   4.8. uac_req_send()
377
+   4.9. uac_reg_lookup(uuid, dst)
378
+   4.10. uac_reg_request_to(user, mode)
368 379
 
369
-1.4.1.  uac_replace_from(display,uri)
380
+4.1.  uac_replace_from(display,uri)
370 381
 
371 382
    Replace in FROM header the display name and the URI part.
372 383
 
... ...
@@ -409,7 +483,7 @@ uac_replace_from("","sip:robin@gotham.org");
409 409
 uac_replace_from("","");
410 410
 ...
411 411
 
412
-1.4.2.  uac_replace_from(uri)
412
+4.2.  uac_replace_from(uri)
413 413
 
414 414
    Replace in FROM header the URI part without altering the display name.
415 415
 
... ...
@@ -422,7 +496,7 @@ uac_replace_from("","");
422 422
 uac_replace_from("sip:batman@gotham.org");
423 423
 ...
424 424
 
425
-1.4.3.  uac_restore_from()
425
+4.3.  uac_restore_from()
426 426
 
427 427
    This function will check if the FROM URI was modified and will use the
428 428
    information stored in header parameter to restore the original FROM URI
... ...
@@ -435,7 +509,7 @@ uac_replace_from("sip:batman@gotham.org");
435 435
 uac_restore_from();
436 436
 ...
437 437
 
438
-1.4.4.  uac_replace_to(display,uri)
438
+4.4.  uac_replace_to(display,uri)
439 439
 
440 440
    Replace in TO header the display name and the URI part.
441 441
 
... ...
@@ -460,7 +534,7 @@ uac_replace_to("","sip:robin@gotham.org");
460 460
 uac_replace_to("","");
461 461
 ...
462 462
 
463
-1.4.5.  uac_replace_to(uri)
463
+4.5.  uac_replace_to(uri)
464 464
 
465 465
    Replace in TO header the URI part without altering the display name.
466 466
 
... ...
@@ -491,7 +565,7 @@ uac_replace_to("","");
491 491
 uac_replace_to("sip:batman@gotham.org");
492 492
 ...
493 493
 
494
-1.4.6.  uac_restore_to()
494
+4.6.  uac_restore_to()
495 495
 
496 496
    This function will check if the TO URI was modified and will use the
497 497
    information stored in header parameter to restore the original TO URI
... ...
@@ -504,7 +578,7 @@ uac_replace_to("sip:batman@gotham.org");
504 504
 uac_restore_to();
505 505
 ...
506 506
 
507
-1.4.7.  uac_auth()
507
+4.7.  uac_auth()
508 508
 
509 509
    This function can be called only from failure route and will build the
510 510
    authentication response header and insert it into the request without
... ...
@@ -517,7 +591,7 @@ uac_restore_to();
517 517
 uac_auth();
518 518
 ...
519 519
 
520
-1.4.8.  uac_req_send()
520
+4.8.  uac_req_send()
521 521
 
522 522
    This function sends a SIP message from the configuration file. The
523 523
    message is built out of $uac_req(...) pseudo-variable.
... ...
@@ -534,7 +608,7 @@ $uac_req(turi)="sip:kamailio.org";
534 534
 uac_req_send();
535 535
 ...
536 536
 
537
-1.4.9.  uac_reg_lookup(uuid, dst)
537
+4.9.  uac_reg_lookup(uuid, dst)
538 538
 
539 539
    This function sets the PV dst to SIP URI that correspond to uuid in uac
540 540
    registations table. uuid and dst must be pseudo-variables.
... ...
@@ -550,7 +624,7 @@ if(uac_reg_lookup("$rU", "$ru"))
550 550
 }
551 551
 ...
552 552
 
553
-1.4.10.  uac_reg_request_to(user, mode)
553
+4.10.  uac_reg_request_to(user, mode)
554 554
 
555 555
    This function can be used to send an authenticated request to a remote
556 556
    user in the uac registrations table. It sets the request-uri, dst-uri
... ...
@@ -583,14 +657,14 @@ failure_route[REMOTE_AUTH] {
583 583
 }
584 584
 ...
585 585
 
586
-1.5. Exported pseudo-variables
586
+5. Exported pseudo-variables
587 587
 
588 588
      * $uac_req(key)
589 589
 
590 590
    Exported pseudo-variables are documented at
591 591
    http://www.kamailio.org/wiki/.
592 592
 
593
-1.6. Remote Registration
593
+6. Remote Registration
594 594
 
595 595
    The module can register contact addresses to remote REGISTRAR servers.
596 596
    You have to add records to uacreg table. The table stores following