Browse code

modules: readme files regenerated - topos ... [skip ci]

Kamailio Dev authored on 01/04/2021 07:16:14
Showing 1 changed files
... ...
@@ -43,15 +43,23 @@ Frederic Gaisnon
43 43
               3.10. contact_host (str)
44 44
               3.11. contact_mode (int)
45 45
               3.12. cparam_name (int)
46
-              3.13. a_contact_avp (str)
47
-              3.14. b_contact_avp (str)
48
-              3.15. rr_update (int)
49
-              3.16. contact_host_avp (str)
46
+              3.13. xavu_cfg (str)
47
+              3.14. xavu_filed_a_contact (str)
48
+              3.15. xavu_filed_b_contact (str)
49
+              3.16. rr_update (int)
50
+              3.17. xavu_field_contact_host (str)
51
+              3.18. context (str)
50 52
 
51
-        4. Event Routes
53
+        4. Functions
52 54
 
53
-              4.1. event_route[topos:msg-outgoing]
54
-              4.2. event_route[topos:msg-sending]
55
+              4.1. tps_set_context(ctx)
56
+
57
+        5. Event Routes
58
+
59
+              5.1. event_route[topos:msg-outgoing]
60
+              5.2. event_route[topos:msg-sending]
61
+              5.3. event_route[topos:msg-incoming]
62
+              5.4. event_route[topos:msg-receiving]
55 63
 
56 64
    List of Examples
57 65
 
... ...
@@ -67,12 +75,17 @@ Frederic Gaisnon
67 75
    1.10. Set contact_host parameter
68 76
    1.11. Set contact_mode parameter
69 77
    1.12. Set cparam_name parameter
70
-   1.13. Set a_contact_avp parameter
71
-   1.14. Set b_contact_avp parameter
72
-   1.15. Set rr_update parameter
73
-   1.16. Set contact_host_avp parameter
74
-   1.17. Usage of event_route[topos:msg-outgoing]
75
-   1.18. Usage of event_route[topos:msg-sending]
78
+   1.13. Set xavu_filed_a_contact parameter
79
+   1.14. Set xavu_filed_a_contact parameter
80
+   1.15. Set xavu_filed_b_contact parameter
81
+   1.16. Set rr_update parameter
82
+   1.17. Set xavu_field_contact_host parameter
83
+   1.18. Set context parameter
84
+   1.19. tps_set_context usage
85
+   1.20. Usage of event_route[topos:msg-outgoing]
86
+   1.21. Usage of event_route[topos:msg-sending]
87
+   1.22. Usage of event_route[topos:msg-incoming]
88
+   1.23. Usage of event_route[topos:msg-receoving]
76 89
 
77 90
 Chapter 1. Admin Guide
78 91
 
... ...
@@ -98,15 +111,23 @@ Chapter 1. Admin Guide
98 111
         3.10. contact_host (str)
99 112
         3.11. contact_mode (int)
100 113
         3.12. cparam_name (int)
101
-        3.13. a_contact_avp (str)
102
-        3.14. b_contact_avp (str)
103
-        3.15. rr_update (int)
104
-        3.16. contact_host_avp (str)
114
+        3.13. xavu_cfg (str)
115
+        3.14. xavu_filed_a_contact (str)
116
+        3.15. xavu_filed_b_contact (str)
117
+        3.16. rr_update (int)
118
+        3.17. xavu_field_contact_host (str)
119
+        3.18. context (str)
120
+
121
+   4. Functions
122
+
123
+        4.1. tps_set_context(ctx)
105 124
 
106
-   4. Event Routes
125
+   5. Event Routes
107 126
 
108
-        4.1. event_route[topos:msg-outgoing]
109
-        4.2. event_route[topos:msg-sending]
127
+        5.1. event_route[topos:msg-outgoing]
128
+        5.2. event_route[topos:msg-sending]
129
+        5.3. event_route[topos:msg-incoming]
130
+        5.4. event_route[topos:msg-receiving]
110 131
 
111 132
 1. Overview
112 133
 
