Debian Codegraph @

src/modules/rtpengine/README

raw
1 rtpengine Module
2
3 Maxim Sobolev
4
5 Sippy Software, Inc.
6
7 Juha Heinanen
8
9 TuTPro, Inc.
10
11 Edited by
12
13 Maxim Sobolev
14
15 Bogdan-Andrei Iancu
16
17 Juha Heinanen
18
19 Sas Ovidiu
20
21 Carsten Bock
22
23 ng-voice GmbH
24
25 Richard Fuchs
26
27 Sipwise GmbH
28
29 Donat Zenichev
30
31 Sipwise GmbH
32
33 Joey Golan
34
35 Copyright © 2003-2008 Sippy Software, Inc.
36
37 Copyright © 2005 Voice Sistem SRL
38
39 Copyright © 2009-2014 TuTPro Inc.
40
41 Copyright © 2010 VoIPEmbedded Inc.
42
43 Copyright © 2013-2019 Sipwise GmbH
44 __________________________________________________________________
45
46 Table of Contents
47
48 1. Admin Guide
49
50 1. Overview
51 2. Recommended Version
52 3. Usage With Multiple RTPEngine Instances
53 4. Dependencies
54
55 4.1. Kamailio Modules
56 4.2. External Libraries or Applications
57
58 5. Parameters
59
60 5.1. rtpengine_sock (string)
61 5.2. rtpengine_disable_tout (integer)
62 5.3. aggressive_redetection (integer)
63 5.4. rtpengine_tout_ms (integer)
64 5.5. rtpengine_allow_op (integer)
65 5.6. queried_nodes_limit (integer)
66 5.7. rtpengine_retr (integer)
67 5.8. extra_id_pv (string)
68 5.9. setid_avp (string)
69 5.10. force_send_interface (string)
70 5.11. read_sdp_pv (string)
71 5.12. write_sdp_pv (string)
72 5.13. write_sdp_pv_mode (int)
73 5.14. rtp_inst_pvar (string)
74 5.15. hash_table_size (integer)
75 5.16. hash_table_tout (integer)
76 5.17. db_url (string)
77 5.18. table_name (string)
78 5.19. setid_col (string)
79 5.20. url_col (string)
80 5.21. weight_col (string)
81 5.22. disabled_col (string)
82 5.23. setid_default (integer)
83 5.24. media_duration (string)
84 5.25. mos_min_pv (string)
85 5.26. mos_min_at_pv (string)
86 5.27. mos_min_packetloss_pv (string)
87 5.28. mos_min_jitter_pv (string)
88 5.29. mos_min_roundtrip_pv (string)
89 5.30. mos_max_pv (string)
90 5.31. mos_max_at_pv (string)
91 5.32. mos_max_packetloss_pv (string)
92 5.33. mos_max_jitter_pv (string)
93 5.34. mos_max_roundtrip_pv (string)
94 5.35. mos_average_pv (string)
95 5.36. mos_average_packetloss_pv (string)
96 5.37. mos_average_jitter_pv (string)
97 5.38. mos_average_roundtrip_pv (string)
98 5.39. mos_average_samples_pv (string)
99 5.40. mos_A_label_pv (string)
100 5.41. mos_min_A_pv (string)
101 5.42. mos_min_at_A_pv (string)
102 5.43. mos_min_packetloss_A_pv (string)
103 5.44. mos_min_jitter_A_pv (string)
104 5.45. mos_min_roundtrip_A_pv (string)
105 5.46. mos_min_roundtrip_leg_A_pv (string)
106 5.47. mos_max_A_pv (string)
107 5.48. mos_max_at_A_pv (string)
108 5.49. mos_max_packetloss_A_pv (string)
109 5.50. mos_max_jitter_A_pv (string)
110 5.51. mos_max_roundtrip_A_pv (string)
111 5.52. mos_max_roundtrip_leg_A_pv (string)
112 5.53. mos_average_A_pv (string)
113 5.54. mos_average_packetloss_A_pv (string)
114 5.55. mos_average_jitter_A_pv (string)
115 5.56. mos_average_roundtrip_A_pv (string)
116 5.57. mos_average_roundtrip_leg_A_pv (string)
117 5.58. mos_average_samples_A_pv (string)
118 5.59. mos_B_label_pv (string)
119 5.60. mos_min_B_pv (string)
120 5.61. mos_min_at_B_pv (string)
121 5.62. mos_min_packetloss_B_pv (string)
122 5.63. mos_min_jitter_B_pv (string)
123 5.64. mos_min_roundtrip_B_pv (string)
124 5.65. mos_min_roundtrip_leg_B_pv (string)
125 5.66. mos_max_B_pv (string)
126 5.67. mos_max_at_B_pv (string)
127 5.68. mos_max_packetloss_B_pv (string)
128 5.69. mos_max_jitter_B_pv (string)
129 5.70. mos_max_roundtrip_B_pv (string)
130 5.71. mos_max_roundtrip_leg_B_pv (string)
131 5.72. mos_average_B_pv (string)
132 5.73. mos_average_packetloss_B_pv (string)
133 5.74. mos_average_jitter_B_pv (string)
134 5.75. mos_average_roundtrip_B_pv (string)
135 5.76. mos_average_roundtrip_leg_B_pv (string)
136 5.77. mos_average_samples_B_pv (string)
137 5.78. dtmf_event_callid (string)
138 5.79. dtmf_event_source_tag (string)
139 5.80. dtmf_event_timestamp (string)
140 5.81. dtmf_event (string)
141 5.82. control_cmd_tos (integer)
142 5.83. hash_algo (integer)
143 5.84. wsapi (string)
144 5.85. dtmf_events_sock (string)
145 5.86. ping_mode (integer)
146
147 6. ping_interval (integer)
148 7. enable_dmq (integer)
149 8. dtmf_event_source_label (str)
150 9. dtmf_event_tags (str)
151 10. dtmf_event_type (str)
152 11. dtmf_event_source_ip (str)
153 12. dtmf_event_duration (str)
154 13. dtmf_event_volume (str)
155 14. event_callback (str)
156 15. Functions
157
158 15.1. set_rtpengine_set(setid[, setid])
159 15.2. rtpengine_offer([flags][,via-branch])
160 15.3. rtpengine_answer([flags][,via-branch])
161 15.4. rtpengine_info([flags][,via-branch])
162 15.5. rtpengine_delete([flags][,via-branch])
163 15.6. rtpengine_destroy([flags][,via-branch])
164 15.7. rtpengine_query([flags][,via-branch])
165 15.8. rtpengine_query_v(fmt, var)
166 15.9. rtpengine_connect([flags][,via-branch])
167 15.10. rtpengine_manage([flags][,via-branch])
168 15.11.
169 rtpengine_subscribe_request(flags,sdp_avp,to_tag_avp,s
170 tream_xavp[,via-branch])
171
172 15.12. rtpengine_subscribe_answer([flags][,via-branch])
173 15.13. rtpengine_unsubscribe([flags][,via-branch])
174 15.14. start_recording([flags])
175 15.15. stop_recording([flags])
176 15.16. block_dtmf([flags])
177 15.17. unblock_dtmf([flags])
178 15.18. block_media([flags])
179 15.19. unblock_media([flags])
180 15.20. silence_media([flags])
181 15.21. unsilence_media([flags])
182 15.22. start_forwarding([flags])
183 15.23. stop_forwarding([flags])
184 15.24. play_media([flags])
185 15.25. stop_media([flags])
186 15.26. play_dtmf([flags])
187
188 16. Exported Pseudo Variables
189
190 16.1. $rtpestat
191 16.2. $rtpstat
192
193 17. RPC Commands
194
195 17.1. rtpengine.reload
196 17.2. rtpengine.enable proxy_url/all 0/1
197 17.3. rtpengine.show proxy_url/all
198 17.4. rtpengine.ping proxy_url/all
199 17.5. rtpengine.get_hash_total
200
201 18. Event routes
202
203 18.1. rtpengine:dtmf-event
204
205 2. Frequently Asked Questions
206
207 List of Examples
208
209 1.1. Set rtpengine_sock parameter
210 1.2. Set rtpengine_disable_tout parameter
211 1.3. Set aggressive_redetection parameter
212 1.4. Set rtpengine_tout_ms parameter
213 1.5. Set rtpengine_allow_op parameter
214 1.6. Set queried_nodes_limit parameter
215 1.7. Set rtpengine_retr parameter
216 1.8. Set extra_id_pv parameter
217 1.9. Set setid_avp parameter
218 1.10. Set force_send_interface parameter
219 1.11. Set read_sdp_pv parameter
220 1.12. Set write_sdp_pv parameter
221 1.13. Set write_sdp_pv_mode parameter
222 1.14. Set rtp_inst_pvar parameter
223 1.15. Set hash_table_size parameter
224 1.16. Set hash_table_tout parameter
225 1.17. Set db_url parameter
226 1.18. Set table_name parameter
227 1.19. Se tup rtpengine table
228 1.20. Set setid_col parameter
229 1.21. Set url_col parameter
230 1.22. Set weight_col parameter
231 1.23. Set disabled_col parameter
232 1.24. Set setid_default parameter
233 1.25. Set media_duration parameter
234 1.26. Set mos_min_pv parameter
235 1.27. Set mos_min_at_pv parameter
236 1.28. Set mos_min_packetloss_pv parameter
237 1.29. Set mos_min_jitter_pv parameter
238 1.30. Set mos_min_roundtrip_pv parameter
239 1.31. Set mos_max_pv parameter
240 1.32. Set mos_max_at_pv parameter
241 1.33. Set mos_max_packetloss_pv parameter
242 1.34. Set mos_max_jitter_pv parameter
243 1.35. Set mos_max_roundtrip_pv parameter
244 1.36. Set mos_average_pv parameter
245 1.37. Set mos_average_packetloss_pv parameter
246 1.38. Set mos_average_jitter_pv parameter
247 1.39. Set mos_average_roundtrip_pv parameter
248 1.40. Set mos_average_samples_pv parameter
249 1.41. Set mos_A_label_pv parameter
250 1.42. Set mos_min_A_pv parameter
251 1.43. Set mos_min_at_A_pv parameter
252 1.44. Set mos_min_packetloss_A_pv parameter
253 1.45. Set mos_min_jitter_A_pv parameter
254 1.46. Set mos_min_roundtrip_A_pv parameter
255 1.47. Set mos_min_roundtrip_leg_A_pv parameter
256 1.48. Set mos_max_A_pv parameter
257 1.49. Set mos_max_at_A_pv parameter
258 1.50. Set mos_max_packetloss_A_pv parameter
259 1.51. Set mos_max_jitter_A_pv parameter
260 1.52. Set mos_max_roundtrip_A_pv parameter
261 1.53. Set mos_max_roundtrip_leg_A_pv parameter
262 1.54. Set mos_average_A_pv parameter
263 1.55. Set mos_average_packetloss_A_pv parameter
264 1.56. Set mos_average_jitter_A_pv parameter
265 1.57. Set mos_average_roundtrip_A_pv parameter
266 1.58. Set mos_average_roundtrip_leg_A_pv parameter
267 1.59. Set mos_average_samples_A_pv parameter
268 1.60. Set mos_B_label_pv parameter
269 1.61. Set mos_min_B_pv parameter
270 1.62. Set mos_min_at_B_pv parameter
271 1.63. Set mos_min_packetloss_B_pv parameter
272 1.64. Set mos_min_jitter_B_pv parameter
273 1.65. Set mos_min_roundtrip_B_pv parameter
274 1.66. Set mos_min_roundtrip_leg_B_pv parameter
275 1.67. Set mos_max_B_pv parameter
276 1.68. Set mos_max_at_B_pv parameter
277 1.69. Set mos_max_packetloss_B_pv parameter
278 1.70. Set mos_max_jitter_B_pv parameter
279 1.71. Set mos_max_roundtrip_B_pv parameter
280 1.72. Set mos_max_roundtrip_leg_B_pv parameter
281 1.73. Set mos_average_B_pv parameter
282 1.74. Set mos_average_packetloss_B_pv parameter
283 1.75. Set mos_average_jitter_B_pv parameter
284 1.76. Set mos_average_roundtrip_B_pv parameter
285 1.77. Set mos_average_roundtrip_leg_B_pv parameter
286 1.78. Set mos_average_samples_B_pv parameter
287 1.79. Set dtmf_event_callid parameter
288 1.80. Set dtmf_event_source_tag parameter
289 1.81. Set dtmf_event_timestamp parameter
290 1.82. Set dtmf_event parameter
291 1.83. Set control_cmd_tos parameter
292 1.84. Set hash_algo parameter
293 1.85. Set wsapi parameter
294 1.86. Set dtmf_events_sock parameter
295 1.87. Set ping_mode parameter
296 1.88. Set ping_interval parameter
297 1.89. Set enable_dmq parameter
298 1.90. set_rtpengine_set usage
299 1.91. rtpengine_offer usage
300 1.92. rtpengine_offer usage to force transcoding from opus to PCMU
301 1.93. rtpengine_offer usage of via-branch parameter
302 1.94. rtpengine_answer usage
303 1.95. rtpengine_info usage
304 1.96. rtpengine_delete usage
305 1.97. rtpengine_destroy usage
306 1.98. rtpengine_query usage
307 1.99. rtpengine_query_v usage
308 1.100. rtpengine_connect usage
309 1.101. rtpengine_manage usage
310 1.102. rtpengine_subscribe_request usage
311 1.103. rtpengine_subscribe_answer usage
312 1.104. rtpengine_unsubscribe usage
313 1.105. start_recording usage
314 1.106. stop_recording usage
315 1.107. block_dtmf usage
316 1.108. unblock_dtmf usage
317 1.109. block_media usage
318 1.110. unblock_media usage
319 1.111. silence_media usage
320 1.112. unsilence_media usage
321 1.113. start_forwarding usage
322 1.114. stop_forwarding usage
323 1.115. play_media usage
324 1.116. stop_media usage
325 1.117. play_dtmf usage
326 1.118. $rtpestat Usage
327 1.119. rtpengine.reload usage
328 1.120. rtpengine.enable usage
329 1.121. rtpengine.show usage
330 1.122. rtpengine.ping usage
331 1.123. rtpengine.get_hash_total usage
332
333 Chapter 1. Admin Guide
334
335 Table of Contents
336
337 1. Overview
338 2. Recommended Version
339 3. Usage With Multiple RTPEngine Instances
340 4. Dependencies
341
342 4.1. Kamailio Modules
343 4.2. External Libraries or Applications
344
345 5. Parameters
346
347 5.1. rtpengine_sock (string)
348 5.2. rtpengine_disable_tout (integer)
349 5.3. aggressive_redetection (integer)
350 5.4. rtpengine_tout_ms (integer)
351 5.5. rtpengine_allow_op (integer)
352 5.6. queried_nodes_limit (integer)
353 5.7. rtpengine_retr (integer)
354 5.8. extra_id_pv (string)
355 5.9. setid_avp (string)
356 5.10. force_send_interface (string)
357 5.11. read_sdp_pv (string)
358 5.12. write_sdp_pv (string)
359 5.13. write_sdp_pv_mode (int)
360 5.14. rtp_inst_pvar (string)
361 5.15. hash_table_size (integer)
362 5.16. hash_table_tout (integer)
363 5.17. db_url (string)
364 5.18. table_name (string)
365 5.19. setid_col (string)
366 5.20. url_col (string)
367 5.21. weight_col (string)
368 5.22. disabled_col (string)
369 5.23. setid_default (integer)
370 5.24. media_duration (string)
371 5.25. mos_min_pv (string)
372 5.26. mos_min_at_pv (string)
373 5.27. mos_min_packetloss_pv (string)
374 5.28. mos_min_jitter_pv (string)
375 5.29. mos_min_roundtrip_pv (string)
376 5.30. mos_max_pv (string)
377 5.31. mos_max_at_pv (string)
378 5.32. mos_max_packetloss_pv (string)
379 5.33. mos_max_jitter_pv (string)
380 5.34. mos_max_roundtrip_pv (string)
381 5.35. mos_average_pv (string)
382 5.36. mos_average_packetloss_pv (string)
383 5.37. mos_average_jitter_pv (string)
384 5.38. mos_average_roundtrip_pv (string)
385 5.39. mos_average_samples_pv (string)
386 5.40. mos_A_label_pv (string)
387 5.41. mos_min_A_pv (string)
388 5.42. mos_min_at_A_pv (string)
389 5.43. mos_min_packetloss_A_pv (string)
390 5.44. mos_min_jitter_A_pv (string)
391 5.45. mos_min_roundtrip_A_pv (string)
392 5.46. mos_min_roundtrip_leg_A_pv (string)
393 5.47. mos_max_A_pv (string)
394 5.48. mos_max_at_A_pv (string)
395 5.49. mos_max_packetloss_A_pv (string)
396 5.50. mos_max_jitter_A_pv (string)
397 5.51. mos_max_roundtrip_A_pv (string)
398 5.52. mos_max_roundtrip_leg_A_pv (string)
399 5.53. mos_average_A_pv (string)
400 5.54. mos_average_packetloss_A_pv (string)
401 5.55. mos_average_jitter_A_pv (string)
402 5.56. mos_average_roundtrip_A_pv (string)
403 5.57. mos_average_roundtrip_leg_A_pv (string)
404 5.58. mos_average_samples_A_pv (string)
405 5.59. mos_B_label_pv (string)
406 5.60. mos_min_B_pv (string)
407 5.61. mos_min_at_B_pv (string)
408 5.62. mos_min_packetloss_B_pv (string)
409 5.63. mos_min_jitter_B_pv (string)
410 5.64. mos_min_roundtrip_B_pv (string)
411 5.65. mos_min_roundtrip_leg_B_pv (string)
412 5.66. mos_max_B_pv (string)
413 5.67. mos_max_at_B_pv (string)
414 5.68. mos_max_packetloss_B_pv (string)
415 5.69. mos_max_jitter_B_pv (string)
416 5.70. mos_max_roundtrip_B_pv (string)
417 5.71. mos_max_roundtrip_leg_B_pv (string)
418 5.72. mos_average_B_pv (string)
419 5.73. mos_average_packetloss_B_pv (string)
420 5.74. mos_average_jitter_B_pv (string)
421 5.75. mos_average_roundtrip_B_pv (string)
422 5.76. mos_average_roundtrip_leg_B_pv (string)
423 5.77. mos_average_samples_B_pv (string)
424 5.78. dtmf_event_callid (string)
425 5.79. dtmf_event_source_tag (string)
426 5.80. dtmf_event_timestamp (string)
427 5.81. dtmf_event (string)
428 5.82. control_cmd_tos (integer)
429 5.83. hash_algo (integer)
430 5.84. wsapi (string)
431 5.85. dtmf_events_sock (string)
432 5.86. ping_mode (integer)
433
434 6. ping_interval (integer)
435 7. enable_dmq (integer)
436 8. dtmf_event_source_label (str)
437 9. dtmf_event_tags (str)
438 10. dtmf_event_type (str)
439 11. dtmf_event_source_ip (str)
440 12. dtmf_event_duration (str)
441 13. dtmf_event_volume (str)
442 14. event_callback (str)
443 15. Functions
444
445 15.1. set_rtpengine_set(setid[, setid])
446 15.2. rtpengine_offer([flags][,via-branch])
447 15.3. rtpengine_answer([flags][,via-branch])
448 15.4. rtpengine_info([flags][,via-branch])
449 15.5. rtpengine_delete([flags][,via-branch])
450 15.6. rtpengine_destroy([flags][,via-branch])
451 15.7. rtpengine_query([flags][,via-branch])
452 15.8. rtpengine_query_v(fmt, var)
453 15.9. rtpengine_connect([flags][,via-branch])
454 15.10. rtpengine_manage([flags][,via-branch])
455 15.11.
456 rtpengine_subscribe_request(flags,sdp_avp,to_tag_avp,stream_
457 xavp[,via-branch])
458
459 15.12. rtpengine_subscribe_answer([flags][,via-branch])
460 15.13. rtpengine_unsubscribe([flags][,via-branch])
461 15.14. start_recording([flags])
462 15.15. stop_recording([flags])
463 15.16. block_dtmf([flags])
464 15.17. unblock_dtmf([flags])
465 15.18. block_media([flags])
466 15.19. unblock_media([flags])
467 15.20. silence_media([flags])
468 15.21. unsilence_media([flags])
469 15.22. start_forwarding([flags])
470 15.23. stop_forwarding([flags])
471 15.24. play_media([flags])
472 15.25. stop_media([flags])
473 15.26. play_dtmf([flags])
474
475 16. Exported Pseudo Variables
476
477 16.1. $rtpestat
478 16.2. $rtpstat
479
480 17. RPC Commands
481
482 17.1. rtpengine.reload
483 17.2. rtpengine.enable proxy_url/all 0/1
484 17.3. rtpengine.show proxy_url/all
485 17.4. rtpengine.ping proxy_url/all
486 17.5. rtpengine.get_hash_total
487
488 18. Event routes
489
490 18.1. rtpengine:dtmf-event
491
492 1. Overview
493
494 This is a module that enables media streams to be proxied via an RTP
495 proxy. The only RTP proxy currently known to work with this module is
496 Sipwise rtpengine. The rtpengine module is a modified version of the
497 original rtpproxy module using a new control protocol. The module is
498 designed to be a drop-in replacement for the old module from a
499 configuration file point of view, however due to the incompatible
500 control protocol, it only works with RTP proxies which specifically
501 support it.
502
503 2. Recommended Version
504
505 This control module is compatible with a wide range of versions of
506 Sipwise rtpengine. The version numbers follow the schema “mrXX.Y.ZZZ”,
507 with “XX” being the major release number, “Y” the minor release number,
508 and “ZZZ” the patch level suffix. Releases with “Y” equalling 5 are LTS
509 releases and receive bug fixes for several years. The recommended
510 version therefore is either the latest LTS release on the latest patch
511 level (e.g. “mr12.5.1.46”), or the latest non-LTS release if newer
512 features are desired (e.g. “mr13.4.1.5”). This version of Kamailio
513 includes a field in the control protocol which is not supported by
514 versions of rtpengine older than “mr12.4” and will trigger a warning
515 log message in these older versions. This is purely cosmetic.
516
517 3. Usage With Multiple RTPEngine Instances
518
519 The rtpengine module can support multiple RTPEngine instances for
520 balancing/distribution and control/selection purposes.
521
522 The module allows definition of several sets of RTPEngines.
523 Load-balancing will be performed over a set and the admin has the
524 ability to choose what set should be used. The set is selected via its
525 id - the id being defined with the set. Refer to the “rtpengine_sock”
526 module parameter definition for syntax description.
527
528 The balancing inside a set is done automatically by the module based on
529 the weight of each RTPEngine from the set. The default weight is 1, if
530 another RTPEngine should be used twice as often as the first one, one
531 would specify the weight 2 for this server, for example.
532
533 The selection of the set is done from script prior using
534 rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
535 rtpengine_manage() functions - see the set_rtpengine_set() function.
536
537 Another way to select the set is to define setid_avp module parameter
538 and assign setid to the defined avp before calling rtpengine_offer() or
539 rtpengine_manage() function. If forwarding of the requests fails and
540 there is another branch to try, remember to unset the avp after calling
541 rtpengine_delete() function.
542
543 For backward compatibility reasons, a set with no id take by default
544 the id 0. Also if no set is explicitly set before rtpengine_delete(),
545 rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
546
547 IMPORTANT: if you use multiple sets, take care and use the same set for
548 both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
549 the set was selected using setid_avp, the avp needs to be set only once
550 before rtpengine_offer() or rtpengine_manage() call.
551
552 From the current implementation point of view, the sets of rtpengine
553 nodes are in shared memory(shm), so all processes can see a common list
554 of nodes. There is no locking when setting the nodes enabled/disabled
555 (to keep the memory access as fast as possible). Thus, problems related
556 to node state might appear for concurrent processes that might set the
557 nodes enabled/disabled (e.g. by fifo command). These robustness
558 problems are overcome as follows.
559
560 If the current process sees the selected node as disabled, the node is
561 force tested before the current process actually accepts the disabled
562 state. If the test succeeds, the process will set the node as enabled
563 (but other concurrent process might still see it as disabled).
564
565 If the current process sees the selected node as enabled, it does no
566 additional checks and sends the command which will fail in case the
567 machine is actually broken. The process will set the node as disabled
568 (but other concurrent process might still see it as enabled).
569
570 The 'kamctl fifo' commands (including rtpengine ones) are executed by
571 an exclusive process which operate on the same shared memory node list.
572
573 All the nodes are pinged in the beginning by all the processes, even if
574 the node list is shared memory.
575
576 4. Dependencies
577
578 4.1. Kamailio Modules
579 4.2. External Libraries or Applications
580
581 4.1. Kamailio Modules
582
583 The following modules must be loaded before this module:
584 * tm module - (optional) if you want to have rtpengine_manage() fully
585 functional
586 * lwsc module - (optional) if you plan to use “wsapi” parameter
587
588 4.2. External Libraries or Applications
589
590 The following libraries or applications must be installed before
591 running Kamailio with this module loaded:
592 * None.
593
594 5. Parameters
595
596 5.1. rtpengine_sock (string)
597 5.2. rtpengine_disable_tout (integer)
598 5.3. aggressive_redetection (integer)
599 5.4. rtpengine_tout_ms (integer)
600 5.5. rtpengine_allow_op (integer)
601 5.6. queried_nodes_limit (integer)
602 5.7. rtpengine_retr (integer)
603 5.8. extra_id_pv (string)
604 5.9. setid_avp (string)
605 5.10. force_send_interface (string)
606 5.11. read_sdp_pv (string)
607 5.12. write_sdp_pv (string)
608 5.13. write_sdp_pv_mode (int)
609 5.14. rtp_inst_pvar (string)
610 5.15. hash_table_size (integer)
611 5.16. hash_table_tout (integer)
612 5.17. db_url (string)
613 5.18. table_name (string)
614 5.19. setid_col (string)
615 5.20. url_col (string)
616 5.21. weight_col (string)
617 5.22. disabled_col (string)
618 5.23. setid_default (integer)
619 5.24. media_duration (string)
620 5.25. mos_min_pv (string)
621 5.26. mos_min_at_pv (string)
622 5.27. mos_min_packetloss_pv (string)
623 5.28. mos_min_jitter_pv (string)
624 5.29. mos_min_roundtrip_pv (string)
625 5.30. mos_max_pv (string)
626 5.31. mos_max_at_pv (string)
627 5.32. mos_max_packetloss_pv (string)
628 5.33. mos_max_jitter_pv (string)
629 5.34. mos_max_roundtrip_pv (string)
630 5.35. mos_average_pv (string)
631 5.36. mos_average_packetloss_pv (string)
632 5.37. mos_average_jitter_pv (string)
633 5.38. mos_average_roundtrip_pv (string)
634 5.39. mos_average_samples_pv (string)
635 5.40. mos_A_label_pv (string)
636 5.41. mos_min_A_pv (string)
637 5.42. mos_min_at_A_pv (string)
638 5.43. mos_min_packetloss_A_pv (string)
639 5.44. mos_min_jitter_A_pv (string)
640 5.45. mos_min_roundtrip_A_pv (string)
641 5.46. mos_min_roundtrip_leg_A_pv (string)
642 5.47. mos_max_A_pv (string)
643 5.48. mos_max_at_A_pv (string)
644 5.49. mos_max_packetloss_A_pv (string)
645 5.50. mos_max_jitter_A_pv (string)
646 5.51. mos_max_roundtrip_A_pv (string)
647 5.52. mos_max_roundtrip_leg_A_pv (string)
648 5.53. mos_average_A_pv (string)
649 5.54. mos_average_packetloss_A_pv (string)
650 5.55. mos_average_jitter_A_pv (string)
651 5.56. mos_average_roundtrip_A_pv (string)
652 5.57. mos_average_roundtrip_leg_A_pv (string)
653 5.58. mos_average_samples_A_pv (string)
654 5.59. mos_B_label_pv (string)
655 5.60. mos_min_B_pv (string)
656 5.61. mos_min_at_B_pv (string)
657 5.62. mos_min_packetloss_B_pv (string)
658 5.63. mos_min_jitter_B_pv (string)
659 5.64. mos_min_roundtrip_B_pv (string)
660 5.65. mos_min_roundtrip_leg_B_pv (string)
661 5.66. mos_max_B_pv (string)
662 5.67. mos_max_at_B_pv (string)
663 5.68. mos_max_packetloss_B_pv (string)
664 5.69. mos_max_jitter_B_pv (string)
665 5.70. mos_max_roundtrip_B_pv (string)
666 5.71. mos_max_roundtrip_leg_B_pv (string)
667 5.72. mos_average_B_pv (string)
668 5.73. mos_average_packetloss_B_pv (string)
669 5.74. mos_average_jitter_B_pv (string)
670 5.75. mos_average_roundtrip_B_pv (string)
671 5.76. mos_average_roundtrip_leg_B_pv (string)
672 5.77. mos_average_samples_B_pv (string)
673 5.78. dtmf_event_callid (string)
674 5.79. dtmf_event_source_tag (string)
675 5.80. dtmf_event_timestamp (string)
676 5.81. dtmf_event (string)
677 5.82. control_cmd_tos (integer)
678 5.83. hash_algo (integer)
679 5.84. wsapi (string)
680 5.85. dtmf_events_sock (string)
681 5.86. ping_mode (integer)
682
683 5.1. rtpengine_sock (string)
684
685 Definition of socket(s) used to connect to (a set) RTP proxy. It may
686 specify an IPv4/IPv6 UDP socket or a websocket URI.
687
688 Default value is “NONE” (disabled).
689
690 Example 1.1. Set rtpengine_sock parameter
691 ...
692 # single rtproxy
693 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
694 # IPv6 UDP
695 modparam("rtpengine", "rtpengine_sock", "udp6:localhost:12221")
696 # websocket
697 modparam("rtpengine", "rtpengine_sock", "ws://localhost:12221/")
698 # websocket with TLS
699 modparam("rtpengine", "rtpengine_sock", "wss://localhost:12221/")
700 # multiple rtproxies for LB with weights (missing weight defaults to 1)
701 modparam("rtpengine", "rtpengine_sock",
702 "udp:localhost:12221=2 udp:localhost:12222=1")
703 # multiple sets of multiple rtproxies
704 modparam("rtpengine", "rtpengine_sock",
705 "1 == udp:localhost:12221 udp:localhost:12222")
706 modparam("rtpengine", "rtpengine_sock",
707 "2 == udp:localhost:12225")
708 ...
709
710 5.2. rtpengine_disable_tout (integer)
711
712 Once an RTP proxy was found unreachable and marked as disabled, the
713 rtpengine module will not attempt to establish communication to that
714 RTP proxy for rtpengine_disable_tout seconds.
715
716 Default value is “60”.
717
718 Can be set at runtime, e.g.:
719 $ kamcmd cfg.set_now_int rtpengine rtpengine_disable_tou
720 t 20
721
722 Example 1.2. Set rtpengine_disable_tout parameter
723 ...
724 modparam("rtpengine", "rtpengine_disable_tout", 20)
725 ...
726
727 5.3. aggressive_redetection (integer)
728
729 This parameter determines what happens when all potential rtpengines
730 are found to be unreachable. If enabled, the sip server will send pings
731 to all rtpengines, else no rtpengine will be queried until its
732 rtpengine_disable_tout timeout passes.
733
734 Default value is “0” (disabled).
735
736 Can be set at runtime, e.g.:
737 $ kamcmd cfg.set_now_int rtpengine aggressive_redetectio
738 n 1
739
740 Example 1.3. Set aggressive_redetection parameter
741 ...
742 modparam("rtpengine", "aggressive_redetection", 1)
743 ...
744
745 5.4. rtpengine_tout_ms (integer)
746
747 Timeout value expressed in milliseconds in waiting for reply from RTP
748 proxy.
749
750 Default value is “1000”.
751
752 Can be set at runtime, e.g.:
753 $ kamcmd cfg.set_now_int rtpengine rtpengine_tout_ms 100
754 0
755
756 Example 1.4. Set rtpengine_tout_ms parameter
757 ...
758 modparam("rtpengine", "rtpengine_tout_ms", 2000)
759 ...
760
761 5.5. rtpengine_allow_op (integer)
762
763 Enable this setting to allow finishing the current sessions while
764 denying new sessions for deactivated nodes.
765
766 Nodes can be manually deactivated via kamctl command i.e.
767 "disabled(permanent)" nodes. Probably the manually deactivated machine
768 is still running (did not crash).
769
770 This is useful when deactivating a node for maintenance and reject new
771 sessions but allow current ones to finish.
772
773 The behaviour is the same for a rtpengine deleted table node. When the
774 node is deleted from the table and the table reloaded (see
775 nh_reload_rtpp) the node actually is disabled(permanent) and hidden for
776 display. Next time the same node will be added in the table, and the
777 database content reloaded, the re-activated node will be updated and
778 re-displayed.
779
780 Default value is “0” to keep the current behaviour.
781
782 If value set to “1” it will send commands to all disabled nodes for the
783 existing call.
784
785 If value set to “2” it will send commands only to manually disabled
786 nodes. (Not when timeout is disabled or node broken)
787
788 Example 1.5. Set rtpengine_allow_op parameter
789 ...
790 modparam("rtpengine", "rtpengine_allow_op", 1)
791 ...
792
793 5.6. queried_nodes_limit (integer)
794
795 The total number of nodes inside a set (sets are configurable via
796 rtpengine_sock function) to be queried before giving up establishing a
797 session. This brings more flexibility in case checking all rtpengines
798 would take too long. Max limit is 30.
799
800 By default all nodes in a set are tried before giving up communicating
801 with the rtpengines.
802
803 Can be set at runtime, e.g.:
804 $ kamcmd cfg.set_now_int rtpengine queried_nodes_limit 5
805
806 Example 1.6. Set queried_nodes_limit parameter
807 ...
808 modparam("rtpengine", "queried_nodes_limit", 5)
809 ...
810
811 5.7. rtpengine_retr (integer)
812
813 How many times the module should retry to send and receive after
814 timeout was generated.
815
816 Default value is “5”.
817
818 Can be set at runtime, e.g.:
819 $ kamcmd cfg.set_now_int rtpengine rtpengine_retr 5
820
821 Example 1.7. Set rtpengine_retr parameter
822 ...
823 modparam("rtpengine", "rtpengine_retr", 2)
824 ...
825
826 5.8. extra_id_pv (string)
827
828 The parameter sets the PV definition to use when the “via-branch”
829 parameter is used on rtpengine_delete(), rtpengine_offer(),
830 rtpengine_answer() or rtpengine_manage() command.
831
832 Default is empty, the “via-branch” parameter may not be used then.
833
834 Example 1.8. Set extra_id_pv parameter
835 ...
836 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
837 ...
838
839 5.9. setid_avp (string)
840
841 The parameter defines an AVP that, if set, determines which RTP proxy
842 set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
843 rtpengine_manage() functions use.
844
845 There is no default value.
846
847 Example 1.9. Set setid_avp parameter
848 ...
849 modparam("rtpengine", "setid_avp", "$avp(setid)")
850 ...
851
852 5.10. force_send_interface (string)
853
854 Forces all control messages between the SIP proxy and the RTP proxy to
855 be sent from the specified local interface. Both IPv4 and IPv6
856 addresses are supported. If not specified, the default interface
857 selected by the operating system will be used. Note: when
858 rtpengine_sock is an IPv6 link-local address, one _must_ set this
859 parameter in order to successfully connect to RTP engine. This is
860 necessarily because OS needs additional scope_id hint to communicate
861 over IPv6 link locals. The scope_id is resolved based on the given
862 IPv6.
863
864 There is no default value.
865
866 Example 1.10. Set force_send_interface parameter
867 ...
868 modparam("rtpengine", "force_send_interface", "10.3.7.123")
869 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
870 fd99")
871 ...
872
873 5.11. read_sdp_pv (string)
874
875 If this parameter is set to a valid AVP or script var specifier,
876 rtpengine will take the input SDP from this pv instead of the message
877 body.
878
879 There is no default value.
880
881 Example 1.11. Set read_sdp_pv parameter
882 ...
883 modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
884 ...
885 request_route {
886 ...
887 $var(sdp) = $rb + "a=foo:bar\r\n";
888 rtpengine_manage();
889 }
890
891 5.12. write_sdp_pv (string)
892
893 If this parameter is set to a valid AVP or script var specifier, the
894 SDP returned by rtpengine in the offer/answer operations is returned in
895 the specified variable instead of the message body.
896
897 There is no default value.
898
899 Example 1.12. Set write_sdp_pv parameter
900 ...
901 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
902 ...
903 request_route {
904 ...
905 rtpengine_manage();
906 set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
907 }
908
909 5.13. write_sdp_pv_mode (int)
910
911 If this parameter is set to 1, the returned SDP is written to pv and
912 also set to message body.
913
914 Default value: 0 (write SDP only to pv).
915
916 Example 1.13. Set write_sdp_pv_mode parameter
917 ...
918 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
919 modparam("rtpengine", "write_sdp_pv_mode", 1)
920 ...
921 request_route {
922 ...
923 rtpengine_manage();
924 xinfo("new sdp: $avp(sdp)\n");
925 }
926
927 5.14. rtp_inst_pvar (string)
928
929 A pseudo variable to store the chosen RTP Engine URI. If this parameter
930 is set, the URI of the instance chosen will be stored in the given
931 variable.
932
933 By default, this parameter is not set.
934
935 Example 1.14. Set rtp_inst_pvar parameter
936 ...
937 modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
938 ...
939
940 5.15. hash_table_size (integer)
941
942 To maintain information about a selected rtp machine node for a given
943 call, entries are added in a hashtable of (callid, node) pairs. This
944 parameter sets the size of the hash table. Default value is 256.
945
946 NOTE: If configured size is less than 1, the size will be defaulted to
947 1.
948
949 Example 1.15. Set hash_table_size parameter
950 ...
951 modparam("rtpengine", "hash_table_size", 123)
952 ...
953
954 5.16. hash_table_tout (integer)
955
956 Number of seconds after an rtpengine hash table entry is marked for
957 deletion. By default, this parameter is set to 3600 (seconds).
958
959 To maintain information about a selected rtp machine node for a given
960 call, entries are added in a hashtable of (callid, node) pairs. When
961 command comes the callid is looked up in this table. If found, the
962 chosen node is used. If not found, choose a new node, insert the callid
963 in the hashtable and return the chosen node.
964
965 NOTE: In the current implementation, the actual deletion happens on the
966 fly, while insert/remove/lookup the hastable, only for the entries in
967 the insert/remove/lookup path.
968
969 NOTE: When configuring this parameter, one should consider maximum call
970 time VS shared memory for unfinished calls.
971
972 Example 1.16. Set hash_table_tout parameter
973 ...
974 modparam("rtpengine", "hash_table_tout", 300)
975 ...
976
977 5.17. db_url (string)
978
979 The rtpengine database url. If present and valid, it activates database
980 mode. In this mode the node information is read from database, not from
981 configuration modparam parameters.
982
983 By default, the database url is NULL (not set).
984
985 Example 1.17. Set db_url parameter
986 ...
987 modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
988 ...
989
990 5.18. table_name (string)
991
992 The rtpengine table name. If database mode is activated (i.e. valid
993 db_url), sets the name of the rtpengine table, on startup.
994
995 By default, the rtpengine table name is "rtpengine".
996
997 NOTE: One needs to add the version of the rtpengine table in the
998 version table. The current version is version 1.
999
1000 Example 1.18. Set table_name parameter
1001 ...
1002 modparam("rtpengine", "table_name", "rtpengine_table_name")
1003 ...
1004
1005 Example 1.19. Se tup rtpengine table
1006 mysql> describe rtpengine;
1007 +----------+------------------+------+-----+---------------------+-------+
1008 | Field | Type | Null | Key | Default | Extra |
1009 +----------+------------------+------+-----+---------------------+-------+
1010 | setid | int(10) unsigned | NO | PRI | 0 | |
1011 | url | varchar(64) | NO | PRI | NULL | |
1012 | weight | int(10) unsigned | NO | | 1 | |
1013 | disabled | int(1) | NO | | 0 | |
1014 | stamp | datetime | NO | | 1900-01-01 00:00:01 | |
1015 +----------+------------------+------+-----+---------------------+-------+
1016
1017 mysql> select * from rtpengine;
1018 +-------+----------------------------+--------+----------+---------------------+
1019 | setid | url | weight | disabled | stamp |
1020 +-------+----------------------------+--------+----------+---------------------+
1021 | 0 | udp:rtpengine1.domain:8800 | 1 | 0 | 2016-03-10 10:30:54 |
1022 | 0 | udp:rtpengine2.domain:8800 | 1 | 1 | 2016-03-10 10:30:54 |
1023 +-------+----------------------------+--------+----------+---------------------+
1024
1025 mysql> select * from version;
1026 +---------------------------+---------------+
1027 | table_name | table_version |
1028 +---------------------------+---------------+
1029 | rtpengine | 1 |
1030 +---------------------------+---------------+
1031
1032 5.19. setid_col (string)
1033
1034 Column name for the "setid" in the rtpengine table. If database mode is
1035 activated (i.e. valid db_url), set the setid of rtp nodes according to
1036 this column, on startup. The MySQL value for this column should be INT
1037 UNSIGNED.
1038
1039 By default, the column name is "setid".
1040
1041 Example 1.20. Set setid_col parameter
1042 ...
1043 modparam("rtpengine", "setid_col", "setid_column_name")
1044 ...
1045
1046 5.20. url_col (string)
1047
1048 Column name for the url in the rtpengine table. If database mode is
1049 activated (i.e. valid db_url), set the url of rtp nodes according to
1050 this column, on startup. The MySQL value for this column should be
1051 VARCHAR.
1052
1053 By default, the column name is "url".
1054
1055 Example 1.21. Set url_col parameter
1056 ...
1057 modparam("rtpengine", "url_col", "url_column_name")
1058 ...
1059
1060 5.21. weight_col (string)
1061
1062 Column name for weight in the rtpengine table. If database mode is
1063 activated (i.e. valid db_url), set the weight of rtp nodes according to
1064 this column, on startup. The column value has priority over the URL
1065 weight. The MySQL value for this column should be INT UNSIGNED.
1066
1067 By default, the column name is "weight".
1068
1069 Example 1.22. Set weight_col parameter
1070 ...
1071 modparam("rtpengine", "weight_col", "weight_column_name")
1072 ...
1073
1074 5.22. disabled_col (string)
1075
1076 Column name in the rtpengine table. If database mode is activated (i.e.
1077 valid db_url), set the state of rtp nodes according to this column, on
1078 startup. The MySQL value for this column should be INT.
1079
1080 By default, the column name is "disabled".
1081
1082 Example 1.23. Set disabled_col parameter
1083 ...
1084 modparam("rtpengine", "disabled_col", "disabled_column_name")
1085 ...
1086
1087 5.23. setid_default (integer)
1088
1089 The default set of nodes to be used.
1090
1091 By default, the setid is 0.
1092
1093 NOTE that if setid_avp is configured, this value will be ignored and
1094 the active set will be chosen according to the setid_avp.
1095
1096 Example 1.24. Set setid_default parameter
1097 ...
1098 modparam("rtpengine", "setid_default", 11)
1099 ...
1100
1101 5.24. media_duration (string)
1102
1103 The name of a pseudovariable to be filled in with the length of the
1104 media being played back after a call to “play_media”, expressed in
1105 milliseconds. It's set to -1 if the length of the media could not be
1106 determined.
1107
1108 By default, this parameter is not set.
1109
1110 Example 1.25. Set media_duration parameter
1111 ...
1112 modparam("rtpengine", "media_duration", "$avp(MEDIA_DURATION)")
1113 ...
1114
1115 5.25. mos_min_pv (string)
1116
1117 The name of a pseudovariable to hold the minimum encountered MOS (Mean
1118 Opinion Score) value for the call. The value typically has a range of
1119 1.0 through 5.0.
1120
1121 There is no default value.
1122
1123 This value is filled in after invoking “rtpengine_delete”,
1124 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1125 deletion of the call (or call branch).
1126
1127 Example 1.26. Set mos_min_pv parameter
1128 ...
1129 modparam("rtpengine", "mos_min_pv", "$avp(mos_min)")
1130 ...
1131
1132 5.26. mos_min_at_pv (string)
1133
1134 The name of a pseudovariable to hold the timestamp of when the minimum
1135 MOS value was encountered during the call, such as “0:30” for 30
1136 seconds after the start of the call.
1137
1138 There is no default value.
1139
1140 This value is filled in after invoking “rtpengine_delete”,
1141 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1142 deletion of the call (or call branch).
1143
1144 Example 1.27. Set mos_min_at_pv parameter
1145 ...
1146 modparam("rtpengine", "mos_min_at_pv", "$avp(mos_min_at)")
1147 ...
1148
1149 5.27. mos_min_packetloss_pv (string)
1150
1151 The name of a pseudovariable to hold the amount of packetloss in
1152 percent at the time the minimum MOS value was encountered;
1153
1154 There is no default value.
1155
1156 This value is filled in after invoking “rtpengine_delete”,
1157 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1158 deletion of the call (or call branch).
1159
1160 Example 1.28. Set mos_min_packetloss_pv parameter
1161 ...
1162 modparam("rtpengine", "mos_min_packetloss_pv", "$avp(mos_min_packetloss)")
1163 ...
1164
1165 5.28. mos_min_jitter_pv (string)
1166
1167 The name of a pseudovariable to hold the amount of jitter in
1168 milliseconds at the time the minimum MOS value was encountered;
1169
1170 There is no default value.
1171
1172 This value is filled in after invoking “rtpengine_delete”,
1173 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1174 deletion of the call (or call branch).
1175
1176 Example 1.29. Set mos_min_jitter_pv parameter
1177 ...
1178 modparam("rtpengine", "mos_min_jitter_pv", "$avp(mos_min_jitter)")
1179 ...
1180
1181 5.29. mos_min_roundtrip_pv (string)
1182
1183 The name of a pseudovariable to hold the packet round-trip time in
1184 microseconds at the time the minimum MOS value was encountered;
1185
1186 There is no default value.
1187
1188 This value is filled in after invoking “rtpengine_delete”,
1189 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1190 deletion of the call (or call branch).
1191
1192 Example 1.30. Set mos_min_roundtrip_pv parameter
1193 ...
1194 modparam("rtpengine", "mos_min_roundtrip_pv", "$avp(mos_min_roundtrip)")
1195 ...
1196
1197 5.30. mos_max_pv (string)
1198
1199 The name of a pseudovariable to hold the maximum encountered MOS value
1200 for the call. The value typically has a range of 1.0 through 5.0.
1201
1202 There is no default value.
1203
1204 This value is filled in after invoking “rtpengine_delete”,
1205 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1206 deletion of the call (or call branch).
1207
1208 Example 1.31. Set mos_max_pv parameter
1209 ...
1210 modparam("rtpengine", "mos_max_pv", "$avp(mos_max)")
1211 ...
1212
1213 5.31. mos_max_at_pv (string)
1214
1215 The name of a pseudovariable to hold the timestamp of when the maximum
1216 MOS value was encountered during the call, such as “0:30” for 30
1217 seconds after the start of the call.
1218
1219 There is no default value.
1220
1221 This value is filled in after invoking “rtpengine_delete”,
1222 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1223 deletion of the call (or call branch).
1224
1225 Example 1.32. Set mos_max_at_pv parameter
1226 ...
1227 modparam("rtpengine", "mos_max_at_pv", "$avp(mos_max_at)")
1228 ...
1229
1230 5.32. mos_max_packetloss_pv (string)
1231
1232 The name of a pseudovariable to hold the amount of packetloss in
1233 percent at the time the maximum MOS value was encountered;
1234
1235 There is no default value.
1236
1237 This value is filled in after invoking “rtpengine_delete”,
1238 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1239 deletion of the call (or call branch).
1240
1241 Example 1.33. Set mos_max_packetloss_pv parameter
1242 ...
1243 modparam("rtpengine", "mos_max_packetloss_pv", "$avp(mos_max_packetloss)")
1244 ...
1245
1246 5.33. mos_max_jitter_pv (string)
1247
1248 The name of a pseudovariable to hold the amount of jitter in
1249 milliseconds at the time the maximum MOS value was encountered;
1250
1251 There is no default value.
1252
1253 This value is filled in after invoking “rtpengine_delete”,
1254 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1255 deletion of the call (or call branch).
1256
1257 Example 1.34. Set mos_max_jitter_pv parameter
1258 ...
1259 modparam("rtpengine", "mos_max_jitter_pv", "$avp(mos_max_jitter)")
1260 ...
1261
1262 5.34. mos_max_roundtrip_pv (string)
1263
1264 The name of a pseudovariable to hold the packet round-trip time in
1265 microseconds at the time the maximum MOS value was encountered;
1266
1267 There is no default value.
1268
1269 This value is filled in after invoking “rtpengine_delete”,
1270 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1271 deletion of the call (or call branch).
1272
1273 Example 1.35. Set mos_max_roundtrip_pv parameter
1274 ...
1275 modparam("rtpengine", "mos_max_roundtrip_pv", "$avp(mos_max_roundtrip)")
1276 ...
1277
1278 5.35. mos_average_pv (string)
1279
1280 The name of a pseudovariable to hold the average (median) MOS value for
1281 the call. The value typically has a range of 1.0 through 5.0.
1282
1283 There is no default value.
1284
1285 This value is filled in after invoking “rtpengine_delete”,
1286 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1287 deletion of the call (or call branch).
1288
1289 Example 1.36. Set mos_average_pv parameter
1290 ...
1291 modparam("rtpengine", "mos_average_pv", "$avp(mos_average)")
1292 ...
1293
1294 5.36. mos_average_packetloss_pv (string)
1295
1296 The name of a pseudovariable to hold the average (median) amount of
1297 packetloss in percent present throughout the call.
1298
1299 There is no default value.
1300
1301 This value is filled in after invoking “rtpengine_delete”,
1302 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1303 deletion of the call (or call branch).
1304
1305 Example 1.37. Set mos_average_packetloss_pv parameter
1306 ...
1307 modparam("rtpengine", "mos_average_packetloss_pv", "$avp(mos_average_packetloss)
1308 ")
1309 ...
1310
1311 5.37. mos_average_jitter_pv (string)
1312
1313 The name of a pseudovariable to hold the average (median) amount of
1314 jitter in milliseconds present throughout the call.
1315
1316 There is no default value.
1317
1318 This value is filled in after invoking “rtpengine_delete”,
1319 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1320 deletion of the call (or call branch).
1321
1322 Example 1.38. Set mos_average_jitter_pv parameter
1323 ...
1324 modparam("rtpengine", "mos_average_jitter_pv", "$avp(mos_average_jitter)")
1325 ...
1326
1327 5.38. mos_average_roundtrip_pv (string)
1328
1329 The name of a pseudovariable to hold the average (median) packet
1330 round-trip time in milliseconds present throughout the call.
1331
1332 There is no default value.
1333
1334 This value is filled in after invoking “rtpengine_delete”,
1335 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1336 deletion of the call (or call branch).
1337
1338 Example 1.39. Set mos_average_roundtrip_pv parameter
1339 ...
1340 modparam("rtpengine", "mos_average_roundtrip_pv", "$avp(mos_average_roundtrip)")
1341 ...
1342
1343 5.39. mos_average_samples_pv (string)
1344
1345 The name of a pseudovariable to hold the number of samples used to
1346 determine the other “average” MOS data points.
1347
1348 There is no default value.
1349
1350 This value is filled in after invoking “rtpengine_delete”,
1351 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1352 deletion of the call (or call branch).
1353
1354 Example 1.40. Set mos_average_samples_pv parameter
1355 ...
1356 modparam("rtpengine", "mos_average_samples_pv", "$avp(mos_average_samples)")
1357 ...
1358
1359 5.40. mos_A_label_pv (string)
1360
1361 The name of a pseudovariable to hold a custom label used in rtpengine
1362 signalling. If set, all the statistics pseudovariables with the “_A”
1363 suffix will be filled in with statistics only from the call legs that
1364 match the label given in this variable. You need to fill this variable
1365 before invoking “rtpengine_delete”, “rtpengine_query”, or
1366 “rtpengine_manage”. Variable value should match the label= flag on
1367 “rtpengine_offer”, “rtpengine_answer”, or “rtpengine_manage”.
1368
1369 There is no default value.
1370
1371 Example 1.41. Set mos_A_label_pv parameter
1372 ...
1373 modparam("rtpengine", "mos_A_label_pv", "$avp(mos_A_label)")
1374 ...
1375
1376 5.41. mos_min_A_pv (string)
1377
1378 The name of a pseudovariable to hold the minimum encountered MOS value
1379 for the call. The value typically has a range of 1.0 through 5.0.
1380
1381 There is no default value.
1382
1383 This value is filled in after invoking “rtpengine_delete”,
1384 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1385 deletion of the call (or call branch).
1386
1387 Only call legs matching the rtpengine label given in the
1388 “mos_A_label_pv” will be used in calculating this statistics value.
1389
1390 Example 1.42. Set mos_min_A_pv parameter
1391 ...
1392 modparam("rtpengine", "mos_min_A_pv", "$avp(mos_min_A)")
1393 ...
1394
1395 5.42. mos_min_at_A_pv (string)
1396
1397 The name of a pseudovariable to hold the timestamp of when the minimum
1398 MOS value was encountered during the call, such as “0:30” for 30
1399 seconds after the start of the call.
1400
1401 There is no default value.
1402
1403 This value is filled in after invoking “rtpengine_delete”,
1404 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1405 deletion of the call (or call branch).
1406
1407 Only call legs matching the rtpengine label given in the
1408 “mos_A_label_pv” will be used in calculating this statistics value.
1409
1410 Example 1.43. Set mos_min_at_A_pv parameter
1411 ...
1412 modparam("rtpengine", "mos_min_at_A_pv", "$avp(mos_min_at_A)")
1413 ...
1414
1415 5.43. mos_min_packetloss_A_pv (string)
1416
1417 The name of a pseudovariable to hold the amount of packetloss in
1418 percent at the time the minimum MOS value was encountered;
1419
1420 There is no default value.
1421
1422 This value is filled in after invoking “rtpengine_delete”,
1423 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1424 deletion of the call (or call branch).
1425
1426 Only call legs matching the rtpengine label given in the
1427 “mos_A_label_pv” will be used in calculating this statistics value.
1428
1429 Example 1.44. Set mos_min_packetloss_A_pv parameter
1430 ...
1431 modparam("rtpengine", "mos_min_packetloss_A_pv", "$avp(mos_min_packetloss_A)")
1432 ...
1433
1434 5.44. mos_min_jitter_A_pv (string)
1435
1436 The name of a pseudovariable to hold the amount of jitter in
1437 milliseconds at the time the minimum MOS value was encountered;
1438
1439 There is no default value.
1440
1441 This value is filled in after invoking “rtpengine_delete”,
1442 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1443 deletion of the call (or call branch).
1444
1445 Only call legs matching the rtpengine label given in the
1446 “mos_A_label_pv” will be used in calculating this statistics value.
1447
1448 Example 1.45. Set mos_min_jitter_A_pv parameter
1449 ...
1450 modparam("rtpengine", "mos_min_jitter_A_pv", "$avp(mos_min_jitter_A)")
1451 ...
1452
1453 5.45. mos_min_roundtrip_A_pv (string)
1454
1455 The name of a pseudovariable to hold the packet round-trip time in
1456 microseconds at the time the minimum MOS value was encountered;
1457
1458 There is no default value.
1459
1460 This value is filled in after invoking “rtpengine_delete”,
1461 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1462 deletion of the call (or call branch).
1463
1464 Only call legs matching the rtpengine label given in the
1465 “mos_A_label_pv” will be used in calculating this statistics value.
1466
1467 Example 1.46. Set mos_min_roundtrip_A_pv parameter
1468 ...
1469 modparam("rtpengine", "mos_min_roundtrip_A_pv", "$avp(mos_min_roundtrip_A)")
1470 ...
1471
1472 5.46. mos_min_roundtrip_leg_A_pv (string)
1473
1474 The name of a pseudovariable to hold the packet round-trip time of the
1475 specific call leg in microseconds at the time the minimum MOS value was
1476 encountered;
1477
1478 There is no default value.
1479
1480 This value is filled in after invoking “rtpengine_delete”,
1481 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1482 deletion of the call (or call branch).
1483
1484 Only call legs matching the rtpengine label given in the
1485 “mos_A_label_pv” will be used in calculating this statistics value.
1486
1487 Example 1.47. Set mos_min_roundtrip_leg_A_pv parameter
1488 ...
1489 modparam("rtpengine", "mos_min_roundtrip_leg_A_pv", "$avp(mos_min_roundtrip_leg_
1490 A)")
1491 ...
1492
1493 5.47. mos_max_A_pv (string)
1494
1495 The name of a pseudovariable to hold the maximum encountered MOS value
1496 for the call. The value typically has a range of 1.0 through 5.0.
1497
1498 There is no default value.
1499
1500 This value is filled in after invoking “rtpengine_delete”,
1501 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1502 deletion of the call (or call branch).
1503
1504 Only call legs matching the rtpengine label given in the
1505 “mos_A_label_pv” will be used in calculating this statistics value.
1506
1507 Example 1.48. Set mos_max_A_pv parameter
1508 ...
1509 modparam("rtpengine", "mos_max_A_pv", "$avp(mos_max_A)")
1510 ...
1511
1512 5.48. mos_max_at_A_pv (string)
1513
1514 The name of a pseudovariable to hold the timestamp of when the maximum
1515 MOS value was encountered during the call, such as “0:30” for 30
1516 seconds after the start of the call.
1517
1518 There is no default value.
1519
1520 This value is filled in after invoking “rtpengine_delete”,
1521 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1522 deletion of the call (or call branch).
1523
1524 Only call legs matching the rtpengine label given in the
1525 “mos_A_label_pv” will be used in calculating this statistics value.
1526
1527 Example 1.49. Set mos_max_at_A_pv parameter
1528 ...
1529 modparam("rtpengine", "mos_max_at_A_pv", "$avp(mos_max_at_A)")
1530 ...
1531
1532 5.49. mos_max_packetloss_A_pv (string)
1533
1534 The name of a pseudovariable to hold the amount of packetloss in
1535 percent at the time the maximum MOS value was encountered;
1536
1537 There is no default value.
1538
1539 This value is filled in after invoking “rtpengine_delete”,
1540 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1541 deletion of the call (or call branch).
1542
1543 Only call legs matching the rtpengine label given in the
1544 “mos_A_label_pv” will be used in calculating this statistics value.
1545
1546 Example 1.50. Set mos_max_packetloss_A_pv parameter
1547 ...
1548 modparam("rtpengine", "mos_max_packetloss_A_pv", "$avp(mos_max_packetloss_A)")
1549 ...
1550
1551 5.50. mos_max_jitter_A_pv (string)
1552
1553 The name of a pseudovariable to hold the amount of jitter in
1554 milliseconds at the time the maximum MOS value was encountered;
1555
1556 There is no default value.
1557
1558 This value is filled in after invoking “rtpengine_delete”,
1559 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1560 deletion of the call (or call branch).
1561
1562 Only call legs matching the rtpengine label given in the
1563 “mos_A_label_pv” will be used in calculating this statistics value.
1564
1565 Example 1.51. Set mos_max_jitter_A_pv parameter
1566 ...
1567 modparam("rtpengine", "mos_max_jitter_A_pv", "$avp(mos_max_jitter_A)")
1568 ...
1569
1570 5.51. mos_max_roundtrip_A_pv (string)
1571
1572 The name of a pseudovariable to hold the packet round-trip time in
1573 microseconds at the time the maximum MOS value was encountered;
1574
1575 There is no default value.
1576
1577 This value is filled in after invoking “rtpengine_delete”,
1578 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1579 deletion of the call (or call branch).
1580
1581 Only call legs matching the rtpengine label given in the
1582 “mos_A_label_pv” will be used in calculating this statistics value.
1583
1584 Example 1.52. Set mos_max_roundtrip_A_pv parameter
1585 ...
1586 modparam("rtpengine", "mos_max_roundtrip_A_pv", "$avp(mos_max_roundtrip_A)")
1587 ...
1588
1589 5.52. mos_max_roundtrip_leg_A_pv (string)
1590
1591 The name of a pseudovariable to hold the packet round-trip time of the
1592 specific call leg in microseconds at the time the maximum MOS value was
1593 encountered;
1594
1595 There is no default value.
1596
1597 This value is filled in after invoking “rtpengine_delete”,
1598 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1599 deletion of the call (or call branch).
1600
1601 Only call legs matching the rtpengine label given in the
1602 “mos_A_label_pv” will be used in calculating this statistics value.
1603
1604 Example 1.53. Set mos_max_roundtrip_leg_A_pv parameter
1605 ...
1606 modparam("rtpengine", "mos_max_roundtrip_leg_A_pv", "$avp(mos_max_roundtrip_leg_
1607 A)")
1608 ...
1609
1610 5.53. mos_average_A_pv (string)
1611
1612 The name of a pseudovariable to hold the average (median) MOS value for
1613 the call. The value typically has a range of 1.0 through 5.0.
1614
1615 There is no default value.
1616
1617 This value is filled in after invoking “rtpengine_delete”,
1618 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1619 deletion of the call (or call branch).
1620
1621 Only call legs matching the rtpengine label given in the
1622 “mos_A_label_pv” will be used in calculating this statistics value.
1623
1624 Example 1.54. Set mos_average_A_pv parameter
1625 ...
1626 modparam("rtpengine", "mos_average_A_pv", "$avp(mos_average_A)")
1627 ...
1628
1629 5.54. mos_average_packetloss_A_pv (string)
1630
1631 The name of a pseudovariable to hold the average (median) amount of
1632 packetloss in percent present throughout the call.
1633
1634 There is no default value.
1635
1636 This value is filled in after invoking “rtpengine_delete”,
1637 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1638 deletion of the call (or call branch).
1639
1640 Only call legs matching the rtpengine label given in the
1641 “mos_A_label_pv” will be used in calculating this statistics value.
1642
1643 Example 1.55. Set mos_average_packetloss_A_pv parameter
1644 ...
1645 modparam("rtpengine", "mos_average_packetloss_A_pv", "$avp(mos_average_packetlos
1646 s_A)")
1647 ...
1648
1649 5.55. mos_average_jitter_A_pv (string)
1650
1651 The name of a pseudovariable to hold the average (median) amount of
1652 jitter in milliseconds present throughout the call.
1653
1654 There is no default value.
1655
1656 This value is filled in after invoking “rtpengine_delete”,
1657 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1658 deletion of the call (or call branch).
1659
1660 Only call legs matching the rtpengine label given in the
1661 “mos_A_label_pv” will be used in calculating this statistics value.
1662
1663 Example 1.56. Set mos_average_jitter_A_pv parameter
1664 ...
1665 modparam("rtpengine", "mos_average_jitter_A_pv", "$avp(mos_average_jitter_A)")
1666 ...
1667
1668 5.56. mos_average_roundtrip_A_pv (string)
1669
1670 The name of a pseudovariable to hold the average (median) packet
1671 round-trip time in microseconds present throughout the call.
1672
1673 There is no default value.
1674
1675 This value is filled in after invoking “rtpengine_delete”,
1676 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1677 deletion of the call (or call branch).
1678
1679 Only call legs matching the rtpengine label given in the
1680 “mos_A_label_pv” will be used in calculating this statistics value.
1681
1682 Example 1.57. Set mos_average_roundtrip_A_pv parameter
1683 ...
1684 modparam("rtpengine", "mos_average_roundtrip_A_pv", "$avp(mos_average_roundtrip_
1685 A)")
1686 ...
1687
1688 5.57. mos_average_roundtrip_leg_A_pv (string)
1689
1690 The name of a pseudovariable to hold the average (median) packet
1691 round-trip time of the specific call leg in microseconds present
1692 throughout the call.
1693
1694 There is no default value.
1695
1696 This value is filled in after invoking “rtpengine_delete”,
1697 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1698 deletion of the call (or call branch).
1699
1700 Only call legs matching the rtpengine label given in the
1701 “mos_A_label_pv” will be used in calculating this statistics value.
1702
1703 Example 1.58. Set mos_average_roundtrip_leg_A_pv parameter
1704 ...
1705 modparam("rtpengine", "mos_average_roundtrip_leg_A_pv", "$avp(mos_average_roundt
1706 rip_leg_A)")
1707 ...
1708
1709 5.58. mos_average_samples_A_pv (string)
1710
1711 The name of a pseudovariable to hold the number of samples used to
1712 determine the other “average” MOS data points.
1713
1714 There is no default value.
1715
1716 This value is filled in after invoking “rtpengine_delete”,
1717 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1718 deletion of the call (or call branch).
1719
1720 Only call legs matching the rtpengine label given in the
1721 “mos_A_label_pv” will be used in calculating this statistics value.
1722
1723 Example 1.59. Set mos_average_samples_A_pv parameter
1724 ...
1725 modparam("rtpengine", "mos_average_samples_A_pv", "$avp(mos_average_samples_A)")
1726 ...
1727
1728 5.59. mos_B_label_pv (string)
1729
1730 The name of a pseudovariable to hold a custom label used in rtpengine
1731 signalling. If set, all the statistics pseudovariables with the “_B”
1732 suffix will be filled in with statistics only from the call legs that
1733 match the label given in this variable. You need to fill this variable
1734 before invoking “rtpengine_delete”, “rtpengine_query”, or
1735 “rtpengine_manage”. Variable value should match the label= flag on
1736 “rtpengine_offer”, “rtpengine_answer”, or “rtpengine_manage”.
1737
1738 There is no default value.
1739
1740 Example 1.60. Set mos_B_label_pv parameter
1741 ...
1742 modparam("rtpengine", "mos_B_label_pv", "$avp(mos_B_label)")
1743 ...
1744
1745 5.60. mos_min_B_pv (string)
1746
1747 The name of a pseudovariable to hold the minimum encountered MOS value
1748 for the call. The value typically has a range of 1.0 through 5.0.
1749
1750 There is no default value.
1751
1752 This value is filled in after invoking “rtpengine_delete”,
1753 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1754 deletion of the call (or call branch).
1755
1756 Only call legs matching the rtpengine label given in the
1757 “mos_B_label_pv” will be used in calculating this statistics value.
1758
1759 Example 1.61. Set mos_min_B_pv parameter
1760 ...
1761 modparam("rtpengine", "mos_min_B_pv", "$avp(mos_min_B)")
1762 ...
1763
1764 5.61. mos_min_at_B_pv (string)
1765
1766 The name of a pseudovariable to hold the timestamp of when the minimum
1767 MOS value was encountered during the call, such as “0:30” for 30
1768 seconds after the start of the call.
1769
1770 There is no default value.
1771
1772 This value is filled in after invoking “rtpengine_delete”,
1773 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1774 deletion of the call (or call branch).
1775
1776 Only call legs matching the rtpengine label given in the
1777 “mos_B_label_pv” will be used in calculating this statistics value.
1778
1779 Example 1.62. Set mos_min_at_B_pv parameter
1780 ...
1781 modparam("rtpengine", "mos_min_at_B_pv", "$avp(mos_min_at_B)")
1782 ...
1783
1784 5.62. mos_min_packetloss_B_pv (string)
1785
1786 The name of a pseudovariable to hold the amount of packetloss in
1787 percent at the time the minimum MOS value was encountered;
1788
1789 There is no default value.
1790
1791 This value is filled in after invoking “rtpengine_delete”,
1792 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1793 deletion of the call (or call branch).
1794
1795 Only call legs matching the rtpengine label given in the
1796 “mos_B_label_pv” will be used in calculating this statistics value.
1797
1798 Example 1.63. Set mos_min_packetloss_B_pv parameter
1799 ...
1800 modparam("rtpengine", "mos_min_packetloss_B_pv", "$avp(mos_min_packetloss_B)")
1801 ...
1802
1803 5.63. mos_min_jitter_B_pv (string)
1804
1805 The name of a pseudovariable to hold the amount of jitter in
1806 milliseconds at the time the minimum MOS value was encountered;
1807
1808 There is no default value.
1809
1810 This value is filled in after invoking “rtpengine_delete”,
1811 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1812 deletion of the call (or call branch).
1813
1814 Only call legs matching the rtpengine label given in the
1815 “mos_B_label_pv” will be used in calculating this statistics value.
1816
1817 Example 1.64. Set mos_min_jitter_B_pv parameter
1818 ...
1819 modparam("rtpengine", "mos_min_jitter_B_pv", "$avp(mos_min_jitter_B)")
1820 ...
1821
1822 5.64. mos_min_roundtrip_B_pv (string)
1823
1824 The name of a pseudovariable to hold the packet round-trip time in
1825 microseconds at the time the minimum MOS value was encountered;
1826
1827 There is no default value.
1828
1829 This value is filled in after invoking “rtpengine_delete”,
1830 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1831 deletion of the call (or call branch).
1832
1833 Only call legs matching the rtpengine label given in the
1834 “mos_B_label_pv” will be used in calculating this statistics value.
1835
1836 Example 1.65. Set mos_min_roundtrip_B_pv parameter
1837 ...
1838 modparam("rtpengine", "mos_min_roundtrip_B_pv", "$avp(mos_min_roundtrip_B)")
1839 ...
1840
1841 5.65. mos_min_roundtrip_leg_B_pv (string)
1842
1843 The name of a pseudovariable to hold the packet round-trip time of the
1844 specific call leg in microseconds at the time the minimum MOS value was
1845 encountered;
1846
1847 There is no default value.
1848
1849 This value is filled in after invoking “rtpengine_delete”,
1850 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1851 deletion of the call (or call branch).
1852
1853 Only call legs matching the rtpengine label given in the
1854 “mos_B_label_pv” will be used in calculating this statistics value.
1855
1856 Example 1.66. Set mos_min_roundtrip_leg_B_pv parameter
1857 ...
1858 modparam("rtpengine", "mos_min_roundtrip_leg_B_pv", "$avp(mos_min_roundtrip_leg_
1859 B)")
1860 ...
1861
1862 5.66. mos_max_B_pv (string)
1863
1864 The name of a pseudovariable to hold the maximum encountered MOS value
1865 for the call. The value typically has a range of 1.0 through 5.0.
1866
1867 There is no default value.
1868
1869 This value is filled in after invoking “rtpengine_delete”,
1870 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1871 deletion of the call (or call branch).
1872
1873 Only call legs matching the rtpengine label given in the
1874 “mos_B_label_pv” will be used in calculating this statistics value.
1875
1876 Example 1.67. Set mos_max_B_pv parameter
1877 ...
1878 modparam("rtpengine", "mos_max_B_pv", "$avp(mos_max_B)")
1879 ...
1880
1881 5.67. mos_max_at_B_pv (string)
1882
1883 The name of a pseudovariable to hold the timestamp of when the maximum
1884 MOS value was encountered during the call, such as “0:30” for 30
1885 seconds after the start of the call.
1886
1887 There is no default value.
1888
1889 This value is filled in after invoking “rtpengine_delete”,
1890 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1891 deletion of the call (or call branch).
1892
1893 Only call legs matching the rtpengine label given in the
1894 “mos_B_label_pv” will be used in calculating this statistics value.
1895
1896 Example 1.68. Set mos_max_at_B_pv parameter
1897 ...
1898 modparam("rtpengine", "mos_max_at_B_pv", "$avp(mos_max_at_B)")
1899 ...
1900
1901 5.68. mos_max_packetloss_B_pv (string)
1902
1903 The name of a pseudovariable to hold the amount of packetloss in
1904 percent at the time the maximum MOS value was encountered;
1905
1906 There is no default value.
1907
1908 This value is filled in after invoking “rtpengine_delete”,
1909 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1910 deletion of the call (or call branch).
1911
1912 Only call legs matching the rtpengine label given in the
1913 “mos_B_label_pv” will be used in calculating this statistics value.
1914
1915 Example 1.69. Set mos_max_packetloss_B_pv parameter
1916 ...
1917 modparam("rtpengine", "mos_max_packetloss_B_pv", "$avp(mos_max_packetloss_B)")
1918 ...
1919
1920 5.69. mos_max_jitter_B_pv (string)
1921
1922 The name of a pseudovariable to hold the amount of jitter in
1923 milliseconds at the time the maximum MOS value was encountered;
1924
1925 There is no default value.
1926
1927 This value is filled in after invoking “rtpengine_delete”,
1928 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1929 deletion of the call (or call branch).
1930
1931 Only call legs matching the rtpengine label given in the
1932 “mos_B_label_pv” will be used in calculating this statistics value.
1933
1934 Example 1.70. Set mos_max_jitter_B_pv parameter
1935 ...
1936 modparam("rtpengine", "mos_max_jitter_B_pv", "$avp(mos_max_jitter_B)")
1937 ...
1938
1939 5.70. mos_max_roundtrip_B_pv (string)
1940
1941 The name of a pseudovariable to hold the packet round-trip time in
1942 microseconds at the time the maximum MOS value was encountered;
1943
1944 There is no default value.
1945
1946 This value is filled in after invoking “rtpengine_delete”,
1947 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1948 deletion of the call (or call branch).
1949
1950 Only call legs matching the rtpengine label given in the
1951 “mos_B_label_pv” will be used in calculating this statistics value.
1952
1953 Example 1.71. Set mos_max_roundtrip_B_pv parameter
1954 ...
1955 modparam("rtpengine", "mos_max_roundtrip_B_pv", "$avp(mos_max_roundtrip_B)")
1956 ...
1957
1958 5.71. mos_max_roundtrip_leg_B_pv (string)
1959
1960 The name of a pseudovariable to hold the packet round-trip time of the
1961 specific call leg in microseconds at the time the maximum MOS value was
1962 encountered;
1963
1964 There is no default value.
1965
1966 This value is filled in after invoking “rtpengine_delete”,
1967 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1968 deletion of the call (or call branch).
1969
1970 Only call legs matching the rtpengine label given in the
1971 “mos_A_label_pv” will be used in calculating this statistics value.
1972
1973 Example 1.72. Set mos_max_roundtrip_leg_B_pv parameter
1974 ...
1975 modparam("rtpengine", "mos_max_roundtrip_leg_B_pv", "$avp(mos_max_roundtrip_leg_
1976 B)")
1977 ...
1978
1979 5.72. mos_average_B_pv (string)
1980
1981 The name of a pseudovariable to hold the average (median) MOS value for
1982 the call. The value typically has a range of 1.0 through 5.0.
1983
1984 There is no default value.
1985
1986 This value is filled in after invoking “rtpengine_delete”,
1987 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1988 deletion of the call (or call branch).
1989
1990 Only call legs matching the rtpengine label given in the
1991 “mos_B_label_pv” will be used in calculating this statistics value.
1992
1993 Example 1.73. Set mos_average_B_pv parameter
1994 ...
1995 modparam("rtpengine", "mos_average_B_pv", "$avp(mos_average_B)")
1996 ...
1997
1998 5.73. mos_average_packetloss_B_pv (string)
1999
2000 The name of a pseudovariable to hold the average (median) amount of
2001 packetloss in percent present throughout the call.
2002
2003 There is no default value.
2004
2005 This value is filled in after invoking “rtpengine_delete”,
2006 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
2007 deletion of the call (or call branch).
2008
2009 Only call legs matching the rtpengine label given in the
2010 “mos_B_label_pv” will be used in calculating this statistics value.
2011
2012 Example 1.74. Set mos_average_packetloss_B_pv parameter
2013 ...
2014 modparam("rtpengine", "mos_average_packetloss_B_pv", "$avp(mos_average_packetlos
2015 s_B)")
2016 ...
2017
2018 5.74. mos_average_jitter_B_pv (string)
2019
2020 The name of a pseudovariable to hold the average (median) amount of
2021 jitter in milliseconds present throughout the call.
2022
2023 There is no default value.
2024
2025 This value is filled in after invoking “rtpengine_delete”,
2026 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
2027 deletion of the call (or call branch).
2028
2029 Only call legs matching the rtpengine label given in the
2030 “mos_B_label_pv” will be used in calculating this statistics value.
2031
2032 Example 1.75. Set mos_average_jitter_B_pv parameter
2033 ...
2034 modparam("rtpengine", "mos_average_jitter_B_pv", "$avp(mos_average_jitter_B)")
2035 ...
2036
2037 5.75. mos_average_roundtrip_B_pv (string)
2038
2039 The name of a pseudovariable to hold the average (median) packet
2040 round-trip time in microseconds present throughout the call.
2041
2042 There is no default value.
2043
2044 This value is filled in after invoking “rtpengine_delete”,
2045 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
2046 deletion of the call (or call branch).
2047
2048 Only call legs matching the rtpengine label given in the
2049 “mos_B_label_pv” will be used in calculating this statistics value.
2050
2051 Example 1.76. Set mos_average_roundtrip_B_pv parameter
2052 ...
2053 modparam("rtpengine", "mos_average_roundtrip_B_pv", "$avp(mos_average_roundtrip_
2054 B)")
2055 ...
2056
2057 5.76. mos_average_roundtrip_leg_B_pv (string)
2058
2059 The name of a pseudovariable to hold the average (median) packet
2060 round-trip time of the specific call leg in microseconds present
2061 throughout the call.
2062
2063 There is no default value.
2064
2065 This value is filled in after invoking “rtpengine_delete”,
2066 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
2067 deletion of the call (or call branch).
2068
2069 Only call legs matching the rtpengine label given in the
2070 “mos_B_label_pv” will be used in calculating this statistics value.
2071
2072 Example 1.77. Set mos_average_roundtrip_leg_B_pv parameter
2073 ...
2074 modparam("rtpengine", "mos_average_roundtrip_leg_B_pv", "$avp(mos_average_roundt
2075 rip_leg_B)")
2076 ...
2077
2078 5.77. mos_average_samples_B_pv (string)
2079
2080 The name of a pseudovariable to hold the number of samples used to
2081 determine the other “average” MOS data points.
2082
2083 There is no default value.
2084
2085 This value is filled in after invoking “rtpengine_delete”,
2086 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
2087 deletion of the call (or call branch).
2088
2089 Only call legs matching the rtpengine label given in the
2090 “mos_B_label_pv” will be used in calculating this statistics value.
2091
2092 Example 1.78. Set mos_average_samples_B_pv parameter
2093 ...
2094 modparam("rtpengine", "mos_average_samples_B_pv", "$avp(mos_average_samples_B)")
2095 ...
2096
2097 5.78. dtmf_event_callid (string)
2098
2099 The name of a pseudovariable to be filled in with the callid of the
2100 triggered dtmf event.
2101
2102 By default, this parameter is not set.
2103
2104 Example 1.79. Set dtmf_event_callid parameter
2105 ...
2106 modparam("rtpengine", "dtmf_event_callid", "$avp(dtmf_event_callid)")
2107 ...
2108
2109 5.79. dtmf_event_source_tag (string)
2110
2111 The name of a pseudovariable to be filled in with the source tag that
2112 triggered the dtmf event.
2113
2114 By default, this parameter is not set.
2115
2116 Example 1.80. Set dtmf_event_source_tag parameter
2117 ...
2118 modparam("rtpengine", "dtmf_event_source_tag", "$avp(dtmf_event_source_tag)")
2119 ...
2120
2121 5.80. dtmf_event_timestamp (string)
2122
2123 The name of a pseudovariable to be filled in with the timestamp when
2124 the dtmf event was triggered.
2125
2126 By default, this parameter is not set.
2127
2128 Example 1.81. Set dtmf_event_timestamp parameter
2129 ...
2130 modparam("rtpengine", "dtmf_event_timestamp", "$avp(dtmf_event_timestamp)")
2131 ...
2132
2133 5.81. dtmf_event (string)
2134
2135 The name of a pseudovariable to be filled in with the triggered DTMF
2136 value.
2137
2138 By default, this parameter is not set.
2139
2140 Example 1.82. Set dtmf_event parameter
2141 ...
2142 modparam("rtpengine", "dtmf_event", "$avp(dtmf_event)")
2143 ...
2144
2145 5.82. control_cmd_tos (integer)
2146
2147 The parameter is used to set the value of “type of service (tos)” for
2148 the control commands (such as rtpengine_offer(), rtpengine_answer()
2149 etc).
2150
2151 There is no default value. By default this feature is not used.
2152
2153 The values not falling into the range “0-255” will be simply ignored.
2154
2155 Example 1.83. Set control_cmd_tos parameter
2156 ...
2157 modparam("rtpengine", "control_cmd_tos", 144)
2158 ...
2159
2160 5.83. hash_algo (integer)
2161
2162 The hashing algorithm to be used in node selection algorithm. There are
2163 two possibilities: SHA1 - 1 (calculate SHA1 hash over the Call-ID) or
2164 CRC32 - 2 (calculate crc32 sum over the callid). The legacy algorithm -
2165 0 is not available anymore. If 0 is specified the default CRC32 will be
2166 used.
2167
2168 Default value is 2, CRC32.
2169
2170 The values not falling into the range “0-2” are ignored.
2171
2172 Example 1.84. Set hash_algo parameter
2173 ...
2174 ### use CRC32 instead of legacy algorithm
2175 modparam("rtpengine", "hash_algo", 2)
2176 ...
2177
2178 5.84. wsapi (string)
2179
2180 Configure a backend API for websocket usage. Currently the only
2181 supported setting is “lwsc” (libwebsockets). If unset, then the
2182 websocket protocol cannot be used.
2183
2184 Example 1.85. Set wsapi parameter
2185 ...
2186 modparam("rtpengine", "wsapi", "lwsc")
2187 ...
2188
2189 5.85. dtmf_events_sock (string)
2190
2191 Definition of IPv4/IPv6 UDP socket used to receive dtmf events from
2192 RTPEngine.
2193
2194 DTMF events coming from RTPEngine will trigger rtpengine:dtmf-event
2195 route.
2196
2197 Default value is “NONE” (disabled).
2198
2199 Example 1.86. Set dtmf_events_sock parameter
2200 ...
2201 modparam("rtpengine", "dtmf_events_sock", "127.0.0.1:2223")
2202 ...
2203
2204 5.86. ping_mode (integer)
2205
2206 Specify if the RTPEngine instances have to be pinged at startup to
2207 detect if they are active. Set it to 0 to disable pinging and to 1 to
2208 activate pinging.
2209
2210 Default value is “1”.
2211
2212 Example 1.87. Set ping_mode parameter
2213 ...
2214 modparam("rtpengine", "ping_mode", 0)
2215 ...
2216
2217 6. ping_interval (integer)
2218
2219 Specify the interval in seconds between pings to all rtpengines
2220 registered.
2221
2222 Default value is “60”.
2223
2224 Example 1.88. Set ping_interval parameter
2225 ...
2226 modparam("rtpengine", "ping_interval", 10)
2227 ...
2228
2229 7. enable_dmq (integer)
2230
2231 If set to 1, will enable DMQ replication of hashtable of (callid, node)
2232 pairs.
2233
2234 Important: If this parameter is enabled, the DMQ module must be loaded
2235 first - otherwise, startup will fail.
2236
2237 Default value is “0”.
2238
2239 Example 1.89. Set enable_dmq parameter
2240 ...
2241 modparam("rtpengine", "enable_dmq", 1)
2242 ...
2243
2244 8. dtmf_event_source_label (str)
2245
2246 9. dtmf_event_tags (str)
2247
2248 10. dtmf_event_type (str)
2249
2250 11. dtmf_event_source_ip (str)
2251
2252 12. dtmf_event_duration (str)
2253
2254 13. dtmf_event_volume (str)
2255
2256 14. event_callback (str)
2257
2258 15. Functions
2259
2260 15.1. set_rtpengine_set(setid[, setid])
2261 15.2. rtpengine_offer([flags][,via-branch])
2262 15.3. rtpengine_answer([flags][,via-branch])
2263 15.4. rtpengine_info([flags][,via-branch])
2264 15.5. rtpengine_delete([flags][,via-branch])
2265 15.6. rtpengine_destroy([flags][,via-branch])
2266 15.7. rtpengine_query([flags][,via-branch])
2267 15.8. rtpengine_query_v(fmt, var)
2268 15.9. rtpengine_connect([flags][,via-branch])
2269 15.10. rtpengine_manage([flags][,via-branch])
2270 15.11.
2271 rtpengine_subscribe_request(flags,sdp_avp,to_tag_avp,stream_xavp[
2272 ,via-branch])
2273
2274 15.12. rtpengine_subscribe_answer([flags][,via-branch])
2275 15.13. rtpengine_unsubscribe([flags][,via-branch])
2276 15.14. start_recording([flags])
2277 15.15. stop_recording([flags])
2278 15.16. block_dtmf([flags])
2279 15.17. unblock_dtmf([flags])
2280 15.18. block_media([flags])
2281 15.19. unblock_media([flags])
2282 15.20. silence_media([flags])
2283 15.21. unsilence_media([flags])
2284 15.22. start_forwarding([flags])
2285 15.23. stop_forwarding([flags])
2286 15.24. play_media([flags])
2287 15.25. stop_media([flags])
2288 15.26. play_dtmf([flags])
2289
2290 15.1. set_rtpengine_set(setid[, setid])
2291
2292 Sets the ID of the RTP proxy set to be used for the next
2293 rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
2294 rtpengine_manage() command. The parameter can be an integer or a config
2295 variable holding an integer.
2296
2297 A second set ID can be specified to daisy-chain two RTP proxies. The
2298 two set IDs must be distinct from each other and there must not be any
2299 overlap in the proxies present in both sets. In this use case, the
2300 request (offer, answer, etc) is first sent to an RTP proxy from the
2301 first set, which rewrites the SDP body and sends it back to the module.
2302 The rewritten SDP body is then used to make another request to an RTP
2303 proxy from the second set, which rewrites the SDP body another time and
2304 sends it back to the module to be placed back into the SIP message.
2305 This is useful if you have a set of RTP proxies that the caller must
2306 use, and another distinct set of RTP proxies that the callee must use.
2307
2308 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
2309 BRANCH_ROUTE.
2310
2311 Example 1.90. set_rtpengine_set usage
2312 ...
2313 set_rtpengine_set("2");
2314 rtpengine_offer();
2315 ...
2316
2317 15.2. rtpengine_offer([flags][,via-branch])
2318
2319 Rewrites SDP body to ensure that media is passed through an RTP proxy.
2320 To be invoked on INVITE for the cases the SDP bodies are in INVITE and
2321 200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
2322
2323 The function will return true on success and false (-1) on various
2324 failures, like using rtp_engine_offer() on a SIP MESSAGE request or
2325 communication with rtpengine fails.
2326
2327 Meaning of the parameters is as follows:
2328 * flags - flags to turn on some features.
2329 The “flags” string is a list of space-separated items. Each item is
2330 either an individual token, or a token in “key=value” format. The
2331 possible tokens are described below.
2332 + via-branch=... - Include the “branch” value of one of the
2333 “Via” headers in the request to the RTP proxy. Possible values
2334 are: “1” - use the first “Via” header; “2” - use the second
2335 “Via” header; “auto” - use the first “Via” header if this is a
2336 request, or the second one if this is a reply; “extra” - don't
2337 take the value from a header, but instead use the value of the
2338 “extra_id_pv” variable; “next” - use the branch ID generated
2339 by Kamailio for the next outgoing branch; “auto-next” - use
2340 “next” in requests and “1” in replies; “auto-extra” - use
2341 “extra” in requests and “1” in replies. This can be used to
2342 create one media session per branch on the RTP proxy. When
2343 sending a subsequent “delete” command to the RTP proxy, you
2344 can then stop just the session for a specific branch when
2345 passing the flag '1' or '2' in the “rtpengine_delete”, or stop
2346 all sessions for a call when not passing one of those two
2347 flags there. This is especially useful if you have serially
2348 forked call scenarios where the RTP proxy gets an “offer”
2349 command for a new branch, and then a “delete” command for the
2350 previous branch, which would otherwise delete the full call,
2351 breaking the subsequent “answer” for the new branch. This flag
2352 is only supported by the Sipwise rtpengine RTP proxy at the
2353 moment!
2354 + asymmetric - flags that UA from which message is received
2355 doesn't support symmetric RTP. Disables learning of endpoint
2356 addresses in the Sipwise rtpengine proxy.
2357 + no-redis-update - this flag can be used by Kamailio in order
2358 to tell rtpengine not to persist the call into Redis upon
2359 receiving offer/answer() control commands. If flag is not set,
2360 default action is rtpengine persists call to redis.
2361 + force-answer - force “answer”, that is, only rewrite SDP when
2362 corresponding session already exists in the RTP proxy. By
2363 default is on when the session is to be completed. This is
2364 only necessary when the offer was sent by rtpengine_offer(),
2365 and the answer is handled by rtpengine_manage().
2366 + direction=... - this option specifies a logical network
2367 interface and should be given exactly twice. It enables RTP
2368 bridging between different addresses or networks of the same
2369 family (e.g. IPv4 to IPv4). The first instance of the option
2370 specifies the interface that the originator of this message
2371 should be using, while the second instance specifies the
2372 interface that the target should be using. For example, if the
2373 SIP message was sent by an endpoint on a private network and
2374 will be sent to an endpoint on the public internet, you would
2375 use “direction=priv direction=pub” if those two logical
2376 network interfaces were called “priv” and “pub” in your RTP
2377 proxy's configuration respectively. The direction must only be
2378 specified in for initial SDP offer; answers or subsequent
2379 offers can omit this option.
2380 + internal, external - shorthand for “direction=internal” and
2381 “direction=external” respectively. Useful for brevity or as
2382 legacy option if the RTP proxy only supports two network
2383 interfaces instead of multiple, arbitrarily named ones.
2384 + address-family=... - instructs the RTP proxy that the
2385 recipient of this SDP body expects to see addresses of a
2386 particular family. Possible values are “IP4” and “IP6”. For
2387 example, if the SDP body contains IPv4 addresses but the
2388 recipient only speaks IPv6, you would use “address-family=IP6”
2389 to bridge between the two address families.
2390 Sipwise rtpengine remembers the address family preference of
2391 each party after it has seen an SDP body from them. This means
2392 that normally it is only necessary to explicitly specify the
2393 address family in the “offer”, but not in the “answer”.
2394 Note: Please note, that this will only work properly with
2395 non-dual-stack user-agents or with dual-stack clients
2396 according to RFC6157 (which suggest ICE for Dual-Stack
2397 implementations). This short-cut will not work properly with
2398 RFC4091 (ANAT) compatible clients, which suggests having
2399 different m-lines with different IP-protocols grouped
2400 together.
2401 + force - instructs the RTP proxy to ignore marks inserted by
2402 another RTP proxy in transit to indicate that the session
2403 already goes through another proxy. Allows creating a chain of
2404 proxies. Not supported and ignored by Sipwise rtpengine.
2405 + trust-address - flags that IP address in SDP should be
2406 trusted. Starting with rtpengine 3.8, this is the default
2407 behaviour. In older versions, without this flag the RTP proxy
2408 ignores the address in the SDP and uses source address of the
2409 SIP message as media address which is passed to the RTP proxy.
2410 + SIP-source-address - the opposite of trust-address. Restores
2411 the old default behaviour of ignoring endpoint addresses in
2412 the SDP body.
2413 + received-from=IP - Configure the SIP-source-address IP
2414 explicitly, which will be useful when two kamailio is cascaded
2415 where first kamailio is handling NAT and second kamailio
2416 RTPEngine.
2417 + replace-origin - flags that IP from the origin description
2418 (o=) should be also changed.
2419 + replace-session-connection - flags to change the session-level
2420 SDP connection (c=) IP if media description also includes
2421 connection information.
2422 + symmetric - flags that for the UA from which message is
2423 received, support symmetric RTP must be forced. Does nothing
2424 with the Sipwise rtpengine proxy as it is the default.
2425 + repacketize=NN - requests the RTP proxy to perform
2426 re-packetization of RTP traffic coming from the UA which has
2427 sent the current message to increase or decrease payload size
2428 per each RTP packet forwarded if possible. The NN is the
2429 target payload size in ms, for the most codecs its value
2430 should be in 10ms increments, however for some codecs the
2431 increment could differ (e.g. 30ms for GSM or 20ms for G.723).
2432 The RTP proxy would select the closest value supported by the
2433 codec. This feature could be used for significantly reducing
2434 bandwith overhead for low bitrate codecs, for example with
2435 G.729 going from 10ms to 100ms saves two thirds of the network
2436 bandwith. Not supported by Sipwise rtpengine.
2437 + ICE=... - controls the RTP proxy's behaviour regarding ICE
2438 attributes within the SDP body. Possible values are: “force” -
2439 discard any ICE attributes already present in the SDP body and
2440 then generate and insert new ICE data, leaving itself as the
2441 only ICE candidates; “force-relay” - discard any “relay” type
2442 ICE attributes already present in the SDP body and then
2443 generate and insert itself as the only ICE “relay” candidates;
2444 “remove” instructs the RTP proxy to discard any ICE attributes
2445 and not insert any new ones into the SDP. The default (if no
2446 “ICE=...” is given at all), new ICE data will only be
2447 generated if no ICE was present in the SDP originally;
2448 otherwise the RTP proxy will only insert itself as additional
2449 ICE candidate. Other SDP substitutions (c=, m=, etc) are
2450 unaffected by this flag.
2451 + RTP, SRTP, DTLS, AVP, AVPF - These flags control the RTP
2452 transport protocol that should be used towards the recipient
2453 of the SDP. If none of them are specified, the protocol given
2454 in the SDP is left untouched. Otherwise, the “SRTP” flag
2455 indicates that SRTP should be used, while “RTP” indicates that
2456 both SRTP and AVPF should not be used. “AVPF” indicates that
2457 the advanced RTCP profile with feedback messages should be
2458 used, and “AVP” indicates that the regular RTCP profile should
2459 be used. See also the next set of flags below.
2460 + RTP/AVP, RTP/SAVP, UDP/TLS/RTP/SAVP, RTP/AVPF, RTP/SAVPF,
2461 UDP/TLS/RTP/SAVPF - these serve as an alternative, more
2462 explicit way to select between the different RTP protocols and
2463 profiles supported by the RTP proxy. For example, giving the
2464 flag “RTP/SAVPF” has the same effect as giving the two flags
2465 “SRTP AVPF”.
2466 + to-tag - force inclusion of the “To” tag. Normally, the “To”
2467 tag is always included when present, except for “delete”
2468 messages. Including the “To” tag in a “delete” messages allows
2469 you to be more selective about which dialogues within a call
2470 are being torn down.
2471 + to-tag=... - use the specified string as “To” tag instead of
2472 the actual “To” tag from the SIP message, and force inclusion
2473 of the tag in the message as per above.
2474 + from-tag=... - use the specified string as “From” tag instead
2475 of the actual “From” tag from the SIP message.
2476 + call-id=... - use the specified string as “Call-ID” instead of
2477 the actual “Call-ID” from the SIP message.
2478 + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
2479 RTP proxy accept the offer, but not offer it to the recipient
2480 of this message.
2481 + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
2482 reject the offer, but still offer it to the recipient. Can be
2483 combined with “rtcp-mux-offer” to always offer it.
2484 + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
2485 recipient of this message, regardless of whether it was
2486 offered originally or not.
2487 + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
2488 accept the offer and also offer it to the recipient of this
2489 message. Can be combined with “rtcp-mux-offer” to always offer
2490 it.
2491 + media-address=... - force a particular media address to be
2492 used in the SDP body. Address family is detected
2493 automatically.
2494 + TOS=... - change the IP TOS value for all outgoing RTP packets
2495 within the entire call in both directions. Only honoured in an
2496 “offer”, ignored for an “answer”. Valid values are 0 through
2497 255, given in decimal. If this option is not specified, the
2498 TOS value will revert to the default TOS (normally 184). A
2499 value of -1 may be used to leave the currently used TOS
2500 unchanged.
2501 + delete-delay=... - override the default delay (in seconds)
2502 before a call is actually deleted from memory. Can be set to
2503 zero to effectuate immediate deletion. This option only makes
2504 sense for delete operations.
2505 + strict-source - instructs the RTP proxy to check the source
2506 addresses of all incoming RTP packets and drop the packets if
2507 the address doesn't match.
2508 + media-handover - the antithesis of strict-source. Instructs
2509 the RTP proxy not only to accept mismatching RTP source
2510 addresses (as it normally would), but also to accept them as
2511 the new endpoint address of the opposite media flow. Not
2512 recommended as it allows media streams to be hijacked by an
2513 attacker.
2514 + DTLS=... - influence the behaviour of DTLS-SRTP. Possible
2515 values are “no” or “off” to suppress offering or accepting
2516 DTLS-SRTP, and “passive” to prefer participating in DTLS-SRTP
2517 in a passive role.
2518 + SDES-off - don't offer SDES when it normally would. In an SRTP
2519 context, this leaves DTLS-SRTP as the only other option.
2520 + SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
2521 SDES-unauthenticated_srtp - these directly reflect the SDES
2522 session parameters from RFC 4568 and will make the RTP proxy
2523 offer these parameters when offering SDES.
2524 + SDES-encrypted_srtp, SDES-encrypted_srtcp,
2525 SDES-authenticated_srtp - the opposites of the flags above.
2526 Useful if accepting these parameters is not desired and they
2527 should be rejected instead.
2528 + SDES-nonew - don't add any new crypto suites into the offer.
2529 This means, offered SDES crypto suites will be accepted,
2530 meanwhile no new is going to be generated by RTPEngine. It
2531 takes precedence over the `SDES-no` and `SDES-only` flags, if
2532 used in combination.
2533 + SDES-pad - RFC 4568 (section 6.1) is somewhat ambiguous
2534 regarding the base64 encoding format of `a=crypto` parameters
2535 added to an SDP body. The default interpretation is that
2536 trailing `=` characters used for padding should be omitted.
2537 With this flag set, these padding characters will be left in
2538 place.
2539 + unidirectional - allows kernelization of one-way streams in
2540 the Sipwise rtpengine proxy. This is especially useful when
2541 the first call leg is handled by some rtpengine machine while
2542 the second call leg is handled by other rtpengine machine.
2543 + record-call=on - instructs RTPEngine to record the session.
2544 Use it in rtpengine_offer() to start recording immediately and
2545 save the call metadata, as alternative to start_recording().
2546 + metadata - a generic metadata string. The metadata will be
2547 used when recording calls to provide custom additional
2548 information. More details about this are found in the
2549 rtpengine README.
2550 + codec-transcode=... - allows codecs to be added to the list of
2551 offered codecs even if they were not present in the original
2552 list of codecs. In this case, the transcoding engine will be
2553 engaged. Only codecs that are supported for both decoding and
2554 encoding can be added in this manner. More details about this
2555 are found in the rtpengine README.
2556 + codec-set=... - set codec options (bitrate etc) for codecs
2557 that are implicitly accepted for transcoding from the offering
2558 side.
2559 + codec-strip=... - strips given codec from sdp
2560 + codec-offer=... - offer given codec from sdp. More details
2561 about this are found in the rtpengine README.
2562 + codec-except=... - same as codec-offer but preserves original
2563 order
2564 + codec-mask=... - similar to strip except that codecs listed
2565 here will still be accepted and used for transcoding on the
2566 offering side. Useful only in combination with
2567 codec-transcode. all keyword can be used to mask all offered
2568 codecs
2569 + codec-accept=... - similar to `mask` and `consume` but doesn't
2570 remove the codec from the list of offered codecs. This means
2571 that a codec listed under `accept` will still be offered to
2572 the remote peer, but if the remote peer rejects it, it will
2573 still be accepted towards the original offerer and then used
2574 for transcoding. It is a more selective version of what the
2575 `always transcode` flag does.
2576 + codec-consume=... - identical to mask but enables the
2577 transcoding engine even if no other transcoding related
2578 options are given.
2579 + T.38=decode - if the offered SDP contains a media section
2580 advertising T.38 over UDPTL, translate it to a regular audio
2581 media section over RTP. By default, PCMU and PCMA will be used
2582 as audio codecs, but that can be overridden using the codec
2583 options described above. Other transport protocols (e.g. SRTP)
2584 can also be selected in the same way. If the offered SDP does
2585 not contain a T.38 section, then this flag has no effect.
2586 + T.38=force - any audio media section (over RTP) in the offered
2587 SDP will be translated into a T.38 section over UDPTL.
2588 + T.38=stop - stops a previously established T.38 to audio
2589 gateway and reverts the session back to media passthrough.
2590 This is useful when handling a rejected T.38 offer.
2591 + label=... - adds a label to a current stream, that later can
2592 be used to get call quality stats, see “mos_A_label_pv” and
2593 “mos_B_label_pv” parameters.
2594 + debug - enables debug logging (rtpengine log level 7) for this
2595 call only. rtpengine will log everything related to that call
2596 after parsing the flags. Useful in debugging scenarios.
2597 Check also the documentation of RTPEngine, these flags are
2598 documented there as well: https://github.com/sipwise/rtpengine.
2599 * via-branch - provide the via-branch taken from one of SIP message
2600 Via headers.
2601 The “via-branch” parameter helps to match NG command (offer,
2602 answer, delete etc.) to particular monologue. It does the same job
2603 as the “via-branch” option flag, but it also enables alternative
2604 parsing behavior, when option flags are passed to rtpengine using
2605 bencode string format and is then parsed there. The benefit of the
2606 second approach is that any new flags supported by rtpengine will
2607 automatically be supported without having to worry about support in
2608 the control module. Regardless whether the flags parsing is done by
2609 the module or daemon, a functional behavior remains the same and
2610 has no difference in terms of SDP processing. Possible values are
2611 the same as for the “via-branch” option flag. If the newer approach
2612 is to be applied, but no “via-branch” is meant to be added for
2613 identfication, then “none” can be given instead. This parameter can
2614 be applied for the rtpengine versions equal or later than mr12.4.
2615
2616 This function can be used from ANY_ROUTE.
2617
2618 Example 1.91. rtpengine_offer usage
2619 request_route {
2620 ...
2621 if (is_method("INVITE")) {
2622 if (has_body("application/sdp")) {
2623 if (rtpengine_offer())
2624 t_on_reply("1");
2625 } else {
2626 t_on_reply("2");
2627 }
2628 }
2629 if (is_method("ACK") && has_body("application/sdp"))
2630 rtpengine_answer();
2631 ...
2632 }
2633
2634 onreply_route[1]
2635 {
2636 ...
2637 if (has_body("application/sdp"))
2638 rtpengine_answer();
2639 ...
2640 }
2641
2642 onreply_route[2]
2643 {
2644 ...
2645 if (has_body("application/sdp"))
2646 rtpengine_offer();
2647 ...
2648 }
2649 ...
2650 if (has_body("application/sdp")) {
2651 if (rtpengine_offer("codec-mask=all codec-transcode=PCMU codec-transcode=PCM
2652 A"))
2653 t_on_reply("1");
2654 }
2655
2656 ...
2657
2658 Example 1.92. rtpengine_offer usage to force transcoding from opus to
2659 PCMU
2660 request_route {
2661 ...
2662 if (is_method("INVITE")) {
2663 if (has_body("application/sdp")) {
2664 if (rtpengine_offer("codec-mask=opus codec-accept=opus codec-strip=P
2665 CMU codec-transcode=PCMU"))
2666 t_on_reply("1");
2667 }
2668 }
2669 ...
2670 }
2671
2672 onreply_route[1]
2673 {
2674 ...
2675 if (has_body("application/sdp"))
2676 rtpengine_answer("codec-strip=PCMU codec-strip=PCMA");
2677 ...
2678 }
2679 ...
2680
2681 Example 1.93. rtpengine_offer usage of via-branch parameter
2682 request_route {
2683 ...
2684 if (is_method("INVITE")) {
2685 if (has_body("application/sdp")) {
2686 if (rtpengine_offer("replace-origin replace-session-connection stric
2687 t-source label=callee OSRTP-accept transport-protocol=RTP/AVP address-family=IP4
2688 ", "auto-next"))
2689 t_on_reply("1");
2690 }
2691 }
2692 ...
2693 }
2694
2695 15.3. rtpengine_answer([flags][,via-branch])
2696
2697 Rewrites SDP body to ensure that media is passed through an RTP proxy.
2698 To be invoked on 200 OK for the cases the SDP bodies are in INVITE and
2699 200 OK and on ACK when SDP bodies are in 200 OK and ACK.
2700
2701 See rtpengine_offer() function description above for the meaning of the
2702 parameters.
2703
2704 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
2705 FAILURE_ROUTE, BRANCH_ROUTE.
2706
2707 Example 1.94. rtpengine_answer usage
2708
2709 See rtpengine_offer() function example above for example.
2710
2711 15.4. rtpengine_info([flags][,via-branch])
2712
2713 Send an updated offer to rtpengine. This is meant to be used when
2714 processing Trickle ICE SDP Fragments that are carried in SIP INFO
2715 messages and are proxied to endpoints that do not support ICE. With a
2716 matching content type, the SDP fragment is used to update rtpengine's
2717 list of ICE candidates. No new SDP is returned and so the SIP INFO
2718 message should be consumed after calling this function.
2719
2720 While this function supports the same flags as “rtpengine_offer” et al,
2721 it is not normally necessary to provide any.
2722
2723 This function can be used from ANY_ROUTE.
2724
2725 Example 1.95. rtpengine_info usage
2726 ...
2727 rtpengine_info();
2728 ...
2729
2730 15.5. rtpengine_delete([flags][,via-branch])
2731
2732 Tears down the RTP proxy session for the current call. This populates
2733 the statistics pseudovariables (such “mos_min_pv” etc).
2734
2735 See rtpengine_offer() function description above for the meaning of the
2736 parameters. Note that not all flags make sense for a “delete”.
2737
2738 This function can be used from ANY_ROUTE.
2739
2740 Example 1.96. rtpengine_delete usage
2741 ...
2742 rtpengine_delete();
2743 ...
2744
2745 15.6. rtpengine_destroy([flags][,via-branch])
2746
2747 Same as rtpengine_delete().
2748
2749 Example 1.97. rtpengine_destroy usage
2750 ...
2751 rtpengine_destroy();
2752 ...
2753
2754 15.7. rtpengine_query([flags][,via-branch])
2755
2756 Queries the RTP proxy about the current status and statistics of a
2757 running call. This populates the statistics pseudovariables (such
2758 “mos_min_pv” etc).
2759
2760 See rtpengine_offer() function description above for the meaning of the
2761 parameters. Note that not all flags make sense for a “query”.
2762
2763 This function can be used from ANY_ROUTE.
2764
2765 Example 1.98. rtpengine_query usage
2766 ...
2767 rtpengine_query();
2768 ...
2769
2770 15.8. rtpengine_query_v(fmt, var)
2771
2772 Queries the RTP proxy about the current status and statistics of a
2773 running call, converts the response to JSON according to fmt and sets
2774 the variable var with the result.
2775
2776 The fmt parameter can be 'j' for compacted JSON and 'jp' for
2777 pretty-formatted JSON.
2778
2779 The var parameter has to be the name of a writable variable.
2780
2781 This function can be used from ANY_ROUTE.
2782
2783 Example 1.99. rtpengine_query_v usage
2784 ...
2785 if(rtpengine_query_v("j", "$var(rdata)")) {
2786 xinfo("rtpengine query response: $var(rdata)\n");
2787 }
2788 ...
2789
2790 15.9. rtpengine_connect([flags][,via-branch])
2791
2792 Connects the media of two call parties directly without the need for a
2793 full offer/answer exchange. The media will be connected in the same way
2794 as it would through an offer/answer exchange. Transcoding will
2795 automatically be engaged if needed.
2796
2797 See rtpengine_query() function description above for the meaning of the
2798 parameters. The function requires call-id, from-tag, and to-tag to
2799 identify the two call parties to connect. Optionally, to-call-id can be
2800 specified in flags to connect parties from different calls (different
2801 call IDs).
2802
2803 This function can be used from ANY_ROUTE.
2804
2805 Example 1.100. rtpengine_connect usage
2806 ...
2807 # Connect two parties from the same call (using tags from current SIP message)
2808 rtpengine_connect();
2809
2810 # Connect two parties from different calls, specifying all parameters
2811 rtpengine_connect("[email protected] from-tag=a1b2c3d4 to-tag=e
2812 5f6g7h8 [email protected]");
2813 ...
2814
2815 15.10. rtpengine_manage([flags][,via-branch])
2816
2817 Manage the RTPEngine session - it combines the functionality of
2818 rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
2819 internally based on message type and method which one to execute.
2820
2821 It can take the same parameters as rtpengine_offer(). The flags
2822 parameter to rtpengine_manage() can be a configuration variable
2823 containing the flags as a string.
2824
2825 Functionality:
2826 * If INVITE with SDP, then do rtpengine_offer()
2827 * If INVITE with SDP, when the tm module is loaded, mark transaction
2828 with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
2829 rtpengine_answer()
2830 * If ACK with SDP, then do rtpengine_answer()
2831 * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
2832 rtpengine_delete(). Be careful with calling this function after
2833 resuming a suspended transaction (e.g., after t_continue()),
2834 because the context of executed route is FAILURE ROUTE (in other
2835 words, rtpengine_manage() in the route block of t_continue() does
2836 the same as in failure_route; use a branch route to engage
2837 rtpengine for a forwarded branch after resuming the transaction).
2838 * It does nothing if used inside event_route[tm:branch-failure:...]
2839 * If reply to INVITE with code >= 300 do rtpengine_delete()
2840 * If reply with SDP to INVITE having code 1xx and 2xx, then do
2841 rtpengine_answer() if the request had SDP or tm is not loaded,
2842 otherwise do rtpengine_offer()
2843
2844 This function can be used from ANY_ROUTE.
2845
2846 Example 1.101. rtpengine_manage usage
2847 ...
2848 rtpengine_manage();
2849 ...
2850
2851 15.11.
2852 rtpengine_subscribe_request(flags,sdp_avp,to_tag_avp,stream_xavp[,via-branch]
2853 )
2854
2855 Generates SDP body for forking the current RTP stream and stores it in
2856 the xavp specified “sdp_avp” AVP. The new call leg will be identified
2857 by the generated (or specified) to tag that will be put in the
2858 “to_tag_avp” AVP. on INVITE for the cases the SDP bodies are in INVITE
2859 and 200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
2860
2861 The function will return true on success and false (-1) on various
2862 failures, like using rtpengine_subscribe_request() before an rtpengine
2863 session was established.
2864
2865 Meaning of the parameters is as follows:
2866 * flags - flags to turn on some features.
2867 The “flags” string is a list of space-separated items. Each item is
2868 either an individual token, or a token in “key=value” format. The
2869 possible tokens are described below. This offer SDP can be
2870 manipulated with the same flags as used in rtpengine_offer
2871 additionally, the following extra flags can be used
2872 + from-tags=... - Specifies which participants in the call
2873 should have their media forked. This value can be repeated
2874 multiple times to specify multiple participants. To specify
2875 all participants, use “all” as an alternative.
2876 + all - forks the media stream for all participants in the call.
2877 Use instead of “from-tags=...”
2878 + siprec - indicates that the SDP should be in SIPREC format.
2879 The flag “all” should also be used in this case.
2880 Check also the documentation of RTPEngine, these flags are
2881 documented there as well: https://github.com/sipwise/rtpengine.
2882 * sdp_avp - the name of the AVP where the generated SDP will be
2883 stored.
2884 The “sdp_avp” parameter is mandatory and must be a writable AVP.
2885 The AVP will be set to the generated SDP body, which can then be
2886 used in a subsequent “t_uac_send()” call to send the offer to the
2887 new participant.
2888 * to_tag_avp - the name of the AVP where to store the to tag of the
2889 new call leg.
2890 The “to_tag_avp” parameter is mandatory and must be a writable AVP.
2891 The to tag will either be auto generated or taken from the value
2892 specified in the “to-tag” flag.
2893 * stream_xavp - XAVP to store the stream information.
2894 The “stream_xavp” parameter is mandatory and must be a writable
2895 XAVP. The XAVP will be a stack, one for each participant. Each
2896 stack element will have a key “tag” to identify the participant,
2897 and a key “label” which is an array of labels, (each stream in the
2898 RTP will have a label attribute in the generated SDP).
2899 * via-branch - provide the via-branch taken from one of SIP message
2900 Via headers.
2901 The “via-branch” parameter helps to match NG command (offer,
2902 answer, delete etc.) to particular monologue. It does the same job
2903 as the “via-branch” option flag, but it also enables alternative
2904 parsing behavior, when option flags are passed to rtpengine using
2905 bencode string format and is then parsed there. The benefit of the
2906 second approach is that any new flags supported by rtpengine will
2907 automatically be supported without having to worry about support in
2908 the control module. Regardless whether the flags parsing is done by
2909 the module or daemon, a functional behavior remains the same and
2910 has no difference in terms of SDP processing. Possible values are
2911 the same as for the “via-branch” option flag. If the newer approach
2912 is to be applied, but no “via-branch” is meant to be added for
2913 identfication, then “none” can be given instead. This parameter can
2914 be applied for the rtpengine versions equal or later than mr12.4.
2915 * via-branch - provide the via-branch taken from one of SIP message
2916 Via headers.
2917 The “via-branch” parameter helps to match NG command (offer,
2918 answer, delete etc.) to particular monologue. It does the same job
2919 as the “via-branch” option flag, but it also enables alternative
2920 parsing behavior, when option flags are passed to rtpengine using
2921 bencode string format and is then parsed there. The benefit of the
2922 second approach is that any new flags supported by rtpengine will
2923 automatically be supported without having to worry about support in
2924 the control module. Regardless whether the flags parsing is done by
2925 the module or daemon, a functional behavior remains the same and
2926 has no difference in terms of SDP processing. Possible values are
2927 the same as for the “via-branch” option flag. If the newer approach
2928 is to be applied, but no “via-branch” is meant to be added for
2929 identfication, then “none” can be given instead. This parameter can
2930 be applied for the rtpengine versions equal or later than mr12.4.
2931
2932 This function can be used from ANY_ROUTE.
2933
2934 Example 1.102. rtpengine_subscribe_request usage
2935 request_route {
2936 ...
2937 if (is_method("INVITE")) {
2938 if (has_body("application/sdp")) {
2939 if (rtpengine_offer())
2940 t_on_reply("1");
2941 }
2942 }
2943 ...
2944 }
2945
2946 onreply_route[1]
2947 {
2948 ...
2949 if (has_body("application/sdp")) {
2950 rtpengine_answer();
2951 rtpengine_subscribe_request("all siprec", "$avp(siprec_offer)",
2952 "$avp(siprec_to_tag)", "siprec_streams");
2953 xinfo("SIPREC participant $xavp(siprec_streams[0]=>tag) with label $xavp
2954 (siprec_streams[0]=>label[0])\n");
2955 xinfo("SIPREC participant $xavp(siprec_streams[1]=>tag) with label $xavp
2956 (siprec_streams[0]=>label[0])\n");
2957 # use the above stream information to build the siprec xml metadata, wil
2958 l just send SDP in this example
2959 $dlg_var(orig_to_tag) = $tt;
2960 $dlg_var(siprec_contact) = "sip:uac@" + $Ri;
2961 $dlg_var(siprec_to_tag) = $avp(siprec_to_tag);
2962 t_uac_send("INVITE" ,"sip:siprec@siprec_server.example.com",
2963 "siprec_server.example.com", "",
2964 "To: <$tu>\r\n" +
2965 "From: <$fu>\r\n" +
2966 "Contact: <$dlg_var(siprec_contact)>\r\n" +
2967 "Content-Type: application/sdp\r\n",
2968 $avp(siprec_offer));
2969 }
2970 ...
2971 }
2972
2973 event_route [tm:local-request] {
2974 if (is_method("INVITE")) {
2975 # save information from the original dialog to the new invite transactio
2976 n
2977 $avp(orig_callid) = $dlg(callid);
2978 $avp(orig_from_tag) = $dlg(from_tag);
2979 $avp(orig_to_tag) = $dlg_var(orig_to_tag);
2980 $avp(siprec_to_tag) = $dlg_var(siprec_to_tag);
2981 $avp(siprec_contact) = $dlg_var(siprec_contact);
2982 t_on_reply("2");
2983 }
2984 if (is_method("ACK")) {
2985 # save the route set in the original dialog
2986 dlg_get($avp(orig_callid), $avp(orig_from_tag), $avp(orig_to_tag));
2987 $dlg_var(siprec_cseq) = $cs;
2988 $dlg_var(siprec_to_hdr) = $hdr(To);
2989 $dlg_var(siprec_from_hdr) = $hdr(From);
2990 append_hf("Contact: <$dlg_var(siprec_contact)>\r\n");
2991
2992 # the same dialog information can be used to send the BYE with t_uac_sen
2993 d
2994 }
2995 }
2996
2997 onreply_route[2] {
2998 if (has_body("application/sdp")) {
2999 rtpengine_subscribe_answer("from-tag=$avp(orig_from_tag) to-tag=$avp(sipr
3000 ec_to_tag) call-id="$avp(orig_callid)");
3001 }
3002 }
3003 ...
3004
3005 15.12. rtpengine_subscribe_answer([flags][,via-branch])
3006
3007 Sends the SDP answer from the recording server to the rtpengine
3008
3009 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
3010 FAILURE_ROUTE, BRANCH_ROUTE.
3011
3012 Meaning of the parameters is as follows:
3013 * flags - flags to turn on some features.
3014 The “flags” string is a list of space-separated items. Each item is
3015 either an individual token, or a token in “key=value” format. The
3016 possible tokens are described below. This offer SDP can be
3017 manipulated with the same flags as used in rtpengine_offer
3018 additionally, the following extra flags can be used
3019 + to-tag=... - value of the to tag returned by
3020 “rtpengine_subscribe_request”
3021 + from-tag=... - value of the from tag of the original call.
3022 + call-id=... - value of the call id of the original call.
3023
3024 Example 1.103. rtpengine_subscribe_answer usage
3025
3026 See rtpengine_subscribe_request() function example above for example.
3027
3028 15.13. rtpengine_unsubscribe([flags][,via-branch])
3029
3030 Sends the SDP answer from the recording server to the rtpengine
3031
3032 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
3033 FAILURE_ROUTE, BRANCH_ROUTE.
3034
3035 Meaning of the parameters is as follows:
3036 * flags - flags to turn on some features.
3037 The “flags” string is a list of space-separated items. Each item is
3038 either an individual token, or a token in “key=value” format. The
3039 possible tokens are described below. This offer SDP can be
3040 manipulated with the same flags as used in rtpengine_offer
3041 additionally, the following extra flags can be used
3042 + to-tag=... - value of the to tag returned by
3043 “rtpengine_subscribe_request”
3044 + from-tag=... - value of the from tag of the original call.
3045 + call-id=... - value of the call id of the original call.
3046
3047 Example 1.104. rtpengine_unsubscribe usage
3048
3049 event_route [dialog:end] {
3050 # call over, stop recording
3051 rtpengine_unsubscribe("from-tag=$avp(orig_from_tag) to-tag=$avp(siprec_to_ta
3052 g) call-id="$avp(orig_callid)");
3053 $var(new_cseq) = $dlg_var(siprec_cseq) + 1;
3054 t_uac_send("BYE", "sip:siprec@siprec_server.example.com",
3055 "siprec_server.example.com", "",
3056 "To: <$dlg_var(siprec_to_hdr)>\r\n" +
3057 "From: <$dlg_var(siprec_from_hdr)>\r\n" +
3058 "Call-ID: $avp(siprec_callid)\r\n" +
3059 "CSeq: $var(new_cseq) BYE\r\n" +
3060 "Contact: $lt;$dlg_var(siprec_contact)>\r\n");
3061 }
3062 ...
3063
3064 15.14. start_recording([flags])
3065
3066 This function will send a signal to the RTP relay to record the RTP
3067 stream flowing through it. See also the option “record-call=on” for
3068 rtpengine_manage()/rtpengine_offer(), which offers an alternative for
3069 call recording, saving also call metadata from SDP.
3070
3071 It can take the same parameters as rtpengine_manage(). The flags
3072 parameter to start_recording can be a configuration variable containing
3073 the flags as a string. The call-id flag can be used to start recording
3074 for a different call.
3075
3076 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
3077
3078 Example 1.105. start_recording usage
3079 ...
3080 start_recording();
3081 ...
3082
3083 15.15. stop_recording([flags])
3084
3085 This function will send a signal to the RTP relay to stop recording the
3086 RTP stream flowing through it. See also the option “record-call=off”
3087 for rtpengine_manage()/rtpengine_offer(), which offers an alternative
3088 for call recording.
3089
3090 It can take the same parameters as rtpengine_manage(). The flags
3091 parameter to start_recording can be a configuration variable containing
3092 the flags as a string. The call-id flag can be used to stop recording
3093 for a different call.
3094
3095 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
3096
3097 Example 1.106. stop_recording usage
3098 ...
3099 stop_recording();
3100 ...
3101
3102 15.16. block_dtmf([flags])
3103
3104 This function will instruct the RTP proxy to start blocking DTMF event
3105 packets (RFC 4733). DTMF events will still be processed by the RTP
3106 proxy, but they won't be forwarded to the receiving peer.
3107
3108 The call-id flag can be used to block DTMF for a different call.
3109
3110 Without any flags given, DTMF events will be blocked for the entire
3111 call. It's possible to block DTMF directionally only for individual
3112 participants. If the “directional” flag is given, DTMF events will be
3113 blocked for the UA with the currently matching “From” tag. Events can
3114 be blocked for a different UA either by specifying an alternative
3115 “from-tag=...”, or by matching UAs against the media address they
3116 advertised in the SDP using the “address=...” flag (which can contain
3117 either an IPv4 or IPv6 address).
3118
3119 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
3120
3121 Example 1.107. block_dtmf usage
3122 ...
3123 block_dtmf();
3124 block_dtmf("directional");
3125 block_dtmf("address=192.168.42.42");
3126 ...
3127
3128 15.17. unblock_dtmf([flags])
3129
3130 Reverses the effects of a previously issued block_dtmf call. See above
3131 for a description of which flags can be used.
3132
3133 If DTMF events were previously blocked for individual UAs, then
3134 unblocking DTMF events for the entire call (i.e. no flags given) will
3135 not remove these blocks. The flag “all” can be used to achieve this.
3136
3137 Example 1.108. unblock_dtmf usage
3138 ...
3139 unblock_dtmf();
3140 unblock_dtmf("all");
3141 ...
3142
3143 15.18. block_media([flags])
3144
3145 Analogous to “block_dtmf”, but blocks media RTP packets instead of DTMF
3146 events. When media is blocked, DTMF events still pass through the RTP
3147 proxy.
3148
3149 See “block_dtmf” for a description of the flags that can be used.
3150
3151 Example 1.109. block_media usage
3152 ...
3153 block_media();
3154 block_media("directional");
3155 block_media("address=192.168.42.42");
3156 ...
3157
3158 15.19. unblock_media([flags])
3159
3160 Analogous to “unblock_dtmf”, but applies to media RTP packets instead
3161 of DTMF events.
3162
3163 See “unblock_dtmf” for a description of the flags that can be used.
3164
3165 Example 1.110. unblock_media usage
3166 ...
3167 unblock_media();
3168 unblock_media("all");
3169 ...
3170
3171 15.20. silence_media([flags])
3172
3173 Identical to “block_media” except that media RTP packets are not simply
3174 blocked, but instead have their audio payload replaced by silence
3175 audio. This is only supported for certain trivial audio codecs (e.g.
3176 G.711, G.722).
3177
3178 See “block_dtmf” for a description of the flags that can be used.
3179
3180 Example 1.111. silence_media usage
3181 ...
3182 silence_media();
3183 silence_media("directional");
3184 silence_media("address=192.168.42.42");
3185 ...
3186
3187 15.21. unsilence_media([flags])
3188
3189 Identical to “unblock_media” except that it's the counterpart to
3190 “silence_media”.
3191
3192 See “unblock_dtmf” for a description of the flags that can be used.
3193
3194 Example 1.112. unsilence_media usage
3195 ...
3196 unsilence_media();
3197 unsilence_media("all");
3198 ...
3199
3200 15.22. start_forwarding([flags])
3201
3202 Controls the PCM forwarding feature of the recording daemon. Unlike the
3203 recording feature, PCM forwarding can be done directionally for
3204 individual call participants only, therefore this command takes the
3205 same flags as the media/DTMF blocking commands above.
3206
3207 See “block_dtmf” for a description of the flags that can be used.
3208
3209 Example 1.113. start_forwarding usage
3210 ...
3211 start_forwarding();
3212 start_forwarding("directional");
3213 start_forwarding("address=192.168.42.42");
3214 ...
3215
3216 15.23. stop_forwarding([flags])
3217
3218 Analogous to “unblock_dtmf”, but controls the PCM forwarding feature
3219 instead of DTMF blocking.
3220
3221 See “unblock_dtmf” for a description of the flags that can be used.
3222
3223 Example 1.114. stop_forwarding usage
3224 ...
3225 stop_forwarding();
3226 stop_forwarding("all");
3227 ...
3228
3229 15.24. play_media([flags])
3230
3231 Instructs rtpengine to play a prerecorded announcement to the selected
3232 call participant, either from a local file or from a file stored in a
3233 database. The participant must be selected using the same flags as are
3234 described under the “block_dtmf” function. If none of these flags are
3235 given, then the “From” tag from the current SIP message context is
3236 used.
3237
3238 If successful, the “media_duration” pseudovariable is filled in with
3239 the duration of the media being played, expressed in milliseconds. If
3240 the length of the media could not be determined, it's set to -1.
3241
3242 Example 1.115. play_media usage
3243 ...
3244 play_media("file=/use/share/media/hello.wav");
3245 play_media("from-tag=tfugklbildfydrtuykgfv db-id=12345");
3246 ...
3247
3248 15.25. stop_media([flags])
3249
3250 Stops the playback of media previously started by “play_media”. Media
3251 playback is automatically stopped when the end of the media file is
3252 reached, so this function is only useful to prematurely stop playback.
3253
3254 Example 1.116. stop_media usage
3255 ...
3256 stop_media();
3257 stop_media("from-tag=5yqaeriguhxcikxj");
3258 ...
3259
3260 15.26. play_dtmf([flags])
3261
3262 Injects a DTMF event into the media stream. Depending on which codecs
3263 were negotiated, this either injects an RFC 2833/4733 DTMF event, or an
3264 in-band PCM DTMF tone into the audio stream. The flag “inject DTMF”
3265 must have been present in both offer and answer messages when the call
3266 was established, which forces all audio to go through rtpengine's
3267 transcoding engine.
3268
3269 Usage is similar to “play_media” with the following exceptions. The
3270 selected party is not the party that will receive the DTMF event, but
3271 rather the party which is generating the event. This is to support DTMF
3272 events that are carried in SIP INFO messages. Instead of specifying a
3273 media file, a DTMF event code must be specified, as well as optionally
3274 a duration and the volume. The “code” can be a number 0 through 15, or
3275 a DTMF digit (0-9, A-D, *, #). The “duration” is specified in
3276 milliseconds and defaults to 250, within a range of 100-5000. The
3277 “volume” is specified in absolute decibels, with a default of -8 db.
3278
3279 Multiple consecutive DTMF events can be queued up by calling this
3280 function multiple times consecutively. RTPengine will play out the DTMF
3281 events in sequence, separated by a default pause of 100 ms. An
3282 alternative pause length can be given through the “pause” option,
3283 between 100 and 5000 ms.
3284
3285 Example 1.117. play_dtmf usage
3286 ...
3287 play_dtmf("from-tag=5yqaeriguhxcikxj code=#");
3288 play_dtmf("code=1 volume=5 duration=300 pause=150");
3289 ...
3290
3291 16. Exported Pseudo Variables
3292
3293 16.1. $rtpestat
3294 16.2. $rtpstat
3295
3296 16.1. $rtpestat
3297
3298 Returns the RTP statistics from the RTP relay. The RTP statistics from
3299 the RTP relay are provided as a string and it does contain several
3300 packet counters. The statistics must be retrieved before the session is
3301 deleted (before rtpengine_delete()).
3302
3303 Example 1.118. $rtpestat Usage
3304 ...
3305 append_hf("X-RTP-Statistics: $rtpestat\r\n");
3306 ...
3307 # $rtpestat = RTP: 54846 bytes, 1447 packets, 0 errors; RTCP: 336 bytes, 3 packe
3308 ts, 0 errors
3309 ...
3310
3311 16.2. $rtpstat
3312
3313 Same as $rtpestat.
3314
3315 17. RPC Commands
3316
3317 17.1. rtpengine.reload
3318 17.2. rtpengine.enable proxy_url/all 0/1
3319 17.3. rtpengine.show proxy_url/all
3320 17.4. rtpengine.ping proxy_url/all
3321 17.5. rtpengine.get_hash_total
3322
3323 17.1. rtpengine.reload
3324
3325 Reloads the database node table content if configured. Returns specific
3326 message related to success, failure and no db_url configured.
3327
3328 NOTE: The current behaviour updates the nodes state or creates new ones
3329 or hides old ones, based on the database content. If allow_op modparam
3330 is enabled, the sessions are still allowed to finish for the hidden old
3331 nodes.
3332
3333 The execution of this command is limited to 10 seconds intervals.
3334
3335 Example 1.119. rtpengine.reload usage
3336 ...
3337 $ kamctl rpc rtpengine.reload
3338 ...
3339
3340 17.2. rtpengine.enable proxy_url/all 0/1
3341
3342 Enables a RTP proxy if the second parameter value is greater than 0.
3343 Disables it if a zero value is given. The first parameter is either a
3344 specific RTP proxy url (exactly as defined in the config file) or the
3345 keyword all. The second parameter value must be a number in decimal.
3346
3347 When try to enable the RTP proxy, an application ping command is sent
3348 to it. If it fails, the proxy is not enabled. Displays success or fail
3349 when try to enable/disable.
3350
3351 NOTE: If a RTP proxy is defined multiple times (in the same or
3352 different sets), all of its instances will be enabled/disabled.
3353
3354 NOTE: If a RTP proxy is in the disabled permanent state and one tries
3355 to enable it, even if the ping fails, it is moved to a disabled
3356 temporary state and a recheck_ticks are given to it. While the
3357 recheck_ticks are grater than 0, the proxy is considered disabled
3358 temporary, and it is not taken into consideration for sending data.
3359 When the recheck_ticks are 0, the proxy is retested when trying to send
3360 data (not automatically retested), and data can be sent to it on
3361 success.
3362
3363 NOTE: If you specify an IPv6 RTP, the proxy url must be prefixed with
3364 :: to escape the :: from the IPv6 address. See the example below.
3365
3366 Example 1.120. rtpengine.enable usage
3367 ...
3368 $ kamctl rpc rtpengine.enable udp:192.168.2.133:8081 0
3369 $ kamctl rpc rtpengine.enable ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
3370 $ kamctl rpc rtpengine.enable all 1
3371 ...
3372
3373 17.3. rtpengine.show proxy_url/all
3374
3375 Displays all the RTP proxies and their information: set and status
3376 (disabled or not, weight and recheck_ticks). If a RTP proxy has been
3377 disabled by nh_enable_rtpp mi command a "(permanent)" quote will appear
3378 when printing the disabled status. This is to differentiate from a
3379 temporary disable due to the proxy being not found responsive by
3380 kamailio. In addition, when disabled permanent, recheck_ticks have no
3381 meaning and "N\A" is printed instead of the value.
3382
3383 It takes either a specific RTP proxy url (exactly as defined in the
3384 config file) or the keyword all as a parameter.
3385
3386 NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
3387 escape the :: from the IPv6 address. See the example below.
3388
3389 Example 1.121. rtpengine.show usage
3390 ...
3391 $ kamctl rpc rtpengine.show udp:192.168.2.133:8081
3392 $ kamctl rpc rtpengine.show ::udp6:fe80::9a90:96ff:fea8:fd99:9999
3393 $ kamctl rpc rtpengine.show all
3394 ...
3395
3396 17.4. rtpengine.ping proxy_url/all
3397
3398 Sends an application ping command to the RTP proxy. If the proxy does
3399 not respond, it will be disabled, but not permanent. If the proxy
3400 responds, no action is taken. Displays the ping result, i.e. success or
3401 fail when try to ping.
3402
3403 It takes either a specific RTP proxy url (exactly as defined in the
3404 config file) or the keyword all as a parameter.
3405
3406 NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
3407 escape the :: from the IPv6 address. See the example below.
3408
3409 Example 1.122. rtpengine.ping usage
3410 ...
3411 $ kamctl rpc rtpengine.ping udp:192.168.2.133:8081
3412 $ kamctl rpc rtpengine.ping ::udp6:fe80::9a90:96ff:fea8:fd99:9999
3413 $ kamctl rpc rtpengine.ping all
3414 ...
3415
3416 17.5. rtpengine.get_hash_total
3417
3418 Print the total number of hash entries in the hash table at a given
3419 moment.
3420
3421 Example 1.123. rtpengine.get_hash_total usage
3422 ...
3423 $ kamctl rpc rtpengine.get_hash_total
3424 ...
3425
3426 18. Event routes
3427
3428 18.1. rtpengine:dtmf-event
3429
3430 18.1. rtpengine:dtmf-event
3431
3432 When defined, the module calls event_route[rtpengine:dtmf-event] when a
3433 DTMF is received.
3434 ...
3435 event_route[rtpengine:dtmf-event] {
3436 xlog("L_INFO", "callid: $avp(dtmf_event_callid)\n");
3437 xlog("L_INFO", "source_tag: $avp(dtmf_event_source_tag)\n");
3438 xlog("L_INFO", "timestamp: $avp(dtmf_event_timestamp)\n");
3439 xlog("L_INFO", "dtmf: $avp(dtmf_event)\n");
3440 }
3441 ...
3442
3443 Chapter 2. Frequently Asked Questions
3444
3445 2.1. How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
3446 2.2. Where can I find more about Kamailio?
3447 2.3. Where can I post a question about this module?
3448 2.4. How can I report a bug?
3449
3450 2.1.
3451
3452 How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
3453
3454 For the most part, only the names of the functions have changed, with
3455 “rtpproxy” in each name replaced with “rtpengine”. For example,
3456 “rtpproxy_manage()” has become “rtpengine_manage()”. A few name
3457 duplications have also been resolved, for example there is now a single
3458 “rtpengine_delete()” instead of “unforce_rtp_proxy()” and the identical
3459 “rtpproxy_destroy()”.
3460
3461 The largest difference to the old module is how flags are passed to
3462 “rtpengine_offer()”, “rtpengine_answer()”, “rtpengine_manage()” and
3463 “rtpengine_delete()”. Instead of having a string of single-letter
3464 flags, they now take a string of space-separated items, with each item
3465 being either a single token (word) or a “key=value” pair.
3466
3467 For example, if you had a call “rtpproxy_offer("FRWOC+PS");”, this
3468 would then become:
3469 rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
3470 nnection ICE=force RTP/SAVPF");
3471
3472 Finally, if you were using the second parameter (explicit media
3473 address) to any of these functions, this has been replaced by the
3474 “media-address=...” option within the first string of flags.
3475
3476 2.2.
3477
3478 Where can I find more about Kamailio?
3479
3480 Take a look at https://www.kamailio.org/.
3481
3482 2.3.
3483
3484 Where can I post a question about this module?
3485
3486 First at all check if your question was already answered on one of our
3487 mailing lists:
3488 * User Mailing List -
3489 https://lists.kamailio.org/mailman3/postorius/lists/sr-users.lists.
3490 kamailio.org/
3491 * Developer Mailing List -
3492 https://lists.kamailio.org/mailman3/postorius/lists/sr-dev.lists.ka
3493 mailio.org/
3494
3495 E-mails regarding any stable Kamailio release should be sent to
3496 <[email protected]> and e-mails regarding development
3497 versions should be sent to <[email protected]>.
3498
3499 2.4.
3500
3501 How can I report a bug?
3502
3503 Please follow the guidelines provided at:
3504 https://github.com/kamailio/kamailio/issues.