src/modules/rtpengine/README
7c1b8e76
 rtpengine Module
ddea262f
 
 Maxim Sobolev
 
    Sippy Software, Inc.
 
 Juha Heinanen
 
    TuTPro, Inc.
 
 Edited by
 
 Maxim Sobolev
 
f0b3ef8c
 Edited by
 
ddea262f
 Bogdan-Andrei Iancu
 
f0b3ef8c
 Edited by
 
ddea262f
 Juha Heinanen
 
f0b3ef8c
 Edited by
 
ddea262f
 Sas Ovidiu
 
f0b3ef8c
 Edited by
 
ddea262f
 Carsten Bock
 
    ng-voice GmbH
 
f0b3ef8c
 Edited by
 
ddea262f
 Richard Fuchs
 
    Sipwise GmbH
 
9cb2a163
    Copyright © 2003-2008 Sippy Software, Inc.
ddea262f
 
9cb2a163
    Copyright © 2005 Voice Sistem SRL
ddea262f
 
9cb2a163
    Copyright © 2009-2014 TuTPro Inc.
ddea262f
 
9cb2a163
    Copyright © 2010 VoIPEmbedded Inc.
ddea262f
 
e72d96eb
    Copyright © 2013-2017 Sipwise GmbH
ddea262f
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
7c1b8e76
         2. Multiple RTP proxy usage
ddea262f
         3. Dependencies
 
               3.1. Kamailio Modules
               3.2. External Libraries or Applications
 
         4. Parameters
 
7c1b8e76
               4.1. rtpengine_sock (string)
               4.2. rtpengine_disable_tout (integer)
bc88adfd
               4.3. aggressive_redetection (integer)
               4.4. rtpengine_tout_ms (integer)
               4.5. rtpengine_allow_op (integer)
               4.6. queried_nodes_limit (integer)
               4.7. rtpengine_retr (integer)
               4.8. extra_id_pv (string)
               4.9. setid_avp (string)
               4.10. force_send_interface (string)
               4.11. read_sdp_pv (string)
               4.12. write_sdp_pv (string)
               4.13. rtp_inst_pvar (string)
               4.14. hash_table_size (integer)
               4.15. hash_table_tout (integer)
               4.16. db_url (string)
               4.17. table_name (string)
               4.18. setid_col (string)
               4.19. url_col (string)
               4.20. weight_col (string)
               4.21. disabled_col (string)
               4.22. setid_default (integer)
               4.23. mos_min_pv (string)
               4.24. mos_min_at_pv (string)
               4.25. mos_min_packetloss_pv (string)
               4.26. mos_min_jitter_pv (string)
               4.27. mos_min_roundtrip_pv (string)
               4.28. mos_max_pv (string)
               4.29. mos_max_at_pv (string)
               4.30. mos_max_packetloss_pv (string)
               4.31. mos_max_jitter_pv (string)
               4.32. mos_max_roundtrip_pv (string)
               4.33. mos_average_pv (string)
               4.34. mos_average_packetloss_pv (string)
               4.35. mos_average_jitter_pv (string)
               4.36. mos_average_roundtrip_pv (string)
               4.37. mos_average_samples_pv (string)
               4.38. mos_A_label_pv (string)
               4.39. mos_min_A_pv (string)
               4.40. mos_min_at_A_pv (string)
               4.41. mos_min_packetloss_A_pv (string)
               4.42. mos_min_jitter_A_pv (string)
               4.43. mos_min_roundtrip_A_pv (string)
               4.44. mos_max_A_pv (string)
               4.45. mos_max_at_A_pv (string)
               4.46. mos_max_packetloss_A_pv (string)
               4.47. mos_max_jitter_A_pv (string)
               4.48. mos_max_roundtrip_A_pv (string)
               4.49. mos_average_A_pv (string)
               4.50. mos_average_packetloss_A_pv (string)
               4.51. mos_average_jitter_A_pv (string)
               4.52. mos_average_roundtrip_A_pv (string)
               4.53. mos_average_samples_A_pv (string)
               4.54. mos_B_label_pv (string)
               4.55. mos_min_B_pv (string)
               4.56. mos_min_at_B_pv (string)
               4.57. mos_min_packetloss_B_pv (string)
               4.58. mos_min_jitter_B_pv (string)
               4.59. mos_min_roundtrip_B_pv (string)
               4.60. mos_max_B_pv (string)
               4.61. mos_max_at_B_pv (string)
               4.62. mos_max_packetloss_B_pv (string)
               4.63. mos_max_jitter_B_pv (string)
               4.64. mos_max_roundtrip_B_pv (string)
               4.65. mos_average_B_pv (string)
               4.66. mos_average_packetloss_B_pv (string)
               4.67. mos_average_jitter_B_pv (string)
               4.68. mos_average_roundtrip_B_pv (string)
               4.69. mos_average_samples_B_pv (string)
3bccc76c
               4.70. control_cmd_tos (integer)
ddea262f
 
         5. Functions
 
1110d4e6
               5.1. set_rtpengine_set(setid[, setid])
7c1b8e76
               5.2. rtpengine_offer([flags])
               5.3. rtpengine_answer([flags])
               5.4. rtpengine_delete([flags])
37a2dc07
               5.5. rtpengine_query([flags])
               5.6. rtpengine_manage([flags])
1542b5bf
               5.7. start_recording([flags])
               5.8. stop_recording([flags])
ddea262f
 
         6. Exported Pseudo Variables
 
eba7dcbe
               6.1. $rtpstat
ddea262f
 
d09412e9
         7. RPC Commands
ddea262f
 
d09412e9
               7.1. rtpengine.reload
e72d96eb
               7.2. rtpengine.enable proxy_url/all 0/1
               7.3. rtpengine.show proxy_url/all
               7.4. rtpengine.ping proxy_url/all
               7.5. rtpengine.get_hash_total
ddea262f
 
    2. Frequently Asked Questions
 
    List of Examples
 
7c1b8e76
    1.1. Set rtpengine_sock parameter
    1.2. Set rtpengine_disable_tout parameter
bc88adfd
    1.3. Set aggressive_redetection parameter
    1.4. Set rtpengine_tout_ms parameter
    1.5. Set rtpengine_allow_op parameter
    1.6. Set queried_nodes_limit parameter
    1.7. Set rtpengine_retr parameter
    1.8. Set extra_id_pv parameter
    1.9. Set setid_avp parameter
    1.10. Set force_send_interface parameter
    1.11. Set read_sdp_pv parameter
    1.12. Set write_sdp_pv parameter
    1.13. Set rtp_inst_pvar parameter
    1.14. Set hash_table_size parameter
    1.15. Set hash_table_tout parameter
    1.16. Set db_url parameter
    1.17. Set table_name parameter
    1.18. Setup rtpengine table
    1.19. Set setid_col parameter
    1.20. Set url_col parameter
    1.21. Set weight_col parameter
    1.22. Set disabled_col parameter
    1.23. Set setid_default parameter
    1.24. Set mos_min_pv parameter
    1.25. Set mos_min_at_pv parameter
    1.26. Set mos_min_packetloss_pv parameter
    1.27. Set mos_min_jitter_pv parameter
    1.28. Set mos_min_roundtrip_pv parameter
    1.29. Set mos_max_pv parameter
    1.30. Set mos_max_at_pv parameter
    1.31. Set mos_max_packetloss_pv parameter
    1.32. Set mos_max_jitter_pv parameter
    1.33. Set mos_max_roundtrip_pv parameter
    1.34. Set mos_average_pv parameter
    1.35. Set mos_average_packetloss_pv parameter
    1.36. Set mos_average_jitter_pv parameter
    1.37. Set mos_average_roundtrip_pv parameter
    1.38. Set mos_average_samples_pv parameter
    1.39. Set mos_A_label_pv parameter
    1.40. Set mos_min_A_pv parameter
    1.41. Set mos_min_at_A_pv parameter
    1.42. Set mos_min_packetloss_A_pv parameter
    1.43. Set mos_min_jitter_A_pv parameter
    1.44. Set mos_min_roundtrip_A_pv parameter
    1.45. Set mos_max_A_pv parameter
    1.46. Set mos_max_at_A_pv parameter
    1.47. Set mos_max_packetloss_A_pv parameter
    1.48. Set mos_max_jitter_A_pv parameter
    1.49. Set mos_max_roundtrip_A_pv parameter
    1.50. Set mos_average_A_pv parameter
    1.51. Set mos_average_packetloss_A_pv parameter
    1.52. Set mos_average_jitter_A_pv parameter
    1.53. Set mos_average_roundtrip_A_pv parameter
    1.54. Set mos_average_samples_A_pv parameter
    1.55. Set mos_B_label_pv parameter
    1.56. Set mos_min_B_pv parameter
    1.57. Set mos_min_at_B_pv parameter
    1.58. Set mos_min_packetloss_B_pv parameter
    1.59. Set mos_min_jitter_B_pv parameter
    1.60. Set mos_min_roundtrip_B_pv parameter
    1.61. Set mos_max_B_pv parameter
    1.62. Set mos_max_at_B_pv parameter
    1.63. Set mos_max_packetloss_B_pv parameter
    1.64. Set mos_max_jitter_B_pv parameter
    1.65. Set mos_max_roundtrip_B_pv parameter
    1.66. Set mos_average_B_pv parameter
    1.67. Set mos_average_packetloss_B_pv parameter
    1.68. Set mos_average_jitter_B_pv parameter
    1.69. Set mos_average_roundtrip_B_pv parameter
    1.70. Set mos_average_samples_B_pv parameter