... ...
@@ -160,10 +181,12 @@ Chapter 1. Admin Guide
160 181
    3.10. contact_host (str)
161 182
    3.11. contact_mode (int)
162 183
    3.12. cparam_name (int)
163
-   3.13. a_contact_avp (str)
164
-   3.14. b_contact_avp (str)
165
-   3.15. rr_update (int)
166
-   3.16. contact_host_avp (str)
184
+   3.13. xavu_cfg (str)
185
+   3.14. xavu_filed_a_contact (str)
186
+   3.15. xavu_filed_b_contact (str)
187
+   3.16. rr_update (int)
188
+   3.17. xavu_field_contact_host (str)
189
+   3.18. context (str)
167 190
 
168 191
 3.1. storage (str)
169 192
 
... ...
@@ -283,7 +306,9 @@ end
283 306
 
284 307
    Control what event_route blocks to be executed. It is a bitmask of: 1 -
285 308
    execute event_route[topos:msg-outgoing]; 2 - execute
286
-   event_route[topos:msg-sending].
309
+   event_route[topos:msg-sending]; 4 execute
310
+   event_route[topos:msg-incoming]; 8 execute
311
+   event_route[topos:msg-receiving];.
287 312
 
288 313
    Default value is 3 (execute both event_route blocks).
289 314
 
... ...
@@ -295,10 +320,10 @@ modparam("topos", "event_mode", 2)
295 320
 3.10. contact_host (str)
296 321
 
297 322
    You may need to control the host part of the Contact header added by
298
-   topos. If the contact_host_avp parameter is set, this value is ignored.
299
-   For example when using TLS with TOPOS the remote UAS must be able to
300
-   open a new TLS socket to the contact header. In this case, the contact
301
-   header must contain a domain name with a trusted CA signed
323
+   topos. If the xavu_filed_contact_host parameter is set, this value is
324
+   ignored. For example when using TLS with TOPOS the remote UAS must be
325
+   able to open a new TLS socket to the contact header. In this case, the
326
+   contact header must contain a domain name with a trusted CA signed
302 327
    certitificate.
303 328
 
304 329
    Default value is taken from the Record-Route URI.
... ...
@@ -321,9 +346,9 @@ modparam("topos", "contact_host", "proxy.domain.com")
321 346
    the b-side contact user from the Contact header of the processed
322 347
    initial SIP request.
323 348
 
324
-   If you use the mode (2), you need to configure the a_contact_avp and
325
-   b_contact_avp parameter. Furthermore you need to assign values to them
326
-   during the processing of the initial SIP request.
349
+   If you use the mode (2), you need to configure the xavu_field_a_contact
350
+   and xavu_field_b_contact parameter. Furthermore you need to assign
351
+   values to them during the processing of the initial SIP request.
327 352
 
328 353
    The name of the Contact URI parameter can be customized with the
329 354
    cparam_name parameter.
... ...
@@ -350,65 +375,130 @@ modparam("topos", "contact_mode", 1)
350 375
 modparam("topos", "cparam_name", "xyz")
351 376
 ...
352 377
 
353
-3.13. a_contact_avp (str)
378
+3.13. xavu_cfg (str)
379
+
380
+   Name of root XAVU to hold config-specific values to be used by module
381
+   at runtime.
382
+
383
+   Note: this parameter must be set if any other parameter prefixed with
384
+   `xavu_field_` is used.
385
+
386
+   Default value is “NULL” (disabled).
387
+
388
+   Example 1.13. Set xavu_filed_a_contact parameter
389
+...
390
+modparam("topos", "xavu_cfg", "_tps_")
391
+modparam("topos", "xavu_filed_a_contact", "a_contact")
392
+...
393
+    $xavu(_tps_=>a_contact) = "...";
394
+...
395
+
396
+3.14. xavu_filed_a_contact (str)
354 397
 
355
-   Name of the AVP parameter to evaluate for the A-side Contact Header
356
-   user part. This parameter is only necessary in contact_mode (2).
398
+   Name of the field inside root XAVU specifed by `xavu_cfg` to evaluate
399
+   for the A-side Contact Header user part. This parameter is only
400
+   necessary in contact_mode (2).
357 401
 
