29 Copyright © 2003-2008 Sippy Software, Inc.
31 Copyright © 2005 Voice Sistem SRL
33 Copyright © 2009-2014 TuTPro Inc.
35 Copyright © 2010 VoIPEmbedded Inc.
37 Copyright © 2013-2019 Sipwise GmbH
38 __________________________________________________________________
45 2. Usage With Multiple RTPEngine Instances
49 3.2. External Libraries or Applications
53 4.1. rtpengine_sock (string)
54 4.2. rtpengine_disable_tout (integer)
55 4.3. aggressive_redetection (integer)
56 4.4. rtpengine_tout_ms (integer)
57 4.5. rtpengine_allow_op (integer)
58 4.6. queried_nodes_limit (integer)
59 4.7. rtpengine_retr (integer)
60 4.8. extra_id_pv (string)
61 4.9. setid_avp (string)
62 4.10. force_send_interface (string)
63 4.11. read_sdp_pv (string)
64 4.12. write_sdp_pv (string)
65 4.13. rtp_inst_pvar (string)
66 4.14. hash_table_size (integer)
67 4.15. hash_table_tout (integer)
69 4.17. table_name (string)
70 4.18. setid_col (string)
71 4.19. url_col (string)
72 4.20. weight_col (string)
73 4.21. disabled_col (string)
74 4.22. setid_default (integer)
75 4.23. media_duration (string)
76 4.24. mos_min_pv (string)
77 4.25. mos_min_at_pv (string)
78 4.26. mos_min_packetloss_pv (string)
79 4.27. mos_min_jitter_pv (string)
80 4.28. mos_min_roundtrip_pv (string)
81 4.29. mos_max_pv (string)
82 4.30. mos_max_at_pv (string)
83 4.31. mos_max_packetloss_pv (string)
84 4.32. mos_max_jitter_pv (string)
85 4.33. mos_max_roundtrip_pv (string)
86 4.34. mos_average_pv (string)
87 4.35. mos_average_packetloss_pv (string)
88 4.36. mos_average_jitter_pv (string)
89 4.37. mos_average_roundtrip_pv (string)
90 4.38. mos_average_samples_pv (string)
91 4.39. mos_A_label_pv (string)
92 4.40. mos_min_A_pv (string)
93 4.41. mos_min_at_A_pv (string)
94 4.42. mos_min_packetloss_A_pv (string)
95 4.43. mos_min_jitter_A_pv (string)
96 4.44. mos_min_roundtrip_A_pv (string)
97 4.45. mos_max_A_pv (string)
98 4.46. mos_max_at_A_pv (string)
99 4.47. mos_max_packetloss_A_pv (string)
100 4.48. mos_max_jitter_A_pv (string)
101 4.49. mos_max_roundtrip_A_pv (string)
102 4.50. mos_average_A_pv (string)
103 4.51. mos_average_packetloss_A_pv (string)
104 4.52. mos_average_jitter_A_pv (string)
105 4.53. mos_average_roundtrip_A_pv (string)
106 4.54. mos_average_samples_A_pv (string)
107 4.55. mos_B_label_pv (string)
108 4.56. mos_min_B_pv (string)
109 4.57. mos_min_at_B_pv (string)
110 4.58. mos_min_packetloss_B_pv (string)
111 4.59. mos_min_jitter_B_pv (string)
112 4.60. mos_min_roundtrip_B_pv (string)
113 4.61. mos_max_B_pv (string)
114 4.62. mos_max_at_B_pv (string)
115 4.63. mos_max_packetloss_B_pv (string)
116 4.64. mos_max_jitter_B_pv (string)
117 4.65. mos_max_roundtrip_B_pv (string)
118 4.66. mos_average_B_pv (string)
119 4.67. mos_average_packetloss_B_pv (string)
120 4.68. mos_average_jitter_B_pv (string)
121 4.69. mos_average_roundtrip_B_pv (string)
122 4.70. mos_average_samples_B_pv (string)
123 4.71. control_cmd_tos (integer)
124 4.72. hash_algo (integer)
128 5.1. set_rtpengine_set(setid[, setid])
129 5.2. rtpengine_offer([flags])
130 5.3. rtpengine_answer([flags])
131 5.4. rtpengine_info([flags])
132 5.5. rtpengine_delete([flags])
133 5.6. rtpengine_query([flags])
134 5.7. rtpengine_manage([flags])
135 5.8. start_recording([flags])
136 5.9. stop_recording([flags])
137 5.10. block_dtmf([flags])
138 5.11. unblock_dtmf([flags])
139 5.12. block_media([flags])
140 5.13. unblock_media([flags])
141 5.14. start_forwarding([flags])
142 5.15. stop_forwarding([flags])
143 5.16. play_media([flags])
144 5.17. stop_media([flags])
145 5.18. play_dtmf([flags])
147 6. Exported Pseudo Variables
153 7.1. rtpengine.reload
154 7.2. rtpengine.enable proxy_url/all 0/1
155 7.3. rtpengine.show proxy_url/all
156 7.4. rtpengine.ping proxy_url/all
157 7.5. rtpengine.get_hash_total
159 2. Frequently Asked Questions
163 1.1. Set rtpengine_sock parameter
164 1.2. Set rtpengine_disable_tout parameter
165 1.3. Set aggressive_redetection parameter
166 1.4. Set rtpengine_tout_ms parameter
167 1.5. Set rtpengine_allow_op parameter
168 1.6. Set queried_nodes_limit parameter
169 1.7. Set rtpengine_retr parameter
170 1.8. Set extra_id_pv parameter
171 1.9. Set setid_avp parameter
172 1.10. Set force_send_interface parameter
173 1.11. Set read_sdp_pv parameter
174 1.12. Set write_sdp_pv parameter
175 1.13. Set rtp_inst_pvar parameter
176 1.14. Set hash_table_size parameter
177 1.15. Set hash_table_tout parameter
178 1.16. Set db_url parameter
179 1.17. Set table_name parameter
180 1.18. Setup rtpengine table
181 1.19. Set setid_col parameter
182 1.20. Set url_col parameter
183 1.21. Set weight_col parameter
184 1.22. Set disabled_col parameter
185 1.23. Set setid_default parameter
186 1.24. Set media_duration parameter
187 1.25. Set mos_min_pv parameter
188 1.26. Set mos_min_at_pv parameter
189 1.27. Set mos_min_packetloss_pv parameter
190 1.28. Set mos_min_jitter_pv parameter
191 1.29. Set mos_min_roundtrip_pv parameter
192 1.30. Set mos_max_pv parameter
193 1.31. Set mos_max_at_pv parameter
194 1.32. Set mos_max_packetloss_pv parameter
195 1.33. Set mos_max_jitter_pv parameter
196 1.34. Set mos_max_roundtrip_pv parameter
197 1.35. Set mos_average_pv parameter
198 1.36. Set mos_average_packetloss_pv parameter
199 1.37. Set mos_average_jitter_pv parameter
200 1.38. Set mos_average_roundtrip_pv parameter
201 1.39. Set mos_average_samples_pv parameter
202 1.40. Set mos_A_label_pv parameter
203 1.41. Set mos_min_A_pv parameter
204 1.42. Set mos_min_at_A_pv parameter
205 1.43. Set mos_min_packetloss_A_pv parameter
206 1.44. Set mos_min_jitter_A_pv parameter
207 1.45. Set mos_min_roundtrip_A_pv parameter
208 1.46. Set mos_max_A_pv parameter
209 1.47. Set mos_max_at_A_pv parameter
210 1.48. Set mos_max_packetloss_A_pv parameter
211 1.49. Set mos_max_jitter_A_pv parameter
212 1.50. Set mos_max_roundtrip_A_pv parameter
213 1.51. Set mos_average_A_pv parameter
214 1.52. Set mos_average_packetloss_A_pv parameter
215 1.53. Set mos_average_jitter_A_pv parameter
216 1.54. Set mos_average_roundtrip_A_pv parameter
217 1.55. Set mos_average_samples_A_pv parameter
218 1.56. Set mos_B_label_pv parameter
219 1.57. Set mos_min_B_pv parameter
220 1.58. Set mos_min_at_B_pv parameter
221 1.59. Set mos_min_packetloss_B_pv parameter
222 1.60. Set mos_min_jitter_B_pv parameter
223 1.61. Set mos_min_roundtrip_B_pv parameter
224 1.62. Set mos_max_B_pv parameter
225 1.63. Set mos_max_at_B_pv parameter
226 1.64. Set mos_max_packetloss_B_pv parameter
227 1.65. Set mos_max_jitter_B_pv parameter
228 1.66. Set mos_max_roundtrip_B_pv parameter
229 1.67. Set mos_average_B_pv parameter
230 1.68. Set mos_average_packetloss_B_pv parameter
231 1.69. Set mos_average_jitter_B_pv parameter
232 1.70. Set mos_average_roundtrip_B_pv parameter
233 1.71. Set mos_average_samples_B_pv parameter
234 1.72. Set control_cmd_tos parameter
235 1.73. Set control_cmd_tos parameter
236 1.74. set_rtpengine_set usage
237 1.75. rtpengine_offer usage
238 1.76. rtpengine_answer usage
239 1.77. rtpengine_info usage
240 1.78. rtpengine_delete usage
241 1.79. rtpengine_query usage
242 1.80. rtpengine_manage usage
243 1.81. start_recording usage
244 1.82. stop_recording usage
245 1.83. block_dtmf usage
246 1.84. unblock_dtmf usage
247 1.85. block_media usage
248 1.86. unblock_media usage
249 1.87. start_forwarding usage
250 1.88. stop_forwarding usage
251 1.89. play_media usage
252 1.90. stop_media usage
253 1.91. play_dtmf usage
255 1.93. rtpengine.reload usage
256 1.94. rtpengine.enable usage
257 1.95. rtpengine.show usage
258 1.96. rtpengine.ping usage
259 1.97. rtpengine.get_hash_total usage
261 Chapter 1. Admin Guide
266 2. Usage With Multiple RTPEngine Instances
269 3.1. Kamailio Modules
270 3.2. External Libraries or Applications
274 4.1. rtpengine_sock (string)
275 4.2. rtpengine_disable_tout (integer)
276 4.3. aggressive_redetection (integer)
277 4.4. rtpengine_tout_ms (integer)
278 4.5. rtpengine_allow_op (integer)
279 4.6. queried_nodes_limit (integer)
280 4.7. rtpengine_retr (integer)
281 4.8. extra_id_pv (string)
282 4.9. setid_avp (string)
283 4.10. force_send_interface (string)
284 4.11. read_sdp_pv (string)
285 4.12. write_sdp_pv (string)
286 4.13. rtp_inst_pvar (string)
287 4.14. hash_table_size (integer)
288 4.15. hash_table_tout (integer)
289 4.16. db_url (string)
290 4.17. table_name (string)
291 4.18. setid_col (string)
292 4.19. url_col (string)
293 4.20. weight_col (string)
294 4.21. disabled_col (string)
295 4.22. setid_default (integer)
296 4.23. media_duration (string)
297 4.24. mos_min_pv (string)
298 4.25. mos_min_at_pv (string)
299 4.26. mos_min_packetloss_pv (string)
300 4.27. mos_min_jitter_pv (string)
301 4.28. mos_min_roundtrip_pv (string)
302 4.29. mos_max_pv (string)
303 4.30. mos_max_at_pv (string)
304 4.31. mos_max_packetloss_pv (string)
305 4.32. mos_max_jitter_pv (string)
306 4.33. mos_max_roundtrip_pv (string)
307 4.34. mos_average_pv (string)
308 4.35. mos_average_packetloss_pv (string)
309 4.36. mos_average_jitter_pv (string)
310 4.37. mos_average_roundtrip_pv (string)
311 4.38. mos_average_samples_pv (string)
312 4.39. mos_A_label_pv (string)
313 4.40. mos_min_A_pv (string)
314 4.41. mos_min_at_A_pv (string)
315 4.42. mos_min_packetloss_A_pv (string)
316 4.43. mos_min_jitter_A_pv (string)
317 4.44. mos_min_roundtrip_A_pv (string)
318 4.45. mos_max_A_pv (string)
319 4.46. mos_max_at_A_pv (string)
320 4.47. mos_max_packetloss_A_pv (string)
321 4.48. mos_max_jitter_A_pv (string)
322 4.49. mos_max_roundtrip_A_pv (string)
323 4.50. mos_average_A_pv (string)
324 4.51. mos_average_packetloss_A_pv (string)
325 4.52. mos_average_jitter_A_pv (string)
326 4.53. mos_average_roundtrip_A_pv (string)
327 4.54. mos_average_samples_A_pv (string)
328 4.55. mos_B_label_pv (string)
329 4.56. mos_min_B_pv (string)
330 4.57. mos_min_at_B_pv (string)
331 4.58. mos_min_packetloss_B_pv (string)
332 4.59. mos_min_jitter_B_pv (string)
333 4.60. mos_min_roundtrip_B_pv (string)
334 4.61. mos_max_B_pv (string)
335 4.62. mos_max_at_B_pv (string)
336 4.63. mos_max_packetloss_B_pv (string)
337 4.64. mos_max_jitter_B_pv (string)
338 4.65. mos_max_roundtrip_B_pv (string)
339 4.66. mos_average_B_pv (string)
340 4.67. mos_average_packetloss_B_pv (string)
341 4.68. mos_average_jitter_B_pv (string)
342 4.69. mos_average_roundtrip_B_pv (string)
343 4.70. mos_average_samples_B_pv (string)
344 4.71. control_cmd_tos (integer)
345 4.72. hash_algo (integer)
349 5.1. set_rtpengine_set(setid[, setid])
350 5.2. rtpengine_offer([flags])
351 5.3. rtpengine_answer([flags])
352 5.4. rtpengine_info([flags])
353 5.5. rtpengine_delete([flags])
354 5.6. rtpengine_query([flags])
355 5.7. rtpengine_manage([flags])
356 5.8. start_recording([flags])
357 5.9. stop_recording([flags])
358 5.10. block_dtmf([flags])
359 5.11. unblock_dtmf([flags])
360 5.12. block_media([flags])
361 5.13. unblock_media([flags])
362 5.14. start_forwarding([flags])
363 5.15. stop_forwarding([flags])
364 5.16. play_media([flags])
365 5.17. stop_media([flags])
366 5.18. play_dtmf([flags])
368 6. Exported Pseudo Variables
374 7.1. rtpengine.reload
375 7.2. rtpengine.enable proxy_url/all 0/1
376 7.3. rtpengine.show proxy_url/all
377 7.4. rtpengine.ping proxy_url/all
378 7.5. rtpengine.get_hash_total
382 This is a module that enables media streams to be proxied via an RTP
383 proxy. The only RTP proxy currently known to work with this module is
384 the Sipwise rtpengine https://github.com/sipwise/rtpengine. The
385 rtpengine module is a modified version of the original rtpproxy module
386 using a new control protocol. The module is designed to be a drop-in
387 replacement for the old module from a configuration file point of view,
388 however due to the incompatible control protocol, it only works with
389 RTP proxies which specifically support it.
391 2. Usage With Multiple RTPEngine Instances
393 The rtpengine module can support multiple RTPEngine instances for
394 balancing/distribution and control/selection purposes.
396 The module allows definition of several sets of RTPEngines.
397 Load-balancing will be performed over a set and the admin has the
398 ability to choose what set should be used. The set is selected via its
399 id - the id being defined with the set. Refer to the “rtpengine_sock”
400 module parameter definition for syntax description.
402 The balancing inside a set is done automatically by the module based on
403 the weight of each RTPEngine from the set.
405 The selection of the set is done from script prior using
406 rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions -
407 see the set_rtpengine_set() function.
409 Another way to select the set is to define setid_avp module parameter
410 and assign setid to the defined avp before calling rtpengine_offer() or
411 rtpengine_manage() function. If forwarding of the requests fails and
412 there is another branch to try, remember to unset the avp after calling
413 rtpengine_delete() function.
415 For backward compatibility reasons, a set with no id take by default
416 the id 0. Also if no set is explicitly set before rtpengine_delete(),
417 rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
419 IMPORTANT: if you use multiple sets, take care and use the same set for
420 both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
421 the set was selected using setid_avp, the avp needs to be set only once
422 before rtpengine_offer() or rtpengine_manage() call.
424 From the current implementation point of view, the sets of rtpengine
425 nodes are in shared memory(shm), so all processes can see a common list
426 of nodes. There is no locking when setting the nodes enabled/disabled
427 (to keep the memory access as fast as possible). Thus, problems related
428 to node state might appear for concurrent processes that might set the
429 nodes enabled/disabled(e.g. by fifo command). This robustness problems
430 are overcome as follows.
432 If the current process sees the selected node as disabled, the node is
433 force tested before the current process actually takes the disabled
434 decision. If the test succeeds, the process will set the node as
435 enabled (but other concurrent process might still see it as disabled).
438 If the current process sees the selected node as enabled, it does no
439 additional checks and sends the command which will fail in case the
440 machine is actually broken. The process will set the node as disabled
441 (but other concurrent process might still see it as enabled).
443 The 'kamctl fifo' commands (including rtpengine ones) are executed by
444 an exclusive process which operate on the same shared memory node list.
446 All the nodes are pinged in the beginning by all the processes, even if
447 the node list is shared memory.
451 3.1. Kamailio Modules
452 3.2. External Libraries or Applications
454 3.1. Kamailio Modules
456 The following modules must be loaded before this module:
457 * tm module - (optional) if you want to have rtpengine_manage() fully
460 3.2. External Libraries or Applications
462 The following libraries or applications must be installed before
463 running Kamailio with this module loaded:
468 4.1. rtpengine_sock (string)
469 4.2. rtpengine_disable_tout (integer)
470 4.3. aggressive_redetection (integer)
471 4.4. rtpengine_tout_ms (integer)
472 4.5. rtpengine_allow_op (integer)
473 4.6. queried_nodes_limit (integer)
474 4.7. rtpengine_retr (integer)
475 4.8. extra_id_pv (string)
476 4.9. setid_avp (string)
477 4.10. force_send_interface (string)
478 4.11. read_sdp_pv (string)
479 4.12. write_sdp_pv (string)
480 4.13. rtp_inst_pvar (string)
481 4.14. hash_table_size (integer)
482 4.15. hash_table_tout (integer)
483 4.16. db_url (string)
484 4.17. table_name (string)
485 4.18. setid_col (string)
486 4.19. url_col (string)
487 4.20. weight_col (string)
488 4.21. disabled_col (string)
489 4.22. setid_default (integer)
490 4.23. media_duration (string)
491 4.24. mos_min_pv (string)
492 4.25. mos_min_at_pv (string)
493 4.26. mos_min_packetloss_pv (string)
494 4.27. mos_min_jitter_pv (string)
495 4.28. mos_min_roundtrip_pv (string)
496 4.29. mos_max_pv (string)
497 4.30. mos_max_at_pv (string)
498 4.31. mos_max_packetloss_pv (string)
499 4.32. mos_max_jitter_pv (string)
500 4.33. mos_max_roundtrip_pv (string)
501 4.34. mos_average_pv (string)
502 4.35. mos_average_packetloss_pv (string)
503 4.36. mos_average_jitter_pv (string)
504 4.37. mos_average_roundtrip_pv (string)
505 4.38. mos_average_samples_pv (string)
506 4.39. mos_A_label_pv (string)
507 4.40. mos_min_A_pv (string)
508 4.41. mos_min_at_A_pv (string)
509 4.42. mos_min_packetloss_A_pv (string)
510 4.43. mos_min_jitter_A_pv (string)
511 4.44. mos_min_roundtrip_A_pv (string)
512 4.45. mos_max_A_pv (string)
513 4.46. mos_max_at_A_pv (string)
514 4.47. mos_max_packetloss_A_pv (string)
515 4.48. mos_max_jitter_A_pv (string)
516 4.49. mos_max_roundtrip_A_pv (string)
517 4.50. mos_average_A_pv (string)
518 4.51. mos_average_packetloss_A_pv (string)
519 4.52. mos_average_jitter_A_pv (string)
520 4.53. mos_average_roundtrip_A_pv (string)
521 4.54. mos_average_samples_A_pv (string)
522 4.55. mos_B_label_pv (string)
523 4.56. mos_min_B_pv (string)
524 4.57. mos_min_at_B_pv (string)
525 4.58. mos_min_packetloss_B_pv (string)
526 4.59. mos_min_jitter_B_pv (string)
527 4.60. mos_min_roundtrip_B_pv (string)
528 4.61. mos_max_B_pv (string)
529 4.62. mos_max_at_B_pv (string)
530 4.63. mos_max_packetloss_B_pv (string)
531 4.64. mos_max_jitter_B_pv (string)
532 4.65. mos_max_roundtrip_B_pv (string)
533 4.66. mos_average_B_pv (string)
534 4.67. mos_average_packetloss_B_pv (string)
535 4.68. mos_average_jitter_B_pv (string)
536 4.69. mos_average_roundtrip_B_pv (string)
537 4.70. mos_average_samples_B_pv (string)
538 4.71. control_cmd_tos (integer)
539 4.72. hash_algo (integer)
541 4.1. rtpengine_sock (string)
543 Definition of socket(s) used to connect to (a set) RTP proxy. It may
544 specify a UNIX socket or an IPv4/IPv6 UDP socket.
546 Default value is “NONE” (disabled).
548 Example 1.1. Set rtpengine_sock parameter
551 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
552 # multiple rtproxies for LB with weights (missing weight defaults to 1)
553 modparam("rtpengine", "rtpengine_sock",
554 "udp:localhost:12221=2 udp:localhost:12222=1")
555 # multiple sets of multiple rtproxies
556 modparam("rtpengine", "rtpengine_sock",
557 "1 == udp:localhost:12221 udp:localhost:12222")
558 modparam("rtpengine", "rtpengine_sock",
559 "2 == udp:localhost:12225")
562 4.2. rtpengine_disable_tout (integer)
564 Once an RTP proxy was found unreachable and marked as disabled, the
565 rtpengine module will not attempt to establish communication to that
566 RTP proxy for rtpengine_disable_tout seconds.
568 Default value is “60”.
570 Can be set at runtime, e.g.:
571 $ kamcmd cfg.set_now_int rtpengine rtpengine_disable_tou
574 Example 1.2. Set rtpengine_disable_tout parameter
576 modparam("rtpengine", "rtpengine_disable_tout", 20)
579 4.3. aggressive_redetection (integer)
581 This parameter determines what happens when all potential rtpengines
582 are found to be unreachable. If enabled, the sip server will send pings
583 to all rtpengines, else no rtpengine will be queried until its
584 rtpengine_disable_tout timeout passes.
586 Default value is “1”.
588 Can be set at runtime, e.g.:
589 $ kamcmd cfg.set_now_int rtpengine aggressive_redetectio
592 Example 1.3. Set aggressive_redetection parameter
594 modparam("rtpengine", "aggressive_redetection", 0)
597 4.4. rtpengine_tout_ms (integer)
599 Timeout value expressed in milliseconds in waiting for reply from RTP
602 Default value is “1000”.
604 Can be set at runtime, e.g.:
605 $ kamcmd cfg.set_now_int rtpengine rtpengine_tout_ms 100
608 Example 1.4. Set rtpengine_tout_ms parameter
610 modparam("rtpengine", "rtpengine_tout_ms", 2000)
613 4.5. rtpengine_allow_op (integer)
615 Enable this to allow finishing the current sessions while denying new
616 sessions for the manually deactivated nodes via kamctl command i.e.
617 "disabled(permanent)" nodes. Probably the manually deactivated machine
618 is still running(did not crash).
620 This is useful when deactivating a node for maintenance and reject new
621 sessions but allow current ones to finish.
623 The behaviour is the same for a rtpengine deleted table node. When the
624 node is deleted from the table and the table reloaded (see
625 nh_reload_rtpp) the node actually is disabled(permanent) and hidden for
626 display. Next time the same node will be added in the table, and the
627 content reloaded, it will be updated and re-displayed.
629 Default value is “0” to keep the current behaviour.
631 Example 1.5. Set rtpengine_allow_op parameter
633 modparam("rtpengine", "rtpengine_allow_op", 1)
636 4.6. queried_nodes_limit (integer)
638 The total number of nodes inside a set (sets are configurable via
639 rtpengine_sock function) to be queried before giving up establishing a
640 session. This brings more flexibility in case checking all rtpengines
641 would take too long. Max limit is 30.
643 By default all nodes in a set are tried before giving up communicating
646 Can be set at runtime, e.g.:
647 $ kamcmd cfg.set_now_int rtpengine queried_nodes_limit 5
649 Example 1.6. Set queried_nodes_limit parameter
651 modparam("rtpengine", "queried_nodes_limit", 5)
654 4.7. rtpengine_retr (integer)
656 How many times the module should retry to send and receive after
657 timeout was generated.
659 Default value is “5”.
661 Can be set at runtime, e.g.:
662 $ kamcmd cfg.set_now_int rtpengine rtpengine_retr 5
664 Example 1.7. Set rtpengine_retr parameter
666 modparam("rtpengine", "rtpengine_retr", 2)
669 4.8. extra_id_pv (string)
671 The parameter sets the PV definition to use when the “via-branch”
672 parameter is used on rtpengine_delete(), rtpengine_offer(),
673 rtpengine_answer() or rtpengine_manage() command.
675 Default is empty, the “via-branch” parameter may not be used then.
677 Example 1.8. Set extra_id_pv parameter
679 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
682 4.9. setid_avp (string)
684 The parameter defines an AVP that, if set, determines which RTP proxy
685 set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
686 rtpengine_manage() functions use.
688 There is no default value.
690 Example 1.9. Set setid_avp parameter
692 modparam("rtpengine", "setid_avp", "$avp(setid)")
695 4.10. force_send_interface (string)
697 Forces all control messages between the SIP proxy and the RTP proxy to
698 be sent from the specified local interface. Both IPv4 and IPv6
699 addresses are supported. If not specified, the default interface
700 selected by the operating system will be used. Note: when
701 rtpengine_sock is a IPv6 link-local address, one _must_ set this
702 parameter in order to successfully connect to RTP engine. This is
703 necessarily because OS needs additional scope_id hint to communicate
704 over IPv6 link locals. The scope_id is resolved based on the given
707 There is no default value.
709 Example 1.10. Set force_send_interface parameter
711 modparam("rtpengine", "force_send_interface", "10.3.7.123")
712 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
716 4.11. read_sdp_pv (string)
718 If this parameter is set to a valid AVP or script var specifier,
719 rtpengine will take the input SDP from this pv instead of the message
722 There is no default value.
724 Example 1.11. Set read_sdp_pv parameter
726 modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
730 $var(sdp) = $rb + "a=foo:bar\r\n";
734 4.12. write_sdp_pv (string)
736 If this parameter is set to a valid AVP or script var specifier, the
737 SDP returned by rtpengine in the offer/answer operations is returned in
738 the specified variable instead of the message body.
740 There is no default value.
742 Example 1.12. Set write_sdp_pv parameter
744 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
749 set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
752 4.13. rtp_inst_pvar (string)
754 A pseudo variable to store the chosen RTP Engine IP address. If this
755 parameter is set, the IP address and port of the instance chosen will
756 be stored in the given variable.
758 By default, this parameter is not set.
760 Example 1.13. Set rtp_inst_pvar parameter
762 modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
765 4.14. hash_table_size (integer)
767 Size of the hash table. Default value is 256.
769 NOTE: If configured size is less than 1, the size will be defaulted to
772 Example 1.14. Set hash_table_size parameter
774 modparam("rtpengine", "hash_table_size", 123)
777 4.15. hash_table_tout (integer)
779 Number of seconds after an rtpengine hash table entry is marked for
780 deletion. By default, this parameter is set to 3600 (seconds).
782 To maintain information about a selected rtp machine node, for a given
783 call, entries are added in a hashtable of (callid, node) pairs. When
784 command comes, lookup callid. If found, return chosen node. If not
785 found, choose a new node, insert it in the hastable and return the
788 NOTE: In the current implementation, the actual deletion happens on the
789 fly, while insert/remove/lookup the hastable, only for the entries in
790 the insert/remove/lookup path.
792 NOTE: When configuring this parameter, one should consider maximum call
793 time VS share memory for unfinished calls.
795 Example 1.15. Set hash_table_tout parameter
797 modparam("rtpengine", "hash_table_tout", 300)
800 4.16. db_url (string)
802 The rtpengine datablase url. If present and valid, it activates
803 database mode. Node information is read from database, not from config.
805 By default, the datablase url is NULL (not set).
807 Example 1.16. Set db_url parameter
809 modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
812 4.17. table_name (string)
814 The rtpengine table name. If database mode is activated (i.e. valid
815 db_url), set the name of rtpengine table, on startup.
817 By default, the rtpengine table name is "rtpengine".
819 NOTE: One needs to add the version of the rtpengine table in the
820 version table. The current version is version 1.
822 Example 1.17. Set table_name parameter
824 modparam("rtpengine", "table_name", "rtpengine_table_name")
827 Example 1.18. Setup rtpengine table
828 mysql> describe rtpengine;
829 +----------+------------------+------+-----+---------------------+-------+
830 | Field | Type | Null | Key | Default | Extra |
831 +----------+------------------+------+-----+---------------------+-------+
832 | setid | int(10) unsigned | NO | PRI | 0 | |
833 | url | varchar(64) | NO | PRI | NULL | |
834 | weight | int(10) unsigned | NO | | 1 | |
835 | disabled | int(1) | NO | | 0 | |
836 | stamp | datetime | NO | | 1900-01-01 00:00:01 | |
837 +----------+------------------+------+-----+---------------------+-------+
839 mysql> select * from rtpengine;
840 +-------+----------------------------+--------+----------+---------------------+
841 | setid | url | weight | disabled | stamp |
842 +-------+----------------------------+--------+----------+---------------------+
843 | 0 | udp:rtpengine1.domain:8800 | 1 | 0 | 2016-03-10 10:30:54 |
844 | 0 | udp:rtpengine2.domain:8800 | 1 | 1 | 2016-03-10 10:30:54 |
845 +-------+----------------------------+--------+----------+---------------------+
847 mysql> select * from version;
848 +---------------------------+---------------+
849 | table_name | table_version |
850 +---------------------------+---------------+
852 +---------------------------+---------------+
854 4.18. setid_col (string)
856 Column name in the rtpengine table. If database mode is activated (i.e.
857 valid db_url), set the setid of rtp nodes according to this column, on
858 startup. The MySQL value for this column should be INT UNSIGNED.
860 By default, the column name is "setid".
862 Example 1.19. Set setid_col parameter
864 modparam("rtpengine", "setid_col", "setid_column_name")
867 4.19. url_col (string)
869 Column name in the rtpengine table. If database mode is activated (i.e.
870 valid db_url), set the url of rtp nodes according to this column, on
871 startup. The MySQL value for this column should be VARCHAR.
873 By default, the column name is "url".
875 Example 1.20. Set url_col parameter
877 modparam("rtpengine", "url_col", "url_column_name")
880 4.20. weight_col (string)
882 Column name in the rtpengine table. If database mode is activated (i.e.
883 valid db_url), set the weight of rtp nodes according to this column, on
884 startup. The column value has priority over the URL weight. The MySQL
885 value for this column should be INT UNSIGNED.
887 By default, the column name is "weight".
889 Example 1.21. Set weight_col parameter
891 modparam("rtpengine", "weight_col", "weight_column_name")
894 4.21. disabled_col (string)
896 Column name in the rtpengine table. If database mode is activated (i.e.
897 valid db_url), set the state of rtp nodes according to this column, on
898 startup. The MySQL value for this column should be INT.
900 By default, the column name is "disabled".
902 Example 1.22. Set disabled_col parameter
904 modparam("rtpengine", "disabled_col", "disabled_column_name")
907 4.22. setid_default (integer)
909 The default set of nodes to be used.
911 By default, the setid is 0.
913 NOTE that if setid_avp is configured, this value will be ignored and
914 the active set will be chosen according to the setid_avp.
916 Example 1.23. Set setid_default parameter
918 modparam("rtpengine", "setid_default", 11)
921 4.23. media_duration (string)
923 The name of a pseudovariable to be filled in with the length of the
924 media being played back after a call to “play_media”, expressed in
925 milliseconds. It's set to -1 if the length of the media could not be
928 By default, this parameter is not set.
930 Example 1.24. Set media_duration parameter
932 modparam("rtpengine", "media_duration", "$avp(MEDIA_DURATION)")
935 4.24. mos_min_pv (string)
937 The name of a pseudovariable to hold the minimum encountered MOS value
938 for the call. The value typically has a range of 1.0 through 5.0.
940 There is no default value.
942 This value is filled in after invoking“rtpengine_delete”,
943 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
944 deletion of the call (or call branch).
946 Example 1.25. Set mos_min_pv parameter
948 modparam("rtpengine", "mos_min_pv", "$avp(mos_min)")
951 4.25. mos_min_at_pv (string)
953 The name of a pseudovariable to hold the timestamp of when the minimum
954 MOS value was encountered during the call, such as “0:30” for 30
955 seconds after the start of the call.
957 There is no default value.
959 This value is filled in after invoking “rtpengine_delete”,
960 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
961 deletion of the call (or call branch).
963 Example 1.26. Set mos_min_at_pv parameter
965 modparam("rtpengine", "mos_min_at_pv", "$avp(mos_min_at)")
968 4.26. mos_min_packetloss_pv (string)
970 The name of a pseudovariable to hold the amount of packetloss in
971 percent at the time the minimum MOS value was encountered;
973 There is no default value.
975 This value is filled in after invoking “rtpengine_delete”,
976 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
977 deletion of the call (or call branch).
979 Example 1.27. Set mos_min_packetloss_pv parameter
981 modparam("rtpengine", "mos_min_packetloss_pv", "$avp(mos_min_packetloss)")
984 4.27. mos_min_jitter_pv (string)
986 The name of a pseudovariable to hold the amount of jitter in
987 milliseconds at the time the minimum MOS value was encountered;
989 There is no default value.
991 This value is filled in after invoking “rtpengine_delete”,
992 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
993 deletion of the call (or call branch).
995 Example 1.28. Set mos_min_jitter_pv parameter
997 modparam("rtpengine", "mos_min_jitter_pv", "$avp(mos_min_jitter)")
1000 4.28. mos_min_roundtrip_pv (string)
1002 The name of a pseudovariable to hold the packet round-trip time in
1003 milliseconds at the time the minimum MOS value was encountered;
1005 There is no default value.
1007 This value is filled in after invoking “rtpengine_delete”,
1008 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1009 deletion of the call (or call branch).
1011 Example 1.29. Set mos_min_roundtrip_pv parameter
1013 modparam("rtpengine", "mos_min_roundtrip_pv", "$avp(mos_min_roundtrip)")
1016 4.29. mos_max_pv (string)
1018 The name of a pseudovariable to hold the maximum encountered MOS value
1019 for the call. The value typically has a range of 1.0 through 5.0.
1021 There is no default value.
1023 This value is filled in after invoking“rtpengine_delete”,
1024 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1025 deletion of the call (or call branch).
1027 Example 1.30. Set mos_max_pv parameter
1029 modparam("rtpengine", "mos_max_pv", "$avp(mos_max)")
1032 4.30. mos_max_at_pv (string)
1034 The name of a pseudovariable to hold the timestamp of when the maximum
1035 MOS value was encountered during the call, such as “0:30” for 30
1036 seconds after the start of the call.
1038 There is no default value.
1040 This value is filled in after invoking “rtpengine_delete”,
1041 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1042 deletion of the call (or call branch).
1044 Example 1.31. Set mos_max_at_pv parameter
1046 modparam("rtpengine", "mos_max_at_pv", "$avp(mos_max_at)")
1049 4.31. mos_max_packetloss_pv (string)
1051 The name of a pseudovariable to hold the amount of packetloss in
1052 percent at the time the maximum MOS value was encountered;
1054 There is no default value.
1056 This value is filled in after invoking “rtpengine_delete”,
1057 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1058 deletion of the call (or call branch).
1060 Example 1.32. Set mos_max_packetloss_pv parameter
1062 modparam("rtpengine", "mos_max_packetloss_pv", "$avp(mos_max_packetloss)")
1065 4.32. mos_max_jitter_pv (string)
1067 The name of a pseudovariable to hold the amount of jitter in
1068 milliseconds at the time the maximum MOS value was encountered;
1070 There is no default value.
1072 This value is filled in after invoking “rtpengine_delete”,
1073 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1074 deletion of the call (or call branch).
1076 Example 1.33. Set mos_max_jitter_pv parameter
1078 modparam("rtpengine", "mos_max_jitter_pv", "$avp(mos_max_jitter)")
1081 4.33. mos_max_roundtrip_pv (string)
1083 The name of a pseudovariable to hold the packet round-trip time in
1084 milliseconds at the time the maximum MOS value was encountered;
1086 There is no default value.
1088 This value is filled in after invoking “rtpengine_delete”,
1089 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1090 deletion of the call (or call branch).
1092 Example 1.34. Set mos_max_roundtrip_pv parameter
1094 modparam("rtpengine", "mos_max_roundtrip_pv", "$avp(mos_max_roundtrip)")
1097 4.34. mos_average_pv (string)
1099 The name of a pseudovariable to hold the average (median) MOS value for
1100 the call. The value typically has a range of 1.0 through 5.0.
1102 There is no default value.
1104 This value is filled in after invoking“rtpengine_delete”,
1105 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1106 deletion of the call (or call branch).
1108 Example 1.35. Set mos_average_pv parameter
1110 modparam("rtpengine", "mos_average_pv", "$avp(mos_average)")
1113 4.35. mos_average_packetloss_pv (string)
1115 The name of a pseudovariable to hold the average (median) amount of
1116 packetloss in percent present throughout the call.
1118 There is no default value.
1120 This value is filled in after invoking “rtpengine_delete”,
1121 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1122 deletion of the call (or call branch).
1124 Example 1.36. Set mos_average_packetloss_pv parameter
1126 modparam("rtpengine", "mos_average_packetloss_pv", "$avp(mos_average_packetloss)
1130 4.36. mos_average_jitter_pv (string)
1132 The name of a pseudovariable to hold the average (median) amount of
1133 jitter in milliseconds present throughout the call.
1135 There is no default value.
1137 This value is filled in after invoking “rtpengine_delete”,
1138 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1139 deletion of the call (or call branch).
1141 Example 1.37. Set mos_average_jitter_pv parameter
1143 modparam("rtpengine", "mos_average_jitter_pv", "$avp(mos_average_jitter)")
1146 4.37. mos_average_roundtrip_pv (string)
1148 The name of a pseudovariable to hold the average (median) packet
1149 round-trip time in milliseconds present throughout the call.
1151 There is no default value.
1153 This value is filled in after invoking “rtpengine_delete”,
1154 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1155 deletion of the call (or call branch).
1157 Example 1.38. Set mos_average_roundtrip_pv parameter
1159 modparam("rtpengine", "mos_average_roundtrip_pv", "$avp(mos_average_roundtrip)")
1162 4.38. mos_average_samples_pv (string)
1164 The name of a pseudovariable to hold the number of samples used to
1165 determine the other “average” MOS data points.
1167 There is no default value.
1169 This value is filled in after invoking “rtpengine_delete”,
1170 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1171 deletion of the call (or call branch).
1173 Example 1.39. Set mos_average_samples_pv parameter
1175 modparam("rtpengine", "mos_average_samples_pv", "$avp(mos_average_samples)")
1178 4.39. mos_A_label_pv (string)
1180 The name of a pseudovariable to hold a custom label used in rtpengine
1181 signalling. If set, all the statistics pseudovariables with the “_A”
1182 suffix will be filled in with statistics only from the call legs that
1183 match the label given in this variable.
1185 There is no default value.
1187 Example 1.40. Set mos_A_label_pv parameter
1189 modparam("rtpengine", "mos_A_label_pv", "$avp(mos_A_label)")
1192 4.40. mos_min_A_pv (string)
1194 The name of a pseudovariable to hold the minimum encountered MOS value
1195 for the call. The value typically has a range of 1.0 through 5.0.
1197 There is no default value.
1199 This value is filled in after invoking“rtpengine_delete”,
1200 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1201 deletion of the call (or call branch).
1203 Only call legs matching the rtpengine label given in the
1204 “mos_A_label_pv” will be used in calculating this statistics value.
1206 Example 1.41. Set mos_min_A_pv parameter
1208 modparam("rtpengine", "mos_min_A_pv", "$avp(mos_min_A)")
1211 4.41. mos_min_at_A_pv (string)
1213 The name of a pseudovariable to hold the timestamp of when the minimum
1214 MOS value was encountered during the call, such as “0:30” for 30
1215 seconds after the start of the call.
1217 There is no default value.
1219 This value is filled in after invoking “rtpengine_delete”,
1220 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1221 deletion of the call (or call branch).
1223 Only call legs matching the rtpengine label given in the
1224 “mos_A_label_pv” will be used in calculating this statistics value.
1226 Example 1.42. Set mos_min_at_A_pv parameter
1228 modparam("rtpengine", "mos_min_at_A_pv", "$avp(mos_min_at_A)")
1231 4.42. mos_min_packetloss_A_pv (string)
1233 The name of a pseudovariable to hold the amount of packetloss in
1234 percent at the time the minimum MOS value was encountered;
1236 There is no default value.
1238 This value is filled in after invoking “rtpengine_delete”,
1239 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1240 deletion of the call (or call branch).
1242 Only call legs matching the rtpengine label given in the
1243 “mos_A_label_pv” will be used in calculating this statistics value.
1245 Example 1.43. Set mos_min_packetloss_A_pv parameter
1247 modparam("rtpengine", "mos_min_packetloss_A_pv", "$avp(mos_min_packetloss_A)")
1250 4.43. mos_min_jitter_A_pv (string)
1252 The name of a pseudovariable to hold the amount of jitter in
1253 milliseconds at the time the minimum MOS value was encountered;
1255 There is no default value.
1257 This value is filled in after invoking “rtpengine_delete”,
1258 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1259 deletion of the call (or call branch).
1261 Only call legs matching the rtpengine label given in the
1262 “mos_A_label_pv” will be used in calculating this statistics value.
1264 Example 1.44. Set mos_min_jitter_A_pv parameter
1266 modparam("rtpengine", "mos_min_jitter_A_pv", "$avp(mos_min_jitter_A)")
1269 4.44. mos_min_roundtrip_A_pv (string)
1271 The name of a pseudovariable to hold the packet round-trip time in
1272 milliseconds at the time the minimum MOS value was encountered;
1274 There is no default value.
1276 This value is filled in after invoking “rtpengine_delete”,
1277 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1278 deletion of the call (or call branch).
1280 Only call legs matching the rtpengine label given in the
1281 “mos_A_label_pv” will be used in calculating this statistics value.
1283 Example 1.45. Set mos_min_roundtrip_A_pv parameter
1285 modparam("rtpengine", "mos_min_roundtrip_A_pv", "$avp(mos_min_roundtrip_A)")
1288 4.45. mos_max_A_pv (string)
1290 The name of a pseudovariable to hold the maximum encountered MOS value
1291 for the call. The value typically has a range of 1.0 through 5.0.
1293 There is no default value.
1295 This value is filled in after invoking“rtpengine_delete”,
1296 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1297 deletion of the call (or call branch).
1299 Only call legs matching the rtpengine label given in the
1300 “mos_A_label_pv” will be used in calculating this statistics value.
1302 Example 1.46. Set mos_max_A_pv parameter
1304 modparam("rtpengine", "mos_max_A_pv", "$avp(mos_max_A)")
1307 4.46. mos_max_at_A_pv (string)
1309 The name of a pseudovariable to hold the timestamp of when the maximum
1310 MOS value was encountered during the call, such as “0:30” for 30
1311 seconds after the start of the call.
1313 There is no default value.
1315 This value is filled in after invoking “rtpengine_delete”,
1316 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1317 deletion of the call (or call branch).
1319 Only call legs matching the rtpengine label given in the
1320 “mos_A_label_pv” will be used in calculating this statistics value.
1322 Example 1.47. Set mos_max_at_A_pv parameter
1324 modparam("rtpengine", "mos_max_at_A_pv", "$avp(mos_max_at_A)")
1327 4.47. mos_max_packetloss_A_pv (string)
1329 The name of a pseudovariable to hold the amount of packetloss in
1330 percent at the time the maximum MOS value was encountered;
1332 There is no default value.
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).
1338 Only call legs matching the rtpengine label given in the
1339 “mos_A_label_pv” will be used in calculating this statistics value.
1341 Example 1.48. Set mos_max_packetloss_A_pv parameter
1343 modparam("rtpengine", "mos_max_packetloss_A_pv", "$avp(mos_max_packetloss_A)")
1346 4.48. mos_max_jitter_A_pv (string)
1348 The name of a pseudovariable to hold the amount of jitter in
1349 milliseconds at the time the maximum MOS value was encountered;
1351 There is no default value.
1353 This value is filled in after invoking “rtpengine_delete”,
1354 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1355 deletion of the call (or call branch).
1357 Only call legs matching the rtpengine label given in the
1358 “mos_A_label_pv” will be used in calculating this statistics value.
1360 Example 1.49. Set mos_max_jitter_A_pv parameter
1362 modparam("rtpengine", "mos_max_jitter_A_pv", "$avp(mos_max_jitter_A)")
1365 4.49. mos_max_roundtrip_A_pv (string)
1367 The name of a pseudovariable to hold the packet round-trip time in
1368 milliseconds at the time the maximum MOS value was encountered;
1370 There is no default value.
1372 This value is filled in after invoking “rtpengine_delete”,
1373 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1374 deletion of the call (or call branch).
1376 Only call legs matching the rtpengine label given in the
1377 “mos_A_label_pv” will be used in calculating this statistics value.
1379 Example 1.50. Set mos_max_roundtrip_A_pv parameter
1381 modparam("rtpengine", "mos_max_roundtrip_A_pv", "$avp(mos_max_roundtrip_A)")
1384 4.50. mos_average_A_pv (string)
1386 The name of a pseudovariable to hold the average (median) MOS value for
1387 the call. The value typically has a range of 1.0 through 5.0.
1389 There is no default value.
1391 This value is filled in after invoking“rtpengine_delete”,
1392 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1393 deletion of the call (or call branch).
1395 Only call legs matching the rtpengine label given in the
1396 “mos_A_label_pv” will be used in calculating this statistics value.
1398 Example 1.51. Set mos_average_A_pv parameter
1400 modparam("rtpengine", "mos_average_A_pv", "$avp(mos_average_A)")
1403 4.51. mos_average_packetloss_A_pv (string)
1405 The name of a pseudovariable to hold the average (median) amount of
1406 packetloss in percent present throughout the call.
1408 There is no default value.
1410 This value is filled in after invoking “rtpengine_delete”,
1411 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1412 deletion of the call (or call branch).
1414 Only call legs matching the rtpengine label given in the
1415 “mos_A_label_pv” will be used in calculating this statistics value.
1417 Example 1.52. Set mos_average_packetloss_A_pv parameter
1419 modparam("rtpengine", "mos_average_packetloss_A_pv", "$avp(mos_average_packetlos
1423 4.52. mos_average_jitter_A_pv (string)
1425 The name of a pseudovariable to hold the average (median) amount of
1426 jitter in milliseconds present throughout the call.
1428 There is no default value.
1430 This value is filled in after invoking “rtpengine_delete”,
1431 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1432 deletion of the call (or call branch).
1434 Only call legs matching the rtpengine label given in the
1435 “mos_A_label_pv” will be used in calculating this statistics value.
1437 Example 1.53. Set mos_average_jitter_A_pv parameter
1439 modparam("rtpengine", "mos_average_jitter_A_pv", "$avp(mos_average_jitter_A)")
1442 4.53. mos_average_roundtrip_A_pv (string)
1444 The name of a pseudovariable to hold the average (median) packet
1445 round-trip time in milliseconds present throughout the call.
1447 There is no default value.
1449 This value is filled in after invoking “rtpengine_delete”,
1450 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1451 deletion of the call (or call branch).
1453 Only call legs matching the rtpengine label given in the
1454 “mos_A_label_pv” will be used in calculating this statistics value.
1456 Example 1.54. Set mos_average_roundtrip_A_pv parameter
1458 modparam("rtpengine", "mos_average_roundtrip_A_pv", "$avp(mos_average_roundtrip_
1462 4.54. mos_average_samples_A_pv (string)
1464 The name of a pseudovariable to hold the number of samples used to
1465 determine the other “average” MOS data points.
1467 There is no default value.
1469 This value is filled in after invoking “rtpengine_delete”,
1470 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1471 deletion of the call (or call branch).
1473 Only call legs matching the rtpengine label given in the
1474 “mos_A_label_pv” will be used in calculating this statistics value.
1476 Example 1.55. Set mos_average_samples_A_pv parameter
1478 modparam("rtpengine", "mos_average_samples_A_pv", "$avp(mos_average_samples_A)")
1481 4.55. mos_B_label_pv (string)
1483 The name of a pseudovariable to hold a custom label used in rtpengine
1484 signalling. If set, all the statistics pseudovariables with the “_B”
1485 suffix will be filled in with statistics only from the call legs that
1486 match the label given in this variable.
1488 There is no default value.
1490 Example 1.56. Set mos_B_label_pv parameter
1492 modparam("rtpengine", "mos_B_label_pv", "$avp(mos_B_label)")
1495 4.56. mos_min_B_pv (string)
1497 The name of a pseudovariable to hold the minimum encountered MOS value
1498 for the call. The value typically has a range of 1.0 through 5.0.
1500 There is no default value.
1502 This value is filled in after invoking“rtpengine_delete”,
1503 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1504 deletion of the call (or call branch).
1506 Only call legs matching the rtpengine label given in the
1507 “mos_B_label_pv” will be used in calculating this statistics value.
1509 Example 1.57. Set mos_min_B_pv parameter
1511 modparam("rtpengine", "mos_min_B_pv", "$avp(mos_min_B)")
1514 4.57. mos_min_at_B_pv (string)
1516 The name of a pseudovariable to hold the timestamp of when the minimum
1517 MOS value was encountered during the call, such as “0:30” for 30
1518 seconds after the start of the call.
1520 There is no default value.
1522 This value is filled in after invoking “rtpengine_delete”,
1523 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1524 deletion of the call (or call branch).
1526 Only call legs matching the rtpengine label given in the
1527 “mos_B_label_pv” will be used in calculating this statistics value.
1529 Example 1.58. Set mos_min_at_B_pv parameter
1531 modparam("rtpengine", "mos_min_at_B_pv", "$avp(mos_min_at_B)")
1534 4.58. mos_min_packetloss_B_pv (string)
1536 The name of a pseudovariable to hold the amount of packetloss in
1537 percent at the time the minimum MOS value was encountered;
1539 There is no default value.
1541 This value is filled in after invoking “rtpengine_delete”,
1542 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1543 deletion of the call (or call branch).
1545 Only call legs matching the rtpengine label given in the
1546 “mos_B_label_pv” will be used in calculating this statistics value.
1548 Example 1.59. Set mos_min_packetloss_B_pv parameter
1550 modparam("rtpengine", "mos_min_packetloss_B_pv", "$avp(mos_min_packetloss_B)")
1553 4.59. mos_min_jitter_B_pv (string)
1555 The name of a pseudovariable to hold the amount of jitter in
1556 milliseconds at the time the minimum MOS value was encountered;
1558 There is no default value.
1560 This value is filled in after invoking “rtpengine_delete”,
1561 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1562 deletion of the call (or call branch).
1564 Only call legs matching the rtpengine label given in the
1565 “mos_B_label_pv” will be used in calculating this statistics value.
1567 Example 1.60. Set mos_min_jitter_B_pv parameter
1569 modparam("rtpengine", "mos_min_jitter_B_pv", "$avp(mos_min_jitter_B)")
1572 4.60. mos_min_roundtrip_B_pv (string)
1574 The name of a pseudovariable to hold the packet round-trip time in
1575 milliseconds at the time the minimum MOS value was encountered;
1577 There is no default value.
1579 This value is filled in after invoking “rtpengine_delete”,
1580 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1581 deletion of the call (or call branch).
1583 Only call legs matching the rtpengine label given in the
1584 “mos_B_label_pv” will be used in calculating this statistics value.
1586 Example 1.61. Set mos_min_roundtrip_B_pv parameter
1588 modparam("rtpengine", "mos_min_roundtrip_B_pv", "$avp(mos_min_roundtrip_B)")
1591 4.61. mos_max_B_pv (string)
1593 The name of a pseudovariable to hold the maximum encountered MOS value
1594 for the call. The value typically has a range of 1.0 through 5.0.
1596 There is no default value.
1598 This value is filled in after invoking“rtpengine_delete”,
1599 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1600 deletion of the call (or call branch).
1602 Only call legs matching the rtpengine label given in the
1603 “mos_B_label_pv” will be used in calculating this statistics value.
1605 Example 1.62. Set mos_max_B_pv parameter
1607 modparam("rtpengine", "mos_max_B_pv", "$avp(mos_max_B)")
1610 4.62. mos_max_at_B_pv (string)
1612 The name of a pseudovariable to hold the timestamp of when the maximum
1613 MOS value was encountered during the call, such as “0:30” for 30
1614 seconds after the start of the call.
1616 There is no default value.
1618 This value is filled in after invoking “rtpengine_delete”,
1619 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1620 deletion of the call (or call branch).
1622 Only call legs matching the rtpengine label given in the
1623 “mos_B_label_pv” will be used in calculating this statistics value.
1625 Example 1.63. Set mos_max_at_B_pv parameter
1627 modparam("rtpengine", "mos_max_at_B_pv", "$avp(mos_max_at_B)")
1630 4.63. mos_max_packetloss_B_pv (string)
1632 The name of a pseudovariable to hold the amount of packetloss in
1633 percent at the time the maximum MOS value was encountered;
1635 There is no default value.
1637 This value is filled in after invoking “rtpengine_delete”,
1638 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1639 deletion of the call (or call branch).
1641 Only call legs matching the rtpengine label given in the
1642 “mos_B_label_pv” will be used in calculating this statistics value.
1644 Example 1.64. Set mos_max_packetloss_B_pv parameter
1646 modparam("rtpengine", "mos_max_packetloss_B_pv", "$avp(mos_max_packetloss_B)")
1649 4.64. mos_max_jitter_B_pv (string)
1651 The name of a pseudovariable to hold the amount of jitter in
1652 milliseconds at the time the maximum MOS value was encountered;
1654 There is no default value.
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).
1660 Only call legs matching the rtpengine label given in the
1661 “mos_B_label_pv” will be used in calculating this statistics value.
1663 Example 1.65. Set mos_max_jitter_B_pv parameter
1665 modparam("rtpengine", "mos_max_jitter_B_pv", "$avp(mos_max_jitter_B)")
1668 4.65. mos_max_roundtrip_B_pv (string)
1670 The name of a pseudovariable to hold the packet round-trip time in
1671 milliseconds at the time the maximum MOS value was encountered;
1673 There is no default value.
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).
1679 Only call legs matching the rtpengine label given in the
1680 “mos_B_label_pv” will be used in calculating this statistics value.
1682 Example 1.66. Set mos_max_roundtrip_B_pv parameter
1684 modparam("rtpengine", "mos_max_roundtrip_B_pv", "$avp(mos_max_roundtrip_B)")
1687 4.66. mos_average_B_pv (string)
1689 The name of a pseudovariable to hold the average (median) MOS value for
1690 the call. The value typically has a range of 1.0 through 5.0.
1692 There is no default value.
1694 This value is filled in after invoking“rtpengine_delete”,
1695 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1696 deletion of the call (or call branch).
1698 Only call legs matching the rtpengine label given in the
1699 “mos_B_label_pv” will be used in calculating this statistics value.
1701 Example 1.67. Set mos_average_B_pv parameter
1703 modparam("rtpengine", "mos_average_B_pv", "$avp(mos_average_B)")
1706 4.67. mos_average_packetloss_B_pv (string)
1708 The name of a pseudovariable to hold the average (median) amount of
1709 packetloss in percent present throughout the call.
1711 There is no default value.
1713 This value is filled in after invoking “rtpengine_delete”,
1714 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1715 deletion of the call (or call branch).
1717 Only call legs matching the rtpengine label given in the
1718 “mos_B_label_pv” will be used in calculating this statistics value.
1720 Example 1.68. Set mos_average_packetloss_B_pv parameter
1722 modparam("rtpengine", "mos_average_packetloss_B_pv", "$avp(mos_average_packetlos
1726 4.68. mos_average_jitter_B_pv (string)
1728 The name of a pseudovariable to hold the average (median) amount of
1729 jitter in milliseconds present throughout the call.
1731 There is no default value.
1733 This value is filled in after invoking “rtpengine_delete”,
1734 “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
1735 deletion of the call (or call branch).
1737 Only call legs matching the rtpengine label given in the
1738 “mos_B_label_pv” will be used in calculating this statistics value.
1740 Example 1.69. Set mos_average_jitter_B_pv parameter
1742 modparam("rtpengine", "mos_average_jitter_B_pv", "$avp(mos_average_jitter_B)")
1745 4.69. mos_average_roundtrip_B_pv (string)
1747 The name of a pseudovariable to hold the average (median) packet
1748 round-trip time in milliseconds present throughout the call.
1750 There is no default value.
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).
1756 Only call legs matching the rtpengine label given in the
1757 “mos_B_label_pv” will be used in calculating this statistics value.
1759 Example 1.70. Set mos_average_roundtrip_B_pv parameter
1761 modparam("rtpengine", "mos_average_roundtrip_B_pv", "$avp(mos_average_roundtrip_
1765 4.70. mos_average_samples_B_pv (string)
1767 The name of a pseudovariable to hold the number of samples used to
1768 determine the other “average” MOS data points.
1770 There is no default value.
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).
1776 Only call legs matching the rtpengine label given in the
1777 “mos_B_label_pv” will be used in calculating this statistics value.
1779 Example 1.71. Set mos_average_samples_B_pv parameter
1781 modparam("rtpengine", "mos_average_samples_B_pv", "$avp(mos_average_samples_B)")
1784 4.71. control_cmd_tos (integer)
1786 The parameter is used to set the value of “type of service (tos)” for
1787 the control commands (such as rtpengine_offer(), rtpengine_answer()
1790 There is no default value. By default this feature is not used.
1792 The values not falling into the range “0-255” will be simply ignored.
1794 Example 1.72. Set control_cmd_tos parameter
1796 modparam("rtpengine", "control_cmd_tos", 144)
1799 4.72. hash_algo (integer)
1801 Hashing algorithm to be used in node selection algorithm. Now there are
1802 2 possibilities: legacy alogrithm - 0(very basic hash over callid) or
1803 SHA1 - 1(apply sha1 over the callid and calculate hash).
1805 Default value is 0, legacy algorithm.
1807 The values not falling into the range “0-1” .
1809 Example 1.73. Set control_cmd_tos parameter
1811 ### use SHA1 instead of legacy algorithm
1812 modparam("rtpengine", "hash_algo", 1)
1817 5.1. set_rtpengine_set(setid[, setid])
1818 5.2. rtpengine_offer([flags])
1819 5.3. rtpengine_answer([flags])
1820 5.4. rtpengine_info([flags])
1821 5.5. rtpengine_delete([flags])
1822 5.6. rtpengine_query([flags])
1823 5.7. rtpengine_manage([flags])
1824 5.8. start_recording([flags])
1825 5.9. stop_recording([flags])
1826 5.10. block_dtmf([flags])
1827 5.11. unblock_dtmf([flags])
1828 5.12. block_media([flags])
1829 5.13. unblock_media([flags])
1830 5.14. start_forwarding([flags])
1831 5.15. stop_forwarding([flags])
1832 5.16. play_media([flags])
1833 5.17. stop_media([flags])
1834 5.18. play_dtmf([flags])
1836 5.1. set_rtpengine_set(setid[, setid])
1838 Sets the ID of the RTP proxy set to be used for the next
1839 rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
1840 rtpengine_manage() command. The parameter can be an integer or a config
1841 variable holding an integer.
1843 A second set ID can be specified to daisy-chain two RTP proxies. The
1844 two set IDs must be distinct from each other and there must not be any
1845 overlap in the proxies present in both sets. In this use case, the
1846 request (offer, answer, etc) is first sent to an RTP proxy from the
1847 first set, which rewrites the SDP body and sends it back to the module.
1848 The rewritten SDP body is then used to make another request to an RTP
1849 proxy from the second set, which rewrites the SDP body another time and
1850 sends it back to the module to be placed back into the SIP message.
1851 This is useful if you have a set of RTP proxies that the caller must
1852 use, and another distinct set of RTP proxies that the callee must use.
1853 This is supported by all rtpengine commands except rtpengine_manage().
1855 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
1858 Example 1.74. set_rtpengine_set usage
1860 set_rtpengine_set("2");
1864 5.2. rtpengine_offer([flags])
1866 Rewrites SDP body to ensure that media is passed through an RTP proxy.
1867 To be invoked on INVITE for the cases the SDP bodies are in INVITE and
1868 200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
1870 The function will return true on success and false (-1) on various
1871 failures, like using rtp_engine_offer() on a SIP MESSAGE request or
1872 communication with rtpengine fails.
1874 Meaning of the parameters is as follows:
1875 * flags - flags to turn on some features.
1876 The “flags” string is a list of space-separated items. Each item is
1877 either an individual token, or a token in “key=value” format. The
1878 possible tokens are described below.
1879 + via-branch=... - Include the “branch” value of one of the
1880 “Via” headers in the request to the RTP proxy. Possible values
1881 are: “1” - use the first “Via” header; “2” - use the second
1882 “Via” header; “auto” - use the first “Via” header if this is a
1883 request, or the second one if this is a reply; “extra” - don't
1884 take the value from a header, but instead use the value of the
1885 “extra_id_pv” variable; “next” - use the branch ID generated
1886 by Kamailio for the next outgoing branch; “auto-next” - use
1887 “next” in requests and “1” in replies; “auto-extra” - use
1888 “extra” in requests and “1” in replies. This can be used to
1889 create one media session per branch on the RTP proxy. When
1890 sending a subsequent “delete” command to the RTP proxy, you
1891 can then stop just the session for a specific branch when
1892 passing the flag '1' or '2' in the “rtpengine_delete”, or stop
1893 all sessions for a call when not passing one of those two
1894 flags there. This is especially useful if you have serially
1895 forked call scenarios where the RTP proxy gets an “offer”
1896 command for a new branch, and then a “delete” command for the
1897 previous branch, which would otherwise delete the full call,
1898 breaking the subsequent “answer” for the new branch. This flag
1899 is only supported by the Sipwise rtpengine RTP proxy at the
1901 + asymmetric - flags that UA from which message is received
1902 doesn't support symmetric RTP. Disables learning of endpoint
1903 addresses in the Sipwise rtpengine proxy.
1904 + no-redis-update - this flag can be used by Kamailio in order
1905 to tell rtpengine not to persist the call into Redis upon
1906 receiving offer/answer() control commands. If flag is not set,
1907 default action is rtpengine persists call to redis.
1908 + force-answer - force “answer”, that is, only rewrite SDP when
1909 corresponding session already exists in the RTP proxy. By
1910 default is on when the session is to be completed.
1911 + direction=... - this option specifies a logical network
1912 interface and should be given exactly twice. It enables RTP
1913 bridging between different addresses or networks of the same
1914 family (e.g. IPv4 to IPv4). The first instance of the option
1915 specifies the interface that the originator of this message
1916 should be using, while the second instance specifies the
1917 interface that the target should be using. For example, if the
1918 SIP message was sent by an endpoint on a private network and
1919 will be sent to an endpoint on the public internet, you would
1920 use “direction=priv direction=pub” if those two logical
1921 network interfaces were called “priv” and “pub” in your RTP
1922 proxy's configuration respectively. The direction must only be
1923 specified in for initial SDP offer; answers or subsequent
1924 offers can omit this option.
1925 + internal, external - shorthand for “direction=internal” and
1926 “direction=external” respectively. Useful for brevity or as
1927 legacy option if the RTP proxy only supports two network
1928 interfaces instead of multiple, arbitrarily named ones.
1929 + address-family=... - instructs the RTP proxy that the
1930 recipient of this SDP body expects to see addresses of a
1931 particular family. Possible values are “IP4” and “IP6”. For
1932 example, if the SDP body contains IPv4 addresses but the
1933 recipient only speaks IPv6, you would use “address-family=IP6”
1934 to bridge between the two address families.
1935 Sipwise rtpengine remembers the address family preference of
1936 each party after it has seen an SDP body from them. This means
1937 that normally it is only necessary to explicitly specify the
1938 address family in the “offer”, but not in the “answer”.
1939 Note: Please note, that this will only work properly with
1940 non-dual-stack user-agents or with dual-stack clients
1941 according to RFC6157 (which suggest ICE for Dual-Stack
1942 implementations). This short-cut will not work properly with
1943 RFC4091 (ANAT) compatible clients, which suggests having
1944 different m-lines with different IP-protocols grouped
1946 + force - instructs the RTP proxy to ignore marks inserted by
1947 another RTP proxy in transit to indicate that the session is
1948 already goes through another proxy. Allows creating a chain of
1949 proxies. Not supported and ignored by Sipwise rtpengine.
1950 + trust-address - flags that IP address in SDP should be
1951 trusted. Starting with rtpengine 3.8, this is the default
1952 behaviour. In older versions, without this flag the RTP proxy
1953 ignores the address in the SDP and uses source address of the
1954 SIP message as media address which is passed to the RTP proxy.
1955 + SIP-source-address - the opposite of trust-address. Restores
1956 the old default behaviour of ignoring endpoint addresses in
1958 + replace-origin - flags that IP from the origin description
1959 (o=) should be also changed.
1960 + replace-session-connection - flags to change the session-level
1961 SDP connection (c=) IP if media description also includes
1962 connection information.
1963 + symmetric - flags that for the UA from which message is
1964 received, support symmetric RTP must be forced. Does nothing
1965 with the Sipwise rtpengine proxy as it is the default.
1966 + repacketize=NN - requests the RTP proxy to perform
1967 re-packetization of RTP traffic coming from the UA which has
1968 sent the current message to increase or decrease payload size
1969 per each RTP packet forwarded if possible. The NN is the
1970 target payload size in ms, for the most codecs its value
1971 should be in 10ms increments, however for some codecs the
1972 increment could differ (e.g. 30ms for GSM or 20ms for G.723).
1973 The RTP proxy would select the closest value supported by the
1974 codec. This feature could be used for significantly reducing
1975 bandwith overhead for low bitrate codecs, for example with
1976 G.729 going from 10ms to 100ms saves two thirds of the network
1977 bandwith. Not supported by Sipwise rtpengine.
1978 + ICE=... - controls the RTP proxy's behaviour regarding ICE
1979 attributes within the SDP body. Possible values are: “force” -
1980 discard any ICE attributes already present in the SDP body and
1981 then generate and insert new ICE data, leaving itself as the
1982 only ICE candidates; “force-relay” - discard any “relay” type
1983 ICE attributes already present in the SDP body and then
1984 generate and insert itself as the only ICE “relay” candidates;
1985 “remove” instructs the RTP proxy to discard any ICE attributes
1986 and not insert any new ones into the SDP. The default (if no
1987 “ICE=...” is given at all), new ICE data will only be
1988 generated if no ICE was present in the SDP originally;
1989 otherwise the RTP proxy will only insert itself as additional
1990 ICE candidate. Other SDP substitutions (c=, m=, etc) are
1991 unaffected by this flag.
1992 + RTP, SRTP, DTLS, AVP, AVPF - These flags control the RTP
1993 transport protocol that should be used towards the recipient
1994 of the SDP. If none of them are specified, the protocol given
1995 in the SDP is left untouched. Otherwise, the “SRTP” flag
1996 indicates that SRTP should be used, while “RTP” indicates that
1997 SRTP should not be used. “AVPF” indicates that the advanced
1998 RTCP profile with feedback messages should be used, and “AVP”
1999 indicates that the regular RTCP profile should be used. See
2000 also the next set of flags below.
2001 + RTP/AVP, RTP/SAVP, UDP/TLS/RTP/SAVP, RTP/AVPF, RTP/SAVPF,
2002 UDP/TLS/RTP/SAVPF - these serve as an alternative, more
2003 explicit way to select between the different RTP protocols and
2004 profiles supported by the RTP proxy. For example, giving the
2005 flag “RTP/SAVPF” has the same effect as giving the two flags
2007 + to-tag - force inclusion of the “To” tag. Normally, the “To”
2008 tag is always included when present, except for “delete”
2009 messages. Including the “To” tag in a “delete” messages allows
2010 you to be more selective about which dialogues within a call
2011 are being torn down.
2012 + to-tag=... - use the specified string as “To” tag instead of
2013 the actual “To” tag from the SIP message, and force inclusion
2014 of the tag in the message as per above.
2015 + from-tag=... - use the specified string as “From” tag instead
2016 of the actual “From” tag from the SIP message.
2017 + call-id=... - use the specified string as “Call-ID” instead of
2018 the actual “Call-ID” from the SIP message.
2019 + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
2020 RTP proxy accept the offer, but not offer it to the recipient
2022 + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
2023 reject the offer, but still offer it to the recipient. Can be
2024 combined with “rtcp-mux-offer” to always offer it.
2025 + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
2026 recipient of this message, regardless of whether it was
2027 offered originally or not.
2028 + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
2029 accept the offer and also offer it to the recipient of this
2030 message. Can be combined with “rtcp-mux-offer” to always offer
2032 + media-address=... - force a particular media address to be
2033 used in the SDP body. Address family is detected
2035 + TOS=... - change the IP TOS value for all outgoing RTP packets
2036 within the entire call in both directions. Only honoured in an
2037 “offer”, ignored for an “answer”. Valid values are 0 through
2038 255, given in decimal. If this option is not specified, the
2039 TOS value will revert to the default TOS (normally 184). A
2040 value of -1 may be used to leave the currently used TOS
2042 + delete-delay=... - override the default delay (in seconds)
2043 before a call is actually deleted from memory. Can be set to
2044 zero to effectuate immediate deletion. This option only makes
2045 sense for delete operations.
2046 + strict-source - instructs the RTP proxy to check the source
2047 addresses of all incoming RTP packets and drop the packets if
2048 the address doesn't match.
2049 + media-handover - the antithesis of strict-source. Instructs
2050 the RTP proxy not only to accept mismatching RTP source
2051 addresses (as it normally would), but also to accept them as
2052 the new endpoint address of the opposite media flow. Not
2053 recommended as it allows media streams to be hijacked by an
2055 + DTLS=... - influence the behaviour of DTLS-SRTP. Possible
2056 values are “no” or “off” to suppress offering or accepting
2057 DTLS-SRTP, and “passive” to prefer participating in DTLS-SRTP
2059 + SDES-off - don't offer SDES when it normally would. In an SRTP
2060 context, this leaves DTLS-SRTP as the only other option.
2061 + SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
2062 SDES-unauthenticated_srtp - these directly reflect the SDES
2063 session parameters from RFC 4568 and will make the RTP proxy
2064 offer these parameters when offering SDES.
2065 + SDES-encrypted_srtp, SDES-encrypted_srtcp,
2066 SDES-authenticated_srtp - the opposites of the flags above.
2067 Useful if accepting these parameters is not desired and they
2068 should be rejected instead.
2069 + unidirectional - allows kernelization of one-way streams in
2070 the Sipwise rtpengine proxy. This is especially useful when
2071 the first call leg is handled by some rtpengine machine while
2072 the second call leg is handled by other rtpengine machine.
2073 + record-call=on - instructs RTPEngine to record the session.
2074 Use it in rtpengine_offer() to start recording immediately and
2075 save the call metadata, as alternative to start_recording().
2076 + metadata - a generic metadata string. The metadata will be
2077 used when recording calls to provide custom additional
2078 information. More details about this are found in the
2080 + codec-transcode=... - allows codecs to be added to the list of
2081 offered codecs even if they were not present in the original
2082 list of codecs. In this case, the transcoding engine will be
2083 engaged. Only codecs that are supported for both decoding and
2084 encoding can be added in this manner. More details about this
2085 are found in the rtpengine README.
2086 + codec-strip=... - strips given codec from sdp
2087 + codec-offer=... - offer given codec from sdp.More details
2088 about this are found in the rtpengine README.
2089 + codec-mask=... - Similar to strip except that codecs listed
2090 here will still be accepted and used for transcoding on the
2091 offering side.Useful only in combination with codec-transcode.
2092 all keyword can be used to mask all offered codecs
2093 + T.38=decode - If the offered SDP contains a media section
2094 advertising T.38 over UDPTL, translate it to a regular audio
2095 media section over RTP. By default, PCMU and PCMA will be used
2096 as audio codecs, but that can be overriden using the codec
2097 options described above. Other transport protocols (e.g. SRTP)
2098 can also be selected in the same way. If the offered SDP does
2099 not contain a T.38 section, then this flag has no effect.
2100 + T.38=force - Any audio media section (over RTP) in the offered
2101 SDP will be translated into a T.38 section over UDPTL.
2102 + T.38=stop - Stops a previously established T.38 to audio
2103 gateway and reverts the session back to media passthrough.
2104 This is useful when handling a rejected T.38 offer.
2105 Check also the documentation of RTPEngine, these flags are
2106 documented there as well: https://github.com/sipwise/rtpengine.
2108 This function can be used from ANY_ROUTE.
2110 Example 1.75. rtpengine_offer usage
2113 if (is_method("INVITE")) {
2114 if (has_body("application/sdp")) {
2115 if (rtpengine_offer())
2121 if (is_method("ACK") && has_body("application/sdp"))
2129 if (has_body("application/sdp"))
2137 if (has_body("application/sdp"))
2142 if (has_body("application/sdp")) {
2143 if (rtpengine_offer("codec-mask=all codec-transcode=PCMU codec-t
2150 5.3. rtpengine_answer([flags])
2152 Rewrites SDP body to ensure that media is passed through an RTP proxy.
2153 To be invoked on 200 OK for the cases the SDP bodies are in INVITE and
2154 200 OK and on ACK when SDP bodies are in 200 OK and ACK.
2156 See rtpengine_offer() function description above for the meaning of the
2159 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
2160 FAILURE_ROUTE, BRANCH_ROUTE.
2162 Example 1.76. rtpengine_answer usage
2164 See rtpengine_offer() function example above for example.
2166 5.4. rtpengine_info([flags])
2168 Send an updated offer to rtpengine. This is meant to be used when
2169 processing Tricke ICE SDP Fragments that are carried in SIP INFO
2170 messages and are proxied to endpoints that do not support ICE. With a
2171 matching content type, the SDP fragment is used to update rtpengine's
2172 list of ICE candidates. No new SDP is returned and so the SIP INFO
2173 message should be consumed after calling this function.
2175 While this function supports the same flags as “rtpengine_offer” et al,
2176 it is not normally necessary to provide any.
2178 This function can be used from ANY_ROUTE.
2180 Example 1.77. rtpengine_info usage
2185 5.5. rtpengine_delete([flags])
2187 Tears down the RTPProxy session for the current call. This populates
2188 the statistics pseudovariables (such “mos_min_pv” etc).
2190 See rtpengine_offer() function description above for the meaning of the
2191 parameters. Note that not all flags make sense for a “delete”.
2193 This function can be used from ANY_ROUTE.
2195 Example 1.78. rtpengine_delete usage
2200 5.6. rtpengine_query([flags])
2202 Queries the RTP proxy about the current status and statistics of a
2203 running call. This populates the statistics pseudovariables (such
2206 See rtpengine_offer() function description above for the meaning of the
2207 parameters. Note that not all flags make sense for a “query”.
2209 This function can be used from ANY_ROUTE.
2211 Example 1.79. rtpengine_query usage
2216 5.7. rtpengine_manage([flags])
2218 Manage the RTPEngine session - it combines the functionality of
2219 rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
2220 internally based on message type and method which one to execute.
2222 It can take the same parameters as rtpengine_offer(). The flags
2223 parameter to rtpengine_manage() can be a configuration variable
2224 containing the flags as a string.
2227 * If INVITE with SDP, then do rtpengine_offer()
2228 * If INVITE with SDP, when the tm module is loaded, mark transaction
2229 with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
2231 * If ACK with SDP, then do rtpengine_answer()
2232 * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
2233 rtpengine_delete(). Be careful with calling this function after
2234 resuming a suspended transaction (e.g., after t_continue()),
2235 because the context of executed route is FAILURE ROUTE (in other
2236 words, rtpengine_manage() in the route block of t_continue() does
2237 the same as in failure_route; use a branch route to engage
2238 rtpengine for a forwarded branch after resuming the transaction).
2239 * It does nothing if used inside event_route[tm:branch-failure:...]
2240 * If reply to INVITE with code >= 300 do rtpengine_delete()
2241 * If reply with SDP to INVITE having code 1xx and 2xx, then do
2242 rtpengine_answer() if the request had SDP or tm is not loaded,
2243 otherwise do rtpengine_offer()
2245 This function can be used from ANY_ROUTE.
2247 Example 1.80. rtpengine_manage usage
2252 5.8. start_recording([flags])
2254 This function will send a signal to the RTP relay to record the RTP
2255 stream flowing through it. See also the option “record-call=on” for
2256 rtpengine_manage()/rtpengine_offer(), which offers an alternative for
2257 call recording, saving also call metadata from SDP.
2259 It can take the same parameters as rtpengine_manage(). The flags
2260 parameter to start_recording can be a configuration variable containing
2261 the flags as a string. The call-id flag can be used to start recording
2262 for a different call.
2264 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
2266 Example 1.81. start_recording usage
2271 5.9. stop_recording([flags])
2273 This function will send a signal to the RTP relay to stop recording the
2274 RTP stream flowing through it. See also the option “record-call=off”
2275 for rtpengine_manage()/rtpengine_offer(), which offers an alternative
2278 It can take the same parameters as rtpengine_manage(). The flags
2279 parameter to start_recording can be a configuration variable containing
2280 the flags as a string. The call-id flag can be used to stop recording
2281 for a different call.
2283 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
2285 Example 1.82. stop_recording usage
2290 5.10. block_dtmf([flags])
2292 This function will instruct the RTP proxy to start blocking DTMF event
2293 packets (RFC 4733). DTMF events will still be processed by the RTP
2294 proxy, but they won't be forwarded to the receiving peer.
2296 The call-id flag can be used to block DTMF for a different call.
2298 Without any flags given, DTMF events will be blocked for the entire
2299 call. It's possible to block DTMF directionally only for individual
2300 participants. If the “directional” flag is given, DTMF events will be
2301 blocked for the UA with the currently matching “From” tag. Events can
2302 be blocked for a different UA either by specifying an alternative
2303 “from-tag=...”, or by matching UAs against the media address they
2304 advertised in the SDP using the “address=...” flag (which can contain
2305 either an IPv4 or IPv6 address).
2307 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
2309 Example 1.83. block_dtmf usage
2312 block_dtmf("directional");
2313 block_dtmf("address=192.168.42.42");
2316 5.11. unblock_dtmf([flags])
2318 Reverses the effects of a previously issued block_dtmf call. See above
2319 for a description of which flags can be used.
2321 If DTMF events were previously blocked for individual UAs, then
2322 unblocking DTMF events for the entire call (i.e. no flags given) will
2323 not remove these blocks. The flag “all” can be used to achieve this.
2325 Example 1.84. unblock_dtmf usage
2328 unblock_dtmf("all");
2331 5.12. block_media([flags])
2333 Analogous to “block_dtmf”, but blocks media RTP packets instead of DTMF
2334 events. When media is blocked, DTMF events still pass through the RTP
2337 See “block_dtmf” for a description of the flags that can be used.
2339 Example 1.85. block_media usage
2342 block_media("directional");
2343 block_media("address=192.168.42.42");
2346 5.13. unblock_media([flags])
2348 Analogous to “unblock_dtmf”, but applies to media RTP packets instead
2351 See “unblock_dtmf” for a description of the flags that can be used.
2353 Example 1.86. unblock_media usage
2356 unblock_media("all");
2359 5.14. start_forwarding([flags])
2361 Controls the PCM forwarding feature of the recording daemon. Unlike the
2362 recording feature, PCM forwarding can be done directionally for
2363 individual call participants only, therefore this command takes the
2364 same flags as the media/DTMF blocking commands above.
2366 See “block_dtmf” for a description of the flags that can be used.
2368 Example 1.87. start_forwarding usage
2371 start_forwarding("directional");
2372 start_forwarding("address=192.168.42.42");
2375 5.15. stop_forwarding([flags])
2377 Analogous to “unblock_dtmf”, but controls the PCM forwarding feature
2378 instead of DTMF blocking.
2380 See “unblock_dtmf” for a description of the flags that can be used.
2382 Example 1.88. stop_forwarding usage
2385 stop_forwarding("all");
2388 5.16. play_media([flags])
2390 Instructs rtpengine to play a prerecorded announcement to the selected
2391 call participant, either from a local file or from a file stored in a
2392 database. The participant must be selected using the same flags as are
2393 described under the “block_dtmf” function. If none of these flags are
2394 given, then the “From” tag from the current SIP message context is
2397 If successful, the “media_duration” pseudovariable is filled in with
2398 the duration of the media being played, expressed in milliseconds. If
2399 the length of the media could not be determined, it's set to -1.
2401 Example 1.89. play_media usage
2403 play_media("file=/use/share/media/hello.wav");
2404 play_media("from-tag=tfugklbildfydrtuykgfv db-id=12345");
2407 5.17. stop_media([flags])
2409 Stops the playback of media previously started by “play_media”. Media
2410 playback is automatically stopped when the end of the media file is
2411 reached, so this function is only useful to prematurely stop playback.
2413 Example 1.90. stop_media usage
2416 stop_media("from-tag=5yqaeriguhxcikxj");
2419 5.18. play_dtmf([flags])
2421 Injects a DTMF event into the media stream. Depending on which codecs
2422 were negotiated, this either injects an RFC 2833/4733 DTMF event, or an
2423 in-band PCM DTMF tone into the audio stream. The flag “inject DTMF”
2424 must have been present in both offer and answer messages when the call
2425 was established, which forces all audio to go through rtpengine's
2428 Usage is similar to “play_media” with the following exceptions. The
2429 selected party is not the party that will receive the DTMF event, but
2430 rather the party which is generating the event. This is to support DTMF
2431 events that are carried in SIP INFO messages. Instead of specifying a
2432 media file, a DTMF event code must be specified, as well as optionally
2433 a duration and the volume. The “code” can be a number 0 through 15, or
2434 a DTMF digit (0-9, A-D, *, #). The “duration” is specified in
2435 milliseconds and defaults to 250, within a range of 100-5000. The
2436 “volume” is specified in absolute decibels, with a default of -8 db.
2438 Multiple consecutive DTMF events can be queued up by calling this
2439 function multiple times consecutively. Rtpengine will play out the DTMF
2440 events in sequence, separated by a default pause of 100 ms. An
2441 alternative pause length can be given through the “pause” option,
2442 between 100 and 5000 ms.
2444 Example 1.91. play_dtmf usage
2446 play_dtmf("from-tag=5yqaeriguhxcikxj code=#");
2447 play_dtmf("code=1 volume=5 duration=300 pause=150");
2450 6. Exported Pseudo Variables
2456 Returns the RTP statistics from the RTP proxy. The RTP statistics from
2457 the RTP proxy are provided as a string and it does contain several
2458 packet counters. The statistics must be retrieved before the session is
2459 deleted (before rtpengine_delete()).
2461 Example 1.92. $rtpstat Usage
2463 append_hf("X-RTP-Statistics: $rtpstat\r\n");
2468 7.1. rtpengine.reload
2469 7.2. rtpengine.enable proxy_url/all 0/1
2470 7.3. rtpengine.show proxy_url/all
2471 7.4. rtpengine.ping proxy_url/all
2472 7.5. rtpengine.get_hash_total
2474 7.1. rtpengine.reload
2476 Reloads the database node table content if configured. Returns specific
2477 message related to success, failure and no db_url configured.
2479 NOTE: The current behaviour updates the nodes state or creates new ones
2480 or hides old ones, based on the database content. If allow_op modparam
2481 is enabled, the sessions are still allowed to finish for the hidden old
2484 Example 1.93. rtpengine.reload usage
2486 $ kamcmd rtpengine.reload
2489 7.2. rtpengine.enable proxy_url/all 0/1
2491 Enables a RTP proxy if the second parameter value is greater than 0.
2492 Disables it if a zero value is given. The first parameter is either a
2493 specific RTP proxy url (exactly as defined in the config file) or the
2494 keyword all. The second parameter value must be a number in decimal.
2496 When try to enable the RTP proxy, an application ping command is sent
2497 to it. If it fails, the proxy is not enabled. Displays success or fail
2498 when try to enable/disable.
2500 NOTE: If a RTP proxy is defined multiple times (in the same or diferent
2501 sets), all of its instances will be enabled/disabled.
2503 NOTE: If a RTP proxy is in the disabled permanent state and one tries
2504 to enable it, even if the ping fails, it is moved to a disabled
2505 temporary state and a recheck_ticks are given to it. While the
2506 recheck_ticks are grater than 0, the proxy is considered disabled
2507 temporary, and it is not taken into consideration for sending data.
2508 When the recheck_ticks are 0, the proxy is retested when trying to send
2509 data(not automatically retested), and data can be send to it on
2512 NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
2513 escape the :: from the IPv6 address. See the example below.
2515 Example 1.94. rtpengine.enable usage
2517 $ kamcmd rtpengine.enable udp:192.168.2.133:8081 0
2518 $ kamcmd rtpengine.enable ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
2519 $ kamcmd rtpengine.enable all 1
2522 7.3. rtpengine.show proxy_url/all
2524 Displays all the RTP proxies and their information: set and status
2525 (disabled or not, weight and recheck_ticks). If a RTP proxy has been
2526 disabled by nh_enable_rtpp mi command a "(permanent)" quote will appear
2527 when printing the disabled status. This is to differentiate from a
2528 temporary disable due to the proxy being not found responsive by
2529 kamailio. In addition, when disabled permanent, recheck_ticks have no
2530 meaning and "N\A" is printed instead of the value.
2532 It takes either a specific RTP proxy url (exactly as defined in the
2533 config file) or the keyword all as a parameter.
2535 NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
2536 escape the :: from the IPv6 address. See the example below.
2538 Example 1.95. rtpengine.show usage
2540 $ kamcmd rtpengine.show udp:192.168.2.133:8081
2541 $ kamcmd rtpengine.show ::udp6:fe80::9a90:96ff:fea8:fd99:9999
2542 $ kamcmd rtpengine.show all
2545 7.4. rtpengine.ping proxy_url/all
2547 Sends an application ping command to the RTP proxy. If the proxy does
2548 not respond, it will be disabled, but not permanent. If the proxy
2549 responds, no action is taken. Displays the ping result, i.e. success or
2550 fail when try to ping.
2552 It takes either a specific RTP proxy url (exactly as defined in the
2553 config file) or the keyword all as a parameter.
2555 NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
2556 escape the :: from the IPv6 address. See the example below.
2558 Example 1.96. rtpengine.ping usage
2560 $ kamcmd rtpengine.ping udp:192.168.2.133:8081
2561 $ kamcmd rtpengine.ping ::udp6:fe80::9a90:96ff:fea8:fd99:9999
2562 $ kamcmd rtpengine.ping all
2565 7.5. rtpengine.get_hash_total
2567 Print the total number of hash entries in the hash table at a given
2570 Example 1.97. rtpengine.get_hash_total usage
2572 $ kamcmd rtpengine.get_hash_total
2575 Chapter 2. Frequently Asked Questions
2577 2.1. How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
2578 2.2. Where can I find more about Kamailio?
2579 2.3. Where can I post a question about this module?
2580 2.4. How can I report a bug?
2584 How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
2586 For the most part, only the names of the functions have changed, with
2587 “rtpproxy” in each name replaced with “rtpengine”. For example,
2588 “rtpproxy_manage()” has become “rtpengine_manage()”. A few name
2589 duplications have also been resolved, for example there is now a single
2590 “rtpengine_delete()” instead of “unforce_rtp_proxy()” and the identical
2591 “rtpproxy_destroy()”.
2593 The largest difference to the old module is how flags are passed to
2594 “rtpengine_offer()”, “rtpengine_answer()”, “rtpengine_manage()” and
2595 “rtpengine_delete()”. Instead of having a string of single-letter
2596 flags, they now take a string of space-separated items, with each item
2597 being either a single token (word) or a “key=value” pair.
2599 For example, if you had a call “rtpproxy_offer("FRWOC+PS");”, this
2601 rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
2602 nnection ICE=force RTP/SAVPF");
2604 Finally, if you were using the second parameter (explicit media
2605 address) to any of these functions, this has been replaced by the
2606 “media-address=...” option within the first string of flags.
2610 Where can I find more about Kamailio?
2612 Take a look at https://www.kamailio.org/.
2616 Where can I post a question about this module?
2618 First at all check if your question was already answered on one of our
2620 * User Mailing List -
2621 https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
2622 * Developer Mailing List -
2623 https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
2625 E-mails regarding any stable Kamailio release should be sent to
2626 <sr-users@lists.kamailio.org> and e-mails regarding development
2627 versions should be sent to <sr-dev@lists.kamailio.org>.
2631 How can I report a bug?
2633 Please follow the guidelines provided at:
2634 https://github.com/kamailio/kamailio/issues.
projects / sip-router / blob