3bccc76c
    1.71. Set control_cmd_tos parameter
    1.72. set_rtpengine_set usage
    1.73. rtpengine_offer usage
    1.74. rtpengine_answer usage
    1.75. rtpengine_delete usage
    1.76. rtpengine_query usage
    1.77. rtpengine_manage usage
    1.78. start_recording usage
    1.79. stop_recording usage
    1.80. $rtpstat Usage
    1.81. rtpengine.reload usage
    1.82. rtpengine.enable usage
    1.83. rtpengine.show usage
    1.84. rtpengine.ping usage
    1.85. rtpengine.get_hash_total usage
ddea262f
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
7c1b8e76
    2. Multiple RTP proxy usage
ddea262f
    3. Dependencies
 
         3.1. Kamailio Modules
         3.2. External Libraries or Applications
 
    4. Parameters
 
7c1b8e76
         4.1. rtpengine_sock (string)
         4.2. rtpengine_disable_tout (integer)
bc88adfd
         4.3. aggressive_redetection (integer)
         4.4. rtpengine_tout_ms (integer)
         4.5. rtpengine_allow_op (integer)
         4.6. queried_nodes_limit (integer)
         4.7. rtpengine_retr (integer)
         4.8. extra_id_pv (string)
         4.9. setid_avp (string)
         4.10. force_send_interface (string)
         4.11. read_sdp_pv (string)
         4.12. write_sdp_pv (string)
         4.13. rtp_inst_pvar (string)
         4.14. hash_table_size (integer)
         4.15. hash_table_tout (integer)
         4.16. db_url (string)
         4.17. table_name (string)
         4.18. setid_col (string)
         4.19. url_col (string)
         4.20. weight_col (string)
         4.21. disabled_col (string)
         4.22. setid_default (integer)
         4.23. mos_min_pv (string)
         4.24. mos_min_at_pv (string)
         4.25. mos_min_packetloss_pv (string)
         4.26. mos_min_jitter_pv (string)
         4.27. mos_min_roundtrip_pv (string)
         4.28. mos_max_pv (string)
         4.29. mos_max_at_pv (string)
         4.30. mos_max_packetloss_pv (string)
         4.31. mos_max_jitter_pv (string)
         4.32. mos_max_roundtrip_pv (string)
         4.33. mos_average_pv (string)
         4.34. mos_average_packetloss_pv (string)
         4.35. mos_average_jitter_pv (string)
         4.36. mos_average_roundtrip_pv (string)
         4.37. mos_average_samples_pv (string)
         4.38. mos_A_label_pv (string)
         4.39. mos_min_A_pv (string)
         4.40. mos_min_at_A_pv (string)
         4.41. mos_min_packetloss_A_pv (string)
         4.42. mos_min_jitter_A_pv (string)
         4.43. mos_min_roundtrip_A_pv (string)
         4.44. mos_max_A_pv (string)
         4.45. mos_max_at_A_pv (string)
         4.46. mos_max_packetloss_A_pv (string)
         4.47. mos_max_jitter_A_pv (string)
         4.48. mos_max_roundtrip_A_pv (string)
         4.49. mos_average_A_pv (string)
         4.50. mos_average_packetloss_A_pv (string)
         4.51. mos_average_jitter_A_pv (string)
         4.52. mos_average_roundtrip_A_pv (string)
         4.53. mos_average_samples_A_pv (string)
         4.54. mos_B_label_pv (string)
         4.55. mos_min_B_pv (string)
         4.56. mos_min_at_B_pv (string)
         4.57. mos_min_packetloss_B_pv (string)
         4.58. mos_min_jitter_B_pv (string)
         4.59. mos_min_roundtrip_B_pv (string)
         4.60. mos_max_B_pv (string)
         4.61. mos_max_at_B_pv (string)
         4.62. mos_max_packetloss_B_pv (string)
         4.63. mos_max_jitter_B_pv (string)
         4.64. mos_max_roundtrip_B_pv (string)
         4.65. mos_average_B_pv (string)
         4.66. mos_average_packetloss_B_pv (string)
         4.67. mos_average_jitter_B_pv (string)
         4.68. mos_average_roundtrip_B_pv (string)
         4.69. mos_average_samples_B_pv (string)
3bccc76c
         4.70. control_cmd_tos (integer)
ddea262f
 
    5. Functions
 
1110d4e6
         5.1. set_rtpengine_set(setid[, setid])
7c1b8e76
         5.2. rtpengine_offer([flags])
         5.3. rtpengine_answer([flags])
         5.4. rtpengine_delete([flags])
37a2dc07
         5.5. rtpengine_query([flags])
         5.6. rtpengine_manage([flags])
1542b5bf
         5.7. start_recording([flags])
         5.8. stop_recording([flags])
ddea262f
 
    6. Exported Pseudo Variables
 
eba7dcbe
         6.1. $rtpstat
ddea262f
 
d09412e9
    7. RPC Commands
 
         7.1. rtpengine.reload
e72d96eb
         7.2. rtpengine.enable proxy_url/all 0/1
         7.3. rtpengine.show proxy_url/all
         7.4. rtpengine.ping proxy_url/all
         7.5. rtpengine.get_hash_total
ddea262f
 
 1. Overview
 
    This is a module that enables media streams to be proxied via an RTP
    proxy. The only RTP proxy currently known to work with this module is
7c1b8e76
    the Sipwise rtpengine https://github.com/sipwise/rtpengine. The
    rtpengine module is a modified version of the original rtpproxy module
    using a new control protocol. The module is designed to be a drop-in
    replacement for the old module from a configuration file point of view,
    however due to the incompatible control protocol, it only works with
    RTP proxies which specifically support it.
ddea262f
 
7c1b8e76
 2. Multiple RTP proxy usage
ddea262f
 
7c1b8e76
    The rtpengine module can support multiple RTP proxies for
ddea262f
    balancing/distribution and control/selection purposes.
 
    The module allows definition of several sets of rtpproxies.
    Load-balancing will be performed over a set and the admin has the
    ability to choose what set should be used. The set is selected via its
9cb2a163
    id - the id being defined with the set. Refer to the “rtpengine_sock”
ddea262f
    module parameter definition for syntax description.
 
    The balancing inside a set is done automatically by the module based on
7c1b8e76
    the weight of each RTP proxy from the set.
ddea262f
 
    The selection of the set is done from script prior using
7c1b8e76
    rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions -
    see the set_rtpengine_set() function.
ddea262f
 
e005b899
    Another way to select the set is to define setid_avp module parameter
7c1b8e76
    and assign setid to the defined avp before calling rtpengine_offer() or
    rtpengine_manage() function. If forwarding of the requests fails and
e005b899
    there is another branch to try, remember to unset the avp after calling
7c1b8e76
    rtpengine_delete() function.
e005b899
 
ddea262f
    For backward compatibility reasons, a set with no id take by default
7c1b8e76
    the id 0. Also if no set is explicitly set before rtpengine_delete(),
    rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
ddea262f
 
    IMPORTANT: if you use multiple sets, take care and use the same set for
7c1b8e76
    both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
    the set was selected using setid_avp, the avp needs to be set only once
    before rtpengine_offer() or rtpengine_manage() call.
ddea262f
 
00da3663
    From the current implementation point of view, the sets of rtpproxy
    nodes are shared memory(shm), so all processes can see a common list of
    nodes. There is no locking when setting the nodes enabled/disabled (to
    keep the memory access as fast as possible). Thus, problems related to
8868e624
    node state might appear for concurrent processes that might set the
00da3663
    nodes enabled/disabled(e.g. by fifo command). This robustness problems
8868e624
    are overcome as follows.
00da3663
 
    If the current process sees the selected node as disabled, the node is
    force tested before the current process actually takes the disabled
    decision. If the test succeeds, the process will set the node as
    enabled (but other concurrent process might still see it as disabled).
    .
 
    If the current process sees the selected node as enabled, it does no
    additional checks and sends the command which will fail in case the
    machine is actually broken. The process will set the node as disabled
    (but other concurrent process might still see it as enabled).
 
8868e624
    The 'kamctl fifo' commands (including rtpengine ones) are executed by
    an exclusive process which operate on the same shared memory node list.
00da3663
 
    All the nodes are pinged in the beginning by all the processes, even if
    the node list is shared memory.
 
ddea262f
 3. Dependencies
 
    3.1. Kamailio Modules
    3.2. External Libraries or Applications
 
 3.1. Kamailio Modules
 
    The following modules must be loaded before this module:
7c1b8e76
      * tm module - (optional) if you want to have rtpengine_manage() fully
ddea262f
        functional
 
 3.2. External Libraries or Applications
 
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
      * None.
 
 4. Parameters
 
7c1b8e76
    4.1. rtpengine_sock (string)
    4.2. rtpengine_disable_tout (integer)