358 402
    Default value is “NULL” (disabled).
359 403
 
360
-   Example 1.13. Set a_contact_avp parameter
404
+   Example 1.14. Set xavu_filed_a_contact parameter
361 405
 ...
362
-modparam("topos", "a_contact_avp", "$avp(tps-act)")
406
+modparam("topos", "xavu_cfg", "_tps_")
407
+modparam("topos", "xavu_filed_a_contact", "a_contact")
408
+...
409
+    $xavu(_tps_=>a_contact) = "...";
363 410
 ...
364 411
 
365
-3.14. b_contact_avp (str)
412
+3.15. xavu_filed_b_contact (str)
366 413
 
367
-   Name of the AVP parameter to evaluate for the B-side Contact Header
368
-   user part. This parameter is only necessary in contact_mode (2).
414
+   Name of the field inside root XAVU specifed by `xavu_cfg` to evaluate
415
+   for the B-side Contact Header user part. This parameter is only
416
+   necessary in contact_mode (2).
369 417
 
370 418
    Default value is “NULL” (disabled).
371 419
 
372
-   Example 1.14. Set b_contact_avp parameter
420
+   Example 1.15. Set xavu_filed_b_contact parameter
421
+...
422
+modparam("topos", "xavu_cfg", "_tps_")
423
+modparam("topos", "xavu_filed_b_contact", "b_contact")
373 424
 ...
374
-modparam("topos", "b_contact_avp", "$avp(tps-bct)")
425
+    $xavu(_tps_=>b_contact) = "...";
426
+
375 427
 ...
376 428
 
377
-3.15. rr_update (int)
429
+3.16. rr_update (int)
378 430
 
379 431
    If set to 1, topos module will track and update record route changes on
380 432
    re-invite.
381 433
 
382 434
    Default value is 0 (do not update record route changes within dialog).
383 435
 
384
-   Example 1.15. Set rr_update parameter
436
+   Example 1.16. Set rr_update parameter
385 437
 ...
386 438
 modparam("topos", "rr_update", 1)
387 439
 ...
388 440
 
389
-3.16. contact_host_avp (str)
441
+3.17. xavu_field_contact_host (str)
390 442
 
391
-   You may need to control the host part of the Contact header added by
392
-   topos. This parameter allows to take the value from an AVP during
393
-   run-time. If this parameter is set, the contact_host parameter is
394
-   ignored. For example when using TLS with TOPOS the remote UAS must be
395
-   able to open a new TLS socket to the contact header. In this case, the
396
-   contact header must contain a domain name with a trusted CA signed
397
-   certitificate.
443
+   Control from where to take the host part of the Contact header added by
444
+   topos. This parameter allows to take the value from an XAVU during
445
+   run-time, it specifies the field inside XAVU "xavu_cfg". If this
446
+   parameter is set, the contact_host parameter is ignored. For example
447
+   when using TLS with TOPOS the remote UAS must be able to open a new TLS
448
+   socket to the contact header. In this case, the contact header must
449
+   contain a domain name with a trusted CA signed certitificate.
398 450
 
399 451
    Default value is empty, not set.
400 452
 
401
-   Example 1.16. Set contact_host_avp parameter
453
+   Example 1.17. Set xavu_field_contact_host parameter
454
+...
455
+modparam("topos", "xavu_cfg", "_tps_")
456
+modparam("topos", "xavu_contact_host", "contact_host")
457
+...
458
+    $xavu(_tps_=>contact_host) = "kamailio.org";
459
+...
460
+
461
+3.18. context (str)
462
+
463
+   Set the global context for topos instance.
464
+
465
+   The value has to be maximum 12 characters.
466
+
467
+   Default value is “NULL” (disabled).
468
+
469
+   Example 1.18. Set context parameter
470
+...
471
+modparam("topos", "context", "srvone")
472
+...
473
+
474
+4. Functions
475
+
476
+   4.1. tps_set_context(ctx)
477
+
478
+4.1.  tps_set_context(ctx)
479
+
480
+   Update the context at runtime. If the value is emtpy string, then the
481
+   runtime context is reset.
482
+
483
+   This function can be used from ANY_ROUTE.
484
+
485
+   Example 1.19. tps_set_context usage
402 486
 ...