bc88adfd
    4.3. aggressive_redetection (integer)
    4.4. rtpengine_tout_ms (integer)
    4.5. rtpengine_allow_op (integer)
    4.6. queried_nodes_limit (integer)
    4.7. rtpengine_retr (integer)
    4.8. extra_id_pv (string)
    4.9. setid_avp (string)
    4.10. force_send_interface (string)
    4.11. read_sdp_pv (string)
    4.12. write_sdp_pv (string)
    4.13. rtp_inst_pvar (string)
    4.14. hash_table_size (integer)
    4.15. hash_table_tout (integer)
    4.16. db_url (string)
    4.17. table_name (string)
    4.18. setid_col (string)
    4.19. url_col (string)
    4.20. weight_col (string)
    4.21. disabled_col (string)
    4.22. setid_default (integer)
    4.23. mos_min_pv (string)
    4.24. mos_min_at_pv (string)
    4.25. mos_min_packetloss_pv (string)
    4.26. mos_min_jitter_pv (string)
    4.27. mos_min_roundtrip_pv (string)
    4.28. mos_max_pv (string)
    4.29. mos_max_at_pv (string)
    4.30. mos_max_packetloss_pv (string)
    4.31. mos_max_jitter_pv (string)
    4.32. mos_max_roundtrip_pv (string)
    4.33. mos_average_pv (string)
    4.34. mos_average_packetloss_pv (string)
    4.35. mos_average_jitter_pv (string)
    4.36. mos_average_roundtrip_pv (string)
    4.37. mos_average_samples_pv (string)
    4.38. mos_A_label_pv (string)
    4.39. mos_min_A_pv (string)
    4.40. mos_min_at_A_pv (string)
    4.41. mos_min_packetloss_A_pv (string)
    4.42. mos_min_jitter_A_pv (string)
    4.43. mos_min_roundtrip_A_pv (string)
    4.44. mos_max_A_pv (string)
    4.45. mos_max_at_A_pv (string)
    4.46. mos_max_packetloss_A_pv (string)
    4.47. mos_max_jitter_A_pv (string)
    4.48. mos_max_roundtrip_A_pv (string)
    4.49. mos_average_A_pv (string)
    4.50. mos_average_packetloss_A_pv (string)
    4.51. mos_average_jitter_A_pv (string)
    4.52. mos_average_roundtrip_A_pv (string)
    4.53. mos_average_samples_A_pv (string)
    4.54. mos_B_label_pv (string)
    4.55. mos_min_B_pv (string)
    4.56. mos_min_at_B_pv (string)
    4.57. mos_min_packetloss_B_pv (string)
    4.58. mos_min_jitter_B_pv (string)
    4.59. mos_min_roundtrip_B_pv (string)
    4.60. mos_max_B_pv (string)
    4.61. mos_max_at_B_pv (string)
    4.62. mos_max_packetloss_B_pv (string)
    4.63. mos_max_jitter_B_pv (string)
    4.64. mos_max_roundtrip_B_pv (string)
    4.65. mos_average_B_pv (string)
    4.66. mos_average_packetloss_B_pv (string)
    4.67. mos_average_jitter_B_pv (string)
    4.68. mos_average_roundtrip_B_pv (string)
    4.69. mos_average_samples_B_pv (string)
3bccc76c
    4.70. control_cmd_tos (integer)
ddea262f
 
7c1b8e76
 4.1. rtpengine_sock (string)
ddea262f
 
7c1b8e76
    Definition of socket(s) used to connect to (a set) RTP proxy. It may
ddea262f
    specify a UNIX socket or an IPv4/IPv6 UDP socket.
 
9cb2a163
    Default value is “NONE” (disabled).
ddea262f
 
7c1b8e76
    Example 1.1. Set rtpengine_sock parameter
ddea262f
 ...
 # single rtproxy
7c1b8e76
 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
4a7ad5ee
 # multiple rtproxies for LB with weights (missing weight defaults to 1)
7c1b8e76
 modparam("rtpengine", "rtpengine_sock",
4a7ad5ee
         "udp:localhost:12221=2 udp:localhost:12222=1")
ddea262f
 # multiple sets of multiple rtproxies
7c1b8e76
 modparam("rtpengine", "rtpengine_sock",
ddea262f
         "1 == udp:localhost:12221 udp:localhost:12222")
7c1b8e76
 modparam("rtpengine", "rtpengine_sock",
ddea262f
         "2 == udp:localhost:12225")
 ...
 
7c1b8e76
 4.2. rtpengine_disable_tout (integer)
ddea262f
 
    Once an RTP proxy was found unreachable and marked as disabled, the
7c1b8e76
    rtpengine module will not attempt to establish communication to that
    RTP proxy for rtpengine_disable_tout seconds.
ddea262f
 
9cb2a163
    Default value is “60”.
ddea262f
 
0527dea7
    Can be set at runtime, e.g.:
                         $ kamcmd cfg.set_now_int rtpengine rtpengine_disable_tou
 t 20
 
7c1b8e76
    Example 1.2. Set rtpengine_disable_tout parameter
ddea262f
 ...
7c1b8e76
 modparam("rtpengine", "rtpengine_disable_tout", 20)
ddea262f
 ...
 
bc88adfd
 4.3. aggressive_redetection (integer)
 
    This parameter determines what happens when all potential rtpengines
    are found to be unreachable. If enabled, the sip server will send pings
8868e624
    to all rtpengines, else no rtpengine will be queried until its
bc88adfd
    rtpengine_disable_tout timeout passes.
 
    Default value is “1”.
 
    Can be set at runtime, e.g.:
                         $ kamcmd cfg.set_now_int rtpengine aggressive_redetectio
 n 0
 
    Example 1.3. Set aggressive_redetection parameter
 ...
 modparam("rtpengine", "aggressive_redetection", 0)
 ...
 
 4.4. rtpengine_tout_ms (integer)
ddea262f
 
4a7ad5ee
    Timeout value expressed in milliseconds in waiting for reply from RTP
    proxy.
ddea262f
 
9cb2a163
    Default value is “1000”.
ddea262f
 
0527dea7
    Can be set at runtime, e.g.:
                         $ kamcmd cfg.set_now_int rtpengine rtpengine_tout_ms 100
 0
 
bc88adfd
    Example 1.4. Set rtpengine_tout_ms parameter
ddea262f
 ...
4a7ad5ee
 modparam("rtpengine", "rtpengine_tout_ms", 2000)
ddea262f
 ...
 
bc88adfd
 4.5. rtpengine_allow_op (integer)
00da3663
 
    Enable this to allow finishing the current sessions while denying new
    sessions for the manually deactivated nodes via kamctl command i.e.
    "disabled(permanent)" nodes. Probably the manually deactivated machine
    is still running(did not crash).
 
8868e624
    This is useful when deactivating a node for maintenance and reject new
00da3663
    sessions but allow current ones to finish.
 
    The behaviour is the same for a rtpengine deleted table node. When the
    node is deleted from the table and the table reloaded (see
    nh_reload_rtpp) the node actually is disabled(permanent) and hidden for
    display. Next time the same node will be added in the table, and the
    content reloaded, it will be updated and re-displayed.
 
9cb2a163
    Default value is “0” to keep the current behaviour.
00da3663
 
bc88adfd
    Example 1.5. Set rtpengine_allow_op parameter
00da3663
 ...
 modparam("rtpengine", "rtpengine_allow_op", 1)
 ...
 
bc88adfd
 4.6. queried_nodes_limit (integer)
4a7ad5ee
 
    The total number of nodes inside a set (sets are configurable via
    rtpengine_sock function) to be queried before giving up establishing a
    session. This brings more flexibility in case checking all rtpengines
0527dea7
    would take too long. Max limit is 30.
4a7ad5ee
 
    By default all nodes in a set are tried before giving up communicating
    with the rtpengines.
 
0527dea7
    Can be set at runtime, e.g.:
                         $ kamcmd cfg.set_now_int rtpengine queried_nodes_limit 5
 
bc88adfd
    Example 1.6. Set queried_nodes_limit parameter
4a7ad5ee
 ...
 modparam("rtpengine", "queried_nodes_limit", 5)
 ...
 
bc88adfd
 4.7. rtpengine_retr (integer)
ddea262f
 
    How many times the module should retry to send and receive after
    timeout was generated.
 
9cb2a163
    Default value is “5”.
ddea262f
 
0527dea7
    Can be set at runtime, e.g.:
                         $ kamcmd cfg.set_now_int rtpengine rtpengine_retr 5
 
bc88adfd
    Example 1.7. Set rtpengine_retr parameter
ddea262f
 ...
7c1b8e76
 modparam("rtpengine", "rtpengine_retr", 2)
ddea262f
 ...
 
bc88adfd
 4.8. extra_id_pv (string)
ddea262f
 
8868e624
    The parameter sets the PV definition to use when the “b” parameter is
7c1b8e76
    used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
    rtpengine_manage() command.
ddea262f
 
9cb2a163
    Default is empty, the “b” parameter may not be used then.
ddea262f
 
bc88adfd
    Example 1.8. Set extra_id_pv parameter
ddea262f
 ...
7c1b8e76
 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
ddea262f
 ...
 
bc88adfd
 4.9. setid_avp (string)
e005b899
 
7c1b8e76
    The parameter defines an AVP that, if set, determines which RTP proxy
    set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
    rtpengine_manage() functions use.
e005b899
 
    There is no default value.
 
bc88adfd
    Example 1.9. Set setid_avp parameter
e005b899
 ...
7c1b8e76
 modparam("rtpengine", "setid_avp", "$avp(setid)")
e005b899
 ...
 
bc88adfd
 4.10. force_send_interface (string)
56164cfc
 
    Forces all control messages between the SIP proxy and the RTP proxy to
4e6d2ae0
    be sent from the specified local interface. Both IPv4 and IPv6
    addresses are supported. If not specified, the default interface
    selected by the operating system will be used. Note: when
    rtpengine_sock is a IPv6 link-local address, one _must_ set this
    parameter in order to successfully connect to RTP engine. This is
8868e624
    necessarily because OS needs additional scope_id hint to communicate
4e6d2ae0
    over IPv6 link locals. The scope_id is resolved based on the given
    IPv6.
56164cfc
 
    There is no default value.
 
bc88adfd
    Example 1.10. Set force_send_interface parameter
56164cfc
 ...
 modparam("rtpengine", "force_send_interface", "10.3.7.123")
4e6d2ae0
 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
 fd99")
56164cfc
 ...
 
bc88adfd
 4.11. read_sdp_pv (string)
00da3663
 
    If this parameter is set to a valid AVP or script var specifier,
    rtpengine will take the input SDP from this pv instead of the message
    body.
 
    There is no default value.
 
bc88adfd
    Example 1.11. Set read_sdp_pv parameter
00da3663
 ...
 modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
 ...
 route {
         ...
         $var(sdp) = $rb + "a=foo:bar\r\n";
         rtpengine_manage();
 }
 
bc88adfd
 4.12. write_sdp_pv (string)
91b3d9b9
 
    If this parameter is set to a valid AVP or script var specifier, the
    SDP returned by rtpengine in the offer/answer operations is returned in
    the specified variable instead of the message body.
 
    There is no default value.
 
bc88adfd
    Example 1.12. Set write_sdp_pv parameter
91b3d9b9
 ...
38ee440e
 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
91b3d9b9
 ...
00da3663
 route {
         ...
         rtpengine_manage();
         set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
 }
91b3d9b9
 
bc88adfd
 4.13. rtp_inst_pvar (string)
91b3d9b9
 
    A pseudo variable to store the chosen RTP Engine IP address. If this
    parameter is set, the IP address and port of the instance chosen will
    be stored in the given variable.
 
    By default, this parameter is not set.
 
bc88adfd
    Example 1.13. Set rtp_inst_pvar parameter
00da3663
 ...
 modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
 ...
 
bc88adfd
 4.14. hash_table_size (integer)
00da3663
 
    Size of the hash table. Default value is 256.
 
    NOTE: If configured size is less than 1, the size will be defaulted to
    1.
 
bc88adfd
    Example 1.14. Set hash_table_size parameter
91b3d9b9
 ...
00da3663
 modparam("rtpengine", "hash_table_size", "123")
 ...
 
bc88adfd
 4.15. hash_table_tout (integer)
00da3663
 
    Number of seconds after an rtpengine hash table entry is marked for
    deletion. By default, this parameter is set to 3600 (seconds).
 
    To maintain information about a selected rtp machine node, for a given
    call, entries are added in a hashtable of (callid, node) pairs. When
    command comes, lookup callid. If found, return chosen node. If not
    found, choose a new node, insert it in the hastable and return the
    chosen node.
 
    NOTE: In the current implementation, the actual deletion happens on the
    fly, while insert/remove/lookup the hastable, only for the entries in
    the insert/remove/lookup path.
 
    NOTE: When configuring this parameter, one should consider maximum call
    time VS share memory for unfinished calls.
 
bc88adfd
    Example 1.15. Set hash_table_tout parameter
00da3663
 ...
 modparam("rtpengine", "hash_table_tout", "300")
 ...
 
bc88adfd
 4.16. db_url (string)
00da3663
 
    The rtpengine datablase url. If present and valid, it activates
    database mode. Node information is read from database, not from config.
 
    By default, the datablase url is NULL (not set).
 
bc88adfd
    Example 1.16. Set db_url parameter
00da3663
 ...
 modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
 ...
 
bc88adfd
 4.17. table_name (string)
00da3663
 
    The rtpengine table name. If database mode is activated (i.e. valid
    db_url), set the name of rtpengine table, on startup.
 
    By default, the rtpengine table name is "rtpengine".
 
    NOTE: One needs to add the version of the rtpengine table in the
    version table. The current version is version 1.
 
bc88adfd
    Example 1.17. Set table_name parameter
00da3663
 ...
 modparam("rtpengine", "table_name", "rtpengine_table_name")
 ...
 
bc88adfd
    Example 1.18. Setup rtpengine table
00da3663
 mysql> describe rtpengine;
 +----------+------------------+------+-----+---------------------+-------+
 | Field    | Type             | Null | Key | Default             | Extra |
 +----------+------------------+------+-----+---------------------+-------+
 | setid    | int(10) unsigned | NO   | PRI | 0                   |       |
 | url      | varchar(64)      | NO   | PRI | NULL                |       |
 | weight   | int(10) unsigned | NO   |     | 1                   |       |
 | disabled | int(1)           | NO   |     | 0                   |       |
 | stamp    | datetime         | NO   |     | 1900-01-01 00:00:01 |       |
 +----------+------------------+------+-----+---------------------+-------+
 
 mysql> select * from rtpengine;
 +-------+---------------------------+--------+----------+---------------------+
 | setid | url                       | weight | disabled | stamp               |
 +-------+---------------------------+--------+----------+---------------------+
 |     0 | udp:rtpproxy1.domain:8800 |      1 |        0 | 2016-03-10 10:30:54 |
 |     0 | udp:rtpproxy2.domain:8800 |      1 |        1 | 2016-03-10 10:30:54 |
 +-------+---------------------------+--------+----------+---------------------+
 
 mysql> select * from version;
 +---------------------------+---------------+
 | table_name                | table_version |
 +---------------------------+---------------+
 | rtpengine                 |             1 |
 +---------------------------+---------------+
 
bc88adfd
 4.18. setid_col (string)
00da3663
 
    Column name in the rtpengine table. If database mode is activated (i.e.
    valid db_url), set the setid of rtp nodes according to this column, on
    startup. The MySQL value for this column should be INT UNSIGNED.
 
    By default, the column name is "setid".
 
bc88adfd
    Example 1.19. Set setid_col parameter
00da3663
 ...
 modparam("rtpengine", "setid_col", "setid_column_name")
 ...
 
bc88adfd
 4.19. url_col (string)
00da3663
 
    Column name in the rtpengine table. If database mode is activated (i.e.
    valid db_url), set the url of rtp nodes according to this column, on
    startup. The MySQL value for this column should be VARCHAR.
 
    By default, the column name is "url".
 
bc88adfd
    Example 1.20. Set url_col parameter
00da3663
 ...
 modparam("rtpengine", "url_col", "url_column_name")
 ...
 
bc88adfd
 4.20. weight_col (string)
00da3663
 
    Column name in the rtpengine table. If database mode is activated (i.e.
    valid db_url), set the weight of rtp nodes according to this column, on
    startup. The column value has priority over the URL weight. The MySQL
    value for this column should be INT UNSIGNED.
 
    By default, the column name is "weight".
 
bc88adfd
    Example 1.21. Set weight_col parameter
00da3663
 ...
 modparam("rtpengine", "weight_col", "weight_column_name")
 ...
 
bc88adfd
 4.21. disabled_col (string)
00da3663
 
    Column name in the rtpengine table. If database mode is activated (i.e.
    valid db_url), set the state of rtp nodes according to this column, on
    startup. The MySQL value for this column should be INT.
 
    By default, the column name is "disabled".
 
bc88adfd
    Example 1.22. Set disabled_col parameter
00da3663
 ...
 modparam("rtpengine", "disabled_col", "disabled_column_name")
 ...
 
bc88adfd
 4.22. setid_default (integer)
00da3663
 
    The default set of nodes to be used.
 
    By default, the setid is 0.
 
    NOTE that if setid_avp is configured, this value will be ignored and
    the active set will be chosen according to the setid_avp.
 
bc88adfd
    Example 1.23. Set setid_default parameter
00da3663
 ...
 modparam("rtpengine", "setid_default", 11)
91b3d9b9
 ...
 
bc88adfd
 4.23. mos_min_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the minimum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.24. Set mos_min_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_pv", "$avp(mos_min)")
 ...
 
bc88adfd
 4.24. mos_min_at_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the minimum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.25. Set mos_min_at_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_at_pv", "$avp(mos_min_at)")
 ...
 
bc88adfd
 4.25. mos_min_packetloss_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.26. Set mos_min_packetloss_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_packetloss_pv", "$avp(mos_min_packetloss)")
 ...
 
bc88adfd
 4.26. mos_min_jitter_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.27. Set mos_min_jitter_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_jitter_pv", "$avp(mos_min_jitter)")
 ...
 
bc88adfd
 4.27. mos_min_roundtrip_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.28. Set mos_min_roundtrip_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_roundtrip_pv", "$avp(mos_min_roundtrip)")
 ...
 
bc88adfd
 4.28. mos_max_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the maximum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.29. Set mos_max_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_pv", "$avp(mos_max)")
 ...
 
bc88adfd
 4.29. mos_max_at_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the maximum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.30. Set mos_max_at_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_at_pv", "$avp(mos_max_at)")
 ...
 
bc88adfd
 4.30. mos_max_packetloss_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.31. Set mos_max_packetloss_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_packetloss_pv", "$avp(mos_max_packetloss)")
 ...
 
bc88adfd
 4.31. mos_max_jitter_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.32. Set mos_max_jitter_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_jitter_pv", "$avp(mos_max_jitter)")
 ...
 
bc88adfd
 4.32. mos_max_roundtrip_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.33. Set mos_max_roundtrip_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_roundtrip_pv", "$avp(mos_max_roundtrip)")
 ...
 
bc88adfd
 4.33. mos_average_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) MOS value for
    the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.34. Set mos_average_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_pv", "$avp(mos_average)")
 ...
 
bc88adfd
 4.34. mos_average_packetloss_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    packetloss in percent present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.35. Set mos_average_packetloss_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_packetloss_pv", "$avp(mos_average_packetloss)
 ")
 ...
 
bc88adfd
 4.35. mos_average_jitter_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    jitter in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.36. Set mos_average_jitter_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_jitter_pv", "$avp(mos_average_jitter)")
 ...
 
bc88adfd
 4.36. mos_average_roundtrip_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) packet
    round-trip time in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.37. Set mos_average_roundtrip_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_roundtrip_pv", "$avp(mos_average_roundtrip)")
 ...
 
bc88adfd
 4.37. mos_average_samples_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the number of samples used to
    determine the other “average” MOS data points.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
bc88adfd
    Example 1.38. Set mos_average_samples_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_samples_pv", "$avp(mos_average_samples)")
 ...
 
bc88adfd
 4.38. mos_A_label_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold a custom label used in rtpengine
    signalling. If set, all the statistics pseudovariables with the “_A”
    suffix will be filled in with statistics only from the call legs that
    match the label given in this variable.
 
    There is no default value.
 
bc88adfd
    Example 1.39. Set mos_A_label_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_A_label_pv", "$avp(mos_A_label)")
 ...
 
bc88adfd
 4.39. mos_min_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the minimum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.40. Set mos_min_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_A_pv", "$avp(mos_min_A)")
 ...
 
bc88adfd
 4.40. mos_min_at_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the minimum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.41. Set mos_min_at_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_at_A_pv", "$avp(mos_min_at_A)")
 ...
 
bc88adfd
 4.41. mos_min_packetloss_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.42. Set mos_min_packetloss_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_packetloss_A_pv", "$avp(mos_min_packetloss_A)")
 ...
 
bc88adfd
 4.42. mos_min_jitter_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.43. Set mos_min_jitter_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_jitter_A_pv", "$avp(mos_min_jitter_A)")
 ...
 
bc88adfd
 4.43. mos_min_roundtrip_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.44. Set mos_min_roundtrip_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_roundtrip_A_pv", "$avp(mos_min_roundtrip_A)")
 ...
 
bc88adfd
 4.44. mos_max_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the maximum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.45. Set mos_max_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_A_pv", "$avp(mos_max_A)")
 ...
 
bc88adfd
 4.45. mos_max_at_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the maximum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.46. Set mos_max_at_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_at_A_pv", "$avp(mos_max_at_A)")
 ...
 
bc88adfd
 4.46. mos_max_packetloss_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.47. Set mos_max_packetloss_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_packetloss_A_pv", "$avp(mos_max_packetloss_A)")
 ...
 
bc88adfd
 4.47. mos_max_jitter_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.48. Set mos_max_jitter_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_jitter_A_pv", "$avp(mos_max_jitter_A)")
 ...
 
bc88adfd
 4.48. mos_max_roundtrip_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.49. Set mos_max_roundtrip_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_roundtrip_A_pv", "$avp(mos_max_roundtrip_A)")
 ...
 
bc88adfd
 4.49. mos_average_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) MOS value for
    the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.50. Set mos_average_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_A_pv", "$avp(mos_average_A)")
 ...
 
bc88adfd
 4.50. mos_average_packetloss_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    packetloss in percent present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.51. Set mos_average_packetloss_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_packetloss_A_pv", "$avp(mos_average_packetlos
 s_A)")
 ...
 
bc88adfd
 4.51. mos_average_jitter_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    jitter in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.52. Set mos_average_jitter_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_jitter_A_pv", "$avp(mos_average_jitter_A)")
 ...
 
bc88adfd
 4.52. mos_average_roundtrip_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) packet
    round-trip time in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.53. Set mos_average_roundtrip_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_roundtrip_A_pv", "$avp(mos_average_roundtrip_
 A)")
 ...
 
bc88adfd
 4.53. mos_average_samples_A_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the number of samples used to
    determine the other “average” MOS data points.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_A_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.54. Set mos_average_samples_A_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_samples_A_pv", "$avp(mos_average_samples_A)")
 ...
 
bc88adfd
 4.54. mos_B_label_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold a custom label used in rtpengine
    signalling. If set, all the statistics pseudovariables with the “_B”
    suffix will be filled in with statistics only from the call legs that
    match the label given in this variable.
 
    There is no default value.
 
bc88adfd
    Example 1.55. Set mos_B_label_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_B_label_pv", "$avp(mos_B_label)")
 ...
 
bc88adfd
 4.55. mos_min_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the minimum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.56. Set mos_min_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_B_pv", "$avp(mos_min_B)")
 ...
 
bc88adfd
 4.56. mos_min_at_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the minimum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.57. Set mos_min_at_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_at_B_pv", "$avp(mos_min_at_B)")
 ...
 
bc88adfd
 4.57. mos_min_packetloss_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.58. Set mos_min_packetloss_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_packetloss_B_pv", "$avp(mos_min_packetloss_B)")
 ...
 
bc88adfd
 4.58. mos_min_jitter_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.59. Set mos_min_jitter_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_jitter_B_pv", "$avp(mos_min_jitter_B)")
 ...
 
bc88adfd
 4.59. mos_min_roundtrip_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the minimum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.60. Set mos_min_roundtrip_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_min_roundtrip_B_pv", "$avp(mos_min_roundtrip_B)")
 ...
 
bc88adfd
 4.60. mos_max_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the maximum encountered MOS value
    for the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.61. Set mos_max_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_B_pv", "$avp(mos_max_B)")
 ...
 
bc88adfd
 4.61. mos_max_at_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the timestamp of when the maximum
    MOS value was encountered during the call, such as “0:30” for 30
    seconds after the start of the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.62. Set mos_max_at_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_at_B_pv", "$avp(mos_max_at_B)")
 ...
 
bc88adfd
 4.62. mos_max_packetloss_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of packetloss in
    percent at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.63. Set mos_max_packetloss_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_packetloss_B_pv", "$avp(mos_max_packetloss_B)")
 ...
 
bc88adfd
 4.63. mos_max_jitter_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the amount of jitter in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.64. Set mos_max_jitter_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_jitter_B_pv", "$avp(mos_max_jitter_B)")
 ...
 
bc88adfd
 4.64. mos_max_roundtrip_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the packet round-trip time in
    milliseconds at the time the maximum MOS value was encountered;
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.65. Set mos_max_roundtrip_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_max_roundtrip_B_pv", "$avp(mos_max_roundtrip_B)")
 ...
 
bc88adfd
 4.65. mos_average_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) MOS value for
    the call. The value typically has a range of 1.0 through 5.0.
 
    There is no default value.
 
    This value is filled in after invoking“rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.66. Set mos_average_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_B_pv", "$avp(mos_average_B)")
 ...
 
bc88adfd
 4.66. mos_average_packetloss_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    packetloss in percent present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.67. Set mos_average_packetloss_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_packetloss_B_pv", "$avp(mos_average_packetlos
 s_B)")
 ...
 
bc88adfd
 4.67. mos_average_jitter_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) amount of
    jitter in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.68. Set mos_average_jitter_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_jitter_B_pv", "$avp(mos_average_jitter_B)")
 ...
 
bc88adfd
 4.68. mos_average_roundtrip_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the average (median) packet
    round-trip time in milliseconds present throughout the call.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.69. Set mos_average_roundtrip_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_roundtrip_B_pv", "$avp(mos_average_roundtrip_
 B)")
 ...
 
bc88adfd
 4.69. mos_average_samples_B_pv (string)
37a2dc07
 
    The name of a pseudovariable to hold the number of samples used to
    determine the other “average” MOS data points.
 
    There is no default value.
 
    This value is filled in after invoking “rtpengine_delete”,
    “rtpengine_query”, or “rtpengine_manage” if the command resulted in a
    deletion of the call (or call branch).
 
    Only call legs matching the rtpengine label given in the
    “mos_B_label_pv” will be used in calculating this statistics value.
 
bc88adfd
    Example 1.70. Set mos_average_samples_B_pv parameter
37a2dc07
 ...
 modparam("rtpengine", "mos_average_samples_B_pv", "$avp(mos_average_samples_B)")
 ...
 
3bccc76c
 4.70. control_cmd_tos (integer)
 
    The parameter is used to set the value of “type of service (tos)” for
    the control commands (such as rtpengine_offer(), rtpengine_answer()
    etc).
 
    There is no default value. By default this feature is not used.
 
    The values not falling into the range “0-255” will be simply ignored.
 
    Example 1.71. Set control_cmd_tos parameter
 ...
 modparam("rtpengine", "control_cmd_tos", "144")
 ...
 
ddea262f
 5. Functions
 
1110d4e6
    5.1. set_rtpengine_set(setid[, setid])
7c1b8e76
    5.2. rtpengine_offer([flags])
    5.3. rtpengine_answer([flags])
    5.4. rtpengine_delete([flags])
37a2dc07
    5.5. rtpengine_query([flags])
    5.6. rtpengine_manage([flags])
1542b5bf
    5.7. start_recording([flags])
    5.8. stop_recording([flags])
ddea262f
 
9cb2a163
 5.1.  set_rtpengine_set(setid[, setid])
ddea262f
 
7c1b8e76
    Sets the ID of the RTP proxy set to be used for the next
    rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
    rtpengine_manage() command. The parameter can be an integer or a config
ddea262f
    variable holding an integer.
 
1110d4e6
    A second set ID can be specified to daisy-chain two RTP proxies. The
    two set IDs must be distinct from each other and there must not be any
    overlap in the proxies present in both sets. In this use case, the
    request (offer, answer, etc) is first sent to an RTP proxy from the
    first set, which rewrites the SDP body and sends it back to the module.
    The rewritten SDP body is then used to make another request to an RTP
    proxy from the second set, which rewrites the SDP body another time and
    sends it back to the module to be placed back into the SIP message.
    This is useful if you have a set of RTP proxies that the caller must
    use, and another distinct set of RTP proxies that the callee must use.
    This is supported by all rtpengine commands except rtpengine_manage().
 
ddea262f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    BRANCH_ROUTE.
 
3bccc76c
    Example 1.72. set_rtpengine_set usage
ddea262f
 ...
7c1b8e76
 set_rtpengine_set("2");
 rtpengine_offer();
ddea262f
 ...
 
9cb2a163
 5.2.  rtpengine_offer([flags])
ddea262f
 
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
1110d4e6
    To be invoked on INVITE for the cases the SDP bodies are in INVITE and
    200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
ddea262f
 
00da3663
    The function will return true on success and false (-1) on various
    failures, like using rtp_engine_offer() on a SIP MESSAGE request or
    communication with rtpengine fails.
 
ddea262f
    Meaning of the parameters is as follows:
      * flags - flags to turn on some features.
9cb2a163
        The “flags” string is a list of space-separated items. Each item is
        either an individual token, or a token in “key=value” format. The
7c1b8e76
        possible tokens are described below.
9cb2a163
           + via-branch=... - Include the “branch” value of one of the
             “Via” headers in the request to the RTP proxy. Possible values
             are: “1” - use the first “Via” header; “2” - use the second
             “Via” header; “auto” - use the first “Via” header if this is a
             request, or the second one if this is a reply; “extra” - don't
7c1b8e76
             take the value from a header, but instead use the value of the
9cb2a163
             “extra_id_pv” variable. This can be used to create one media
7c1b8e76
             session per branch on the RTP proxy. When sending a subsequent
9cb2a163
             “delete” command to the RTP proxy, you can then stop just the
7c1b8e76
             session for a specific branch when passing the flag '1' or '2'
9cb2a163
             in the “rtpengine_delete”, or stop all sessions for a call
7c1b8e76
             when not passing one of those two flags there. This is
             especially useful if you have serially forked call scenarios
9cb2a163
             where the RTP proxy gets an “offer” command for a new branch,
             and then a “delete” command for the previous branch, which
7c1b8e76
             would otherwise delete the full call, breaking the subsequent
9cb2a163
             “answer” for the new branch. This flag is only supported by
7c1b8e76
             the Sipwise rtpengine RTP proxy at the moment!
           + asymmetric - flags that UA from which message is received
1110d4e6
             doesn't support symmetric RTP. Disables learning of endpoint
             addresses in the Sipwise rtpengine proxy.
ff004839
           + no-redis-update - this flag can be used by Kamailio in order
             to tell rtpengine not to persist the call into Redis upon
             receiving offer/answer() control commands. If flag is not set,
             default action is rtpengine persists call to redis.
9cb2a163
           + force-answer - force “answer”, that is, only rewrite SDP when
ddea262f
             corresponding session already exists in the RTP proxy. By
             default is on when the session is to be completed.
1110d4e6
           + direction=... - this option specifies a logical network
             interface and should be given exactly twice. It enables RTP
             bridging between different addresses or networks of the same
             family (e.g. IPv4 to IPv4). The first instance of the option
             specifies the interface that the originator of this message
             should be using, while the second instance specifies the
             interface that the target should be using. For example, if the
             SIP message was sent by an endpoint on a private network and
             will be sent to an endpoint on the public internet, you would
9cb2a163
             use “direction=priv direction=pub” if those two logical
             network interfaces were called “priv” and “pub” in your RTP
1110d4e6
             proxy's configuration respectively. The direction must only be
             specified in for initial SDP offer; answers or subsequent
             offers can omit this option.
9cb2a163
           + internal, external - shorthand for “direction=internal” and
             “direction=external” respectively. Useful for brevity or as
1110d4e6
             legacy option if the RTP proxy only supports two network
             interfaces instead of multiple, arbitrarily named ones.
9cb2a163
           + auto-bridge - this flag an alternative to the “internal” and
             “external” flags in order to do automatic bridging between
7c1b8e76
             IPv4 on the "internal network" and IPv6 on the "external
             network". Instead of explicitly instructing the RTP proxy to
             select a particular address family, the distinction is done by
             the given IP in the SDP body by the RTP proxy itself. Not
             supported by Sipwise rtpengine.
           + address-family=... - instructs the RTP proxy that the
             recipient of this SDP body expects to see addresses of a
9cb2a163
             particular family. Possible values are “IP4” and “IP6”. For
7c1b8e76
             example, if the SDP body contains IPv4 addresses but the
9cb2a163
             recipient only speaks IPv6, you would use “address-family=IP6”
7c1b8e76
             to bridge between the two address families.
             Sipwise rtpengine remembers the address family preference of
             each party after it has seen an SDP body from them. This means
             that normally it is only necessary to explicitly specify the
9cb2a163
             address family in the “offer”, but not in the “answer”.
ddea262f
             Note: Please note, that this will only work properly with
             non-dual-stack user-agents or with dual-stack clients
             according to RFC6157 (which suggest ICE for Dual-Stack
             implementations). This short-cut will not work properly with
             RFC4091 (ANAT) compatible clients, which suggests having
             different m-lines with different IP-protocols grouped
             together.
7c1b8e76
           + force - instructs the RTP proxy to ignore marks inserted by
             another RTP proxy in transit to indicate that the session is
             already goes through another proxy. Allows creating a chain of
             proxies. Not supported and ignored by Sipwise rtpengine.
           + trust-address - flags that IP address in SDP should be
4e6d2ae0
             trusted. Starting with rtpengine 3.8, this is the default
             behaviour. In older versions, without this flag the RTP proxy
             ignores the address in the SDP and uses source address of the
             SIP message as media address which is passed to the RTP proxy.
           + SIP-source-address - the opposite of trust-address. Restores
             the old default behaviour of ignoring endpoint addresses in
             the SDP body.
7c1b8e76
           + replace-origin - flags that IP from the origin description
             (o=) should be also changed.
           + replace-session-connection - flags to change the session-level
             SDP connection (c=) IP if media description also includes
             connection information.
           + symmetric - flags that for the UA from which message is
1110d4e6
             received, support symmetric RTP must be forced. Does nothing
             with the Sipwise rtpengine proxy as it is the default.
7c1b8e76
           + repacketize=NN - requests the RTP proxy to perform
             re-packetization of RTP traffic coming from the UA which has
             sent the current message to increase or decrease payload size
             per each RTP packet forwarded if possible. The NN is the
             target payload size in ms, for the most codecs its value
             should be in 10ms increments, however for some codecs the
             increment could differ (e.g. 30ms for GSM or 20ms for G.723).
             The RTP proxy would select the closest value supported by the
             codec. This feature could be used for significantly reducing
             bandwith overhead for low bitrate codecs, for example with
             G.729 going from 10ms to 100ms saves two thirds of the network
             bandwith. Not supported by Sipwise rtpengine.
           + ICE=... - controls the RTP proxy's behaviour regarding ICE
9cb2a163
             attributes within the SDP body. Possible values are: “force” -
7c1b8e76
             discard any ICE attributes already present in the SDP body and
             then generate and insert new ICE data, leaving itself as the
9cb2a163
             only ICE candidates; “force-relay” - discard any “relay” type
c9aa1aab
             ICE attributes already present in the SDP body and then
9cb2a163
             generate and insert itself as the only ICE “relay” candidates;
             “remove” instructs the RTP proxy to discard any ICE attributes
c9aa1aab
             and not insert any new ones into the SDP. The default (if no
9cb2a163
             “ICE=...” is given at all), new ICE data will only be
c9aa1aab
             generated if no ICE was present in the SDP originally;
             otherwise the RTP proxy will only insert itself as additional
             ICE candidate. Other SDP substitutions (c=, m=, etc) are
             unaffected by this flag.
755ce7bf
           + RTP, SRTP, DTLS, AVP, AVPF - These flags control the RTP
             transport protocol that should be used towards the recipient
             of the SDP. If none of them are specified, the protocol given
             in the SDP is left untouched. Otherwise, the “SRTP” flag
             indicates that SRTP should be used, while “RTP” indicates that
             SRTP should not be used. “AVPF” indicates that the advanced
             RTCP profile with feedback messages should be used, and “AVP”
             indicates that the regular RTCP profile should be used. See
             also the next set of flags below.
           + RTP/AVP, RTP/SAVP, UDP/TLS/RTP/SAVP, RTP/AVPF, RTP/SAVPF,
             UDP/TLS/RTP/SAVPF - these serve as an alternative, more
             explicit way to select between the different RTP protocols and
             profiles supported by the RTP proxy. For example, giving the
             flag “RTP/SAVPF” has the same effect as giving the two flags
             “SRTP AVPF”.
9cb2a163
           + to-tag - force inclusion of the “To” tag. Normally, the “To”
             tag is always included when present, except for “delete”
             messages. Including the “To” tag in a “delete” messages allows
7c1b8e76
             you to be more selective about which dialogues within a call
             are being torn down.
a813dec2
           + to-tag=... - use the specified string as “To” tag instead of
             the actual “To” tag from the SIP message, and force inclusion
             of the tag in the message as per above.
           + from-tag=... - use the specified string as “From” tag instead
             of the actual “From” tag from the SIP message.
           + call-id=... - use the specified string as “Call-ID” instead of
             the actual “Call-ID” from the SIP message.
7c1b8e76
           + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
             RTP proxy accept the offer, but not offer it to the recipient
             of this message.
           + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
             reject the offer, but still offer it to the recipient. Can be
9cb2a163
             combined with “rtcp-mux-offer” to always offer it.
7c1b8e76
           + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
             recipient of this message, regardless of whether it was
             offered originally or not.
           + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
             accept the offer and also offer it to the recipient of this
9cb2a163
             message. Can be combined with “rtcp-mux-offer” to always offer
7c1b8e76
             it.
           + media-address=... - force a particular media address to be
             used in the SDP body. Address family is detected
             automatically.
1110d4e6
           + TOS=... - change the IP TOS value for all outgoing RTP packets
             within the entire call in both directions. Only honoured in an
9cb2a163
             “offer”, ignored for an “answer”. Valid values are 0 through
1110d4e6
             255, given in decimal. If this option is not specified, the
             TOS value will revert to the default TOS (normally 184). A
             value of -1 may be used to leave the currently used TOS
             unchanged.
4e6d2ae0
           + delete-delay=... - override the default delay (in seconds)
             before a call is actually deleted from memory. Can be set to
             zero to effectuate immediate deletion. This option only makes
             sense for delete operations.
           + strict-source - instructs the RTP proxy to check the source
             addresses of all incoming RTP packets and drop the packets if
             the address doesn't match.
           + media-handover - the antithesis of strict-source. Instructs
             the RTP proxy not only to accept mismatching RTP source
             addresses (as it normally would), but also to accept them as
             the new endpoint address of the opposite media flow. Not
             recommended as it allows media streams to be hijacked by an
             attacker.
           + DTLS=... - influence the behaviour of DTLS-SRTP. Possible
9cb2a163
             values are “no” or “off” to suppress offering or accepting
             DTLS-SRTP, and “passive” to prefer participating in DTLS-SRTP
4e6d2ae0
             in a passive role.
           + SDES-off - don't offer SDES when it normally would. In an SRTP
             context, this leaves DTLS-SRTP as the only other option.
           + SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
             SDES-unauthenticated_srtp - these directly reflect the SDES
             session parameters from RFC 4568 and will make the RTP proxy
             offer these parameters when offering SDES.
           + SDES-encrypted_srtp, SDES-encrypted_srtcp,
             SDES-authenticated_srtp - the opposites of the flags above.
             Useful if accepting these parameters is not desired and they
             should be rejected instead.
7769b15a
           + unidirectional - allows kernelization of one-way streams in
             the Sipwise rtpengine proxy. This is especially useful when
             the first call leg is handled by some rtpengine machine while
             the second call leg is handled by other rtpengine machine.
fcc4b8ed
           + record-call=on - instructs RTPEngine to record the session.
             Use it in rtpengine_offer() to start recording immediately and
             save the call metadata, as alternative to start_recording().
8549789a
           + metadata - a generic metadata string. The metadata will be
             used when recording calls to provide custom additional
             information. More details about this are found in the
             rtpengine README.
fcc4b8ed
        Check also the documentation of RTPEngine, these flags are
        documented there as well: https://github.com/sipwise/rtpengine.
ddea262f
 
    This function can be used from ANY_ROUTE.
 
3bccc76c
    Example 1.73. rtpengine_offer usage
ddea262f
 route {
 ...
     if (is_method("INVITE")) {
aa15067b
         if (has_body("application/sdp")) {
7c1b8e76
             if (rtpengine_offer())
ddea262f
                 t_on_reply("1");
         } else {
             t_on_reply("2");
         }
     }
aa15067b
     if (is_method("ACK") && has_body("application/sdp"))
7c1b8e76
         rtpengine_answer();
ddea262f
 ...
 }
 
 onreply_route[1]
 {
 ...
aa15067b
     if (has_body("application/sdp"))
7c1b8e76
         rtpengine_answer();
ddea262f
 ...
 }
 
 onreply_route[2]
 {
 ...
aa15067b
     if (has_body("application/sdp"))
7c1b8e76
         rtpengine_offer();
ddea262f
 ...
 }
 
9cb2a163
 5.3.  rtpengine_answer([flags])
ddea262f
 
    Rewrites SDP body to ensure that media is passed through an RTP proxy.
1110d4e6
    To be invoked on 200 OK for the cases the SDP bodies are in INVITE and
    200 OK and on ACK when SDP bodies are in 200 OK and ACK.
ddea262f
 
7c1b8e76
    See rtpengine_offer() function description above for the meaning of the
ddea262f
    parameters.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
3bccc76c
    Example 1.74. rtpengine_answer usage
ddea262f
 
7c1b8e76
    See rtpengine_offer() function example above for example.
ddea262f
 
9cb2a163
 5.4.  rtpengine_delete([flags])
ddea262f
 
37a2dc07
    Tears down the RTPProxy session for the current call. This populates
    the statistics pseudovariables (such “mos_min_pv” etc).
ddea262f
 
7c1b8e76
    See rtpengine_offer() function description above for the meaning of the
9cb2a163
    parameters. Note that not all flags make sense for a “delete”.
7c1b8e76
 
ddea262f
    This function can be used from ANY_ROUTE.
 
3bccc76c
    Example 1.75. rtpengine_delete usage
7c1b8e76
 ...
 rtpengine_delete();
 ...
 
37a2dc07
 5.5.  rtpengine_query([flags])
 
    Queries the RTP proxy about the current status and statistics of a
    running call. This populates the statistics pseudovariables (such
    “mos_min_pv” etc).
 
    See rtpengine_offer() function description above for the meaning of the
    parameters. Note that not all flags make sense for a “query”.
 
    This function can be used from ANY_ROUTE.
 
3bccc76c
    Example 1.76. rtpengine_query usage
37a2dc07
 ...
 rtpengine_query();
 ...
 
 5.6.  rtpengine_manage([flags])
ddea262f
 
    Manage the RTPProxy session - it combines the functionality of
7c1b8e76
    rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
ddea262f
    internally based on message type and method which one to execute.
 
7c1b8e76
    It can take the same parameters as rtpengine_offer(). The flags
    parameter to rtpengine_manage() can be a configuration variable
ddea262f
    containing the flags as a string.
 
    Functionality:
7c1b8e76
      * If INVITE with SDP, then do rtpengine_offer()
ddea262f
      * If INVITE with SDP, when the tm module is loaded, mark transaction
        with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
7c1b8e76
        rtpengine_answer()
      * If ACK with SDP, then do rtpengine_answer()
650087d6
      * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
        rtpengine_delete(). Be careful with calling this function after
        resuming a suspended transaction (e.g., after t_continue()),
        because the context of executed route is FAILURE ROUTE (in other
        words, rtpengine_manage() in the route block of t_continue() does
        the same as in failure_route).
7c1b8e76
      * If reply to INVITE with code >= 300 do rtpengine_delete()
ddea262f
      * If reply with SDP to INVITE having code 1xx and 2xx, then do
7c1b8e76
        rtpengine_answer() if the request had SDP or tm is not loaded,
        otherwise do rtpengine_offer()
ddea262f
 
    This function can be used from ANY_ROUTE.
 
3bccc76c
    Example 1.77. rtpengine_manage usage
ddea262f
 ...
7c1b8e76
 rtpengine_manage();
ddea262f
 ...
 
1542b5bf
 5.7.  start_recording([flags])