403
-modparam("topos", "contact_host_avp", "$avp(contact_host)")
487
+request_route {
488
+    ...
489
+    tps_set_context("srvone");
490
+    ...
491
+}
404 492
 ...
405 493
 
406
-4. Event Routes
494
+5. Event Routes
407 495
 
408
-   4.1. event_route[topos:msg-outgoing]
409
-   4.2. event_route[topos:msg-sending]
496
+   5.1. event_route[topos:msg-outgoing]
497
+   5.2. event_route[topos:msg-sending]
498
+   5.3. event_route[topos:msg-incoming]
499
+   5.4. event_route[topos:msg-receiving]
410 500
 
411
-4.1. event_route[topos:msg-outgoing]
501
+5.1. event_route[topos:msg-outgoing]
412 502
 
413 503
    It is executed before doing topology stripping processing for an
414 504
    outgoing SIP message. If 'drop' is executed inside the event route,
... ...
@@ -420,7 +510,7 @@ modparam("topos", "contact_host_avp", "$avp(contact_host)")
420 510
    reparsing the outgoing SIP message for the cases when topology hiding
421 511
    is not wanted.
422 512
 
423
-   Example 1.17. Usage of event_route[topos:msg-outgoing]
513
+   Example 1.20. Usage of event_route[topos:msg-outgoing]
424 514
 ...
425 515
 event_route[topos:msg-outgoing] {
426 516
   if($sndto(ip)=="10.1.1.10") {
... ...
@@ -429,7 +519,7 @@ event_route[topos:msg-outgoing] {
429 519
 }
430 520
 ...
431 521
 
432
-4.2. event_route[topos:msg-sending]
522
+5.2. event_route[topos:msg-sending]
433 523
 
434 524
    It is executed before doing topology stripping processing for a SIP
435 525
    message to be sent out, being executed after
... ...
@@ -439,7 +529,7 @@ event_route[topos:msg-outgoing] {
439 529
    $sndto(proto) point to the destination. The SIP message is the one to
440 530
    be sent out.
441 531
 
442
-   Example 1.18. Usage of event_route[topos:msg-sending]
532
+   Example 1.21. Usage of event_route[topos:msg-sending]
443 533
 ...
444 534
 event_route[topos:msg-sending] {
445 535
   if(is_request() and $fU=="alice") {
... ...
@@ -447,3 +537,41 @@ event_route[topos:msg-sending] {
447 537
   }
448 538
 }
449 539
 ...
540
+
541
+5.3. event_route[topos:msg-incoming]
542
+
543
+   It is executed before doing topology stripping processing for an
544
+   incoming SIP message. If 'drop' is executed inside the event route,
545
+   then the module skips doing the topology hiding.
546
+
547
+   Inside the event route the variables $si, $sp and $proto point to the
548
+   source address. The SIP message is not the one to be sent out, but an
549
+   internally generated one at startup, to avoid reparsing the outgoing
550
+   SIP message for the cases when topology hiding is not wanted.
551
+
552
+   Example 1.22. Usage of event_route[topos:msg-incoming]
553
+...
554
+event_route[topos:msg-incoming] {
555
+  if($si=="10.1.1.10") {
556
+    drop;
557
+  }
558
+}
559
+...
560
+
561
+5.4. event_route[topos:msg-receiving]
562
+
563
+   It is executed before doing topology stripping processing for a SIP
564
+   message that was received, being executed after
565
+   event_route[topos:msg-incoing].
566
+
567
+   Inside the event route the variables $si, $sp and $proto point to the
568
+   source address. The SIP message is the one to be sent out.
569
+
570
+   Example 1.23. Usage of event_route[topos:msg-receoving]
571
+...
572
+event_route[topos:msg-receiving] {
573
+  if(is_request() and $fU=="alice") {
574
+    drop;
575
+  }
576
+}
577
+...