eba7dcbe
 
fcc4b8ed
    This function will send a signal to the RTP relay to record the RTP
    stream flowing through it. See also the option “record-call=on” for
    rtpengine_manage()/rtpengine_offer(), which offers an alternative for
    call recording, saving also call metadata from SDP.
eba7dcbe
 
1542b5bf
    It can take the same parameters as rtpengine_manage(). The flags
    parameter to start_recording can be a configuration variable containing
    the flags as a string. The call-id flag can be used to start recording
    for a different call.
 
eba7dcbe
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
 
3bccc76c
    Example 1.78. start_recording usage
eba7dcbe
 ...
 start_recording();
 ...
 
1542b5bf
 5.8.  stop_recording([flags])
 
    This function will send a signal to the RTP relay to stop recording the
    RTP stream flowing through it. See also the option “record-call=off”
    for rtpengine_manage()/rtpengine_offer(), which offers an alternative
    for call recording.
 
    It can take the same parameters as rtpengine_manage(). The flags
    parameter to start_recording can be a configuration variable containing
    the flags as a string. The call-id flag can be used to stop recording
    for a different call.
 
    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
 
3bccc76c
    Example 1.79. stop_recording usage
1542b5bf
 ...
 stop_recording();
 ...
 
ddea262f
 6. Exported Pseudo Variables
 
eba7dcbe
    6.1. $rtpstat
ddea262f
 
eba7dcbe
 6.1. $rtpstat
ddea262f
 
7c1b8e76
    Returns the RTP statistics from the RTP proxy. The RTP statistics from
    the RTP proxy are provided as a string and it does contain several
eba7dcbe
    packet counters. The statistics must be retrieved before the session is
7c1b8e76
    deleted (before rtpengine_delete()).
ddea262f
 
3bccc76c
    Example 1.80. $rtpstat Usage
ddea262f
 ...
     append_hf("X-RTP-Statistics: $rtpstat\r\n");
 ...
 
d09412e9
 7. RPC Commands
 
    7.1. rtpengine.reload
e72d96eb
    7.2. rtpengine.enable proxy_url/all 0/1
    7.3. rtpengine.show proxy_url/all
    7.4. rtpengine.ping proxy_url/all
    7.5. rtpengine.get_hash_total
d09412e9
 
 7.1. rtpengine.reload
 
    Reloads the database node table content if configured. Returns specific
    message related to success, failure and no db_url configured.
 
    NOTE: The current behaviour updates the nodes state or creates new ones
    or hides old ones, based on the database content. If allow_op modparam
    is enabled, the sessions are still allowed to finish for the hidden old
    nodes.
 
3bccc76c
    Example 1.81.  rtpengine.reload usage
d09412e9
 ...
 $ kamcmd rtpengine.reload
 ...
 
e72d96eb
 7.2. rtpengine.enable proxy_url/all 0/1
ddea262f
 
eba5c3b8
    Enables a RTP proxy if the second parameter value is greater than 0.
    Disables it if a zero value is given. The first parameter is either a
    specific RTP proxy url (exactly as defined in the config file) or the
    keyword all. The second parameter value must be a number in decimal.
ddea262f
 
eba5c3b8
    When try to enable the RTP proxy, an application ping command is sent
    to it. If it fails, the proxy is not enabled. Displays success or fail
    when try to enable/disable.
ddea262f
 
eba5c3b8
    NOTE: If a RTP proxy is defined multiple times (in the same or diferent
    sets), all of its instances will be enabled/disabled.
ddea262f
 
eba5c3b8
    NOTE: If a RTP proxy is in the disabled permanent state and one tries
    to enable it, even if the ping fails, it is moved to a disabled
    temporary state and a recheck_ticks are given to it. While the
    recheck_ticks are grater than 0, the proxy is considered disabled
    temporary, and it is not taken into consideration for sending data.
    When the recheck_ticks are 0, the proxy is retested when trying to send
    data(not automatically retested), and data can be send to it on
    success.
ddea262f
 
eba5c3b8
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
3bccc76c
    Example 1.82.  rtpengine.enable usage
ddea262f
 ...
e72d96eb
 $ kamcmd rtpengine.enable udp:192.168.2.133:8081 0
 $ kamcmd rtpengine.enable ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
 $ kamcmd rtpengine.enable all 1
ddea262f
 ...
 
e72d96eb
 7.3. rtpengine.show proxy_url/all
ddea262f
 
7c1b8e76
    Displays all the RTP proxies and their information: set and status
4a7ad5ee
    (disabled or not, weight and recheck_ticks). If a RTP proxy has been
eba5c3b8
    disabled by nh_enable_rtpp mi command a "(permanent)" quote will appear
    when printing the disabled status. This is to differentiate from a
    temporary disable due to the proxy being not found responsive by
    kamailio. In addition, when disabled permanent, recheck_ticks have no
    meaning and "N\A" is printed instead of the value.
 
    It takes either a specific RTP proxy url (exactly as defined in the
    config file) or the keyword all as a parameter.
 
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
 
3bccc76c
    Example 1.83.  rtpengine.show usage
eba5c3b8
 ...
e72d96eb
 $ kamcmd rtpengine.show udp:192.168.2.133:8081
 $ kamcmd rtpengine.show ::udp6:fe80::9a90:96ff:fea8:fd99:9999
 $ kamcmd rtpengine.show all
eba5c3b8
 ...
 
e72d96eb
 7.4. rtpengine.ping proxy_url/all
eba5c3b8
 
    Sends an application ping command to the RTP proxy. If the proxy does
    not respond, it will be disabled, but not permanent. If the proxy
    responds, no action is taken. Displays the ping result, i.e. success or
    fail when try to ping.
 
    It takes either a specific RTP proxy url (exactly as defined in the
    config file) or the keyword all as a parameter.
ddea262f
 
eba5c3b8
    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
    escape the :: from the IPv6 address. See the example below.
ddea262f
 
3bccc76c
    Example 1.84.  rtpengine.ping usage
00da3663
 ...
e72d96eb
 $ kamcmd rtpengine.ping udp:192.168.2.133:8081
 $ kamcmd rtpengine.ping ::udp6:fe80::9a90:96ff:fea8:fd99:9999
 $ kamcmd rtpengine.ping all
00da3663
 ...
 
e72d96eb
 7.5. rtpengine.get_hash_total
00da3663
 
    Print the total number of hash entries in the hash table at a given
    moment.
 
3bccc76c
    Example 1.85.  rtpengine.get_hash_total usage
00da3663
 ...
e72d96eb
 $ kamcmd rtpengine.get_hash_total
00da3663
 ...
 
ddea262f
 Chapter 2. Frequently Asked Questions
 
9cb2a163
    2.1. How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
ddea262f
    2.2. Where can I find more about Kamailio?
    2.3. Where can I post a question about this module?
    2.4. How can I report a bug?
 
    2.1.
 
9cb2a163
    How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
7c1b8e76
 
    For the most part, only the names of the functions have changed, with
9cb2a163
    “rtpproxy” in each name replaced with “rtpengine”. For example,
    “rtpproxy_manage()” has become “rtpengine_manage()”. A few name
7c1b8e76
    duplications have also been resolved, for example there is now a single
9cb2a163
    “rtpengine_delete()” instead of “unforce_rtp_proxy()” and the identical
    “rtpproxy_destroy()”.
7c1b8e76
 
    The largest difference to the old module is how flags are passed to
9cb2a163
    “rtpengine_offer()”, “rtpengine_answer()”, “rtpengine_manage()” and
    “rtpengine_delete()”. Instead of having a string of single-letter
7c1b8e76
    flags, they now take a string of space-separated items, with each item
9cb2a163
    being either a single token (word) or a “key=value” pair.
7c1b8e76
 
9cb2a163
    For example, if you had a call “rtpproxy_offer("FRWOC+PS");”, this
7c1b8e76
    would then become:
 rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
 nnection ICE=force RTP/SAVPF");
ddea262f
 
8868e624
    Finally, if you were using the second parameter (explicit media
7c1b8e76
    address) to any of these functions, this has been replaced by the
9cb2a163
    “media-address=...” option within the first string of flags.
ddea262f
 
    2.2.
 
7c1b8e76
    Where can I find more about Kamailio?
ddea262f
 
ff1bcdb4
    Take a look at https://www.kamailio.org/.
ddea262f
 
    2.3.
 
7c1b8e76
    Where can I post a question about this module?
ddea262f
 
7c1b8e76
    First at all check if your question was already answered on one of our
    mailing lists:
      * User Mailing List -
ff1bcdb4
        https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
7c1b8e76
      * Developer Mailing List -
ff1bcdb4
        https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
ddea262f
 
7c1b8e76
    E-mails regarding any stable Kamailio release should be sent to
ff1bcdb4
    <sr-users@lists.kamailio.org> and e-mails regarding development
    versions should be sent to <sr-dev@lists.kamailio.org>.
ddea262f
 
6f79e7cc
    Please report security issues to <management at kamailio dot org>.
ddea262f
 
    2.4.
 
7c1b8e76
    How can I report a bug?
ddea262f
 
7c1b8e76
    Please follow the guidelines provided at:
f0b3ef8c
    https://github.com/kamailio/kamailio/issues.