rtpengine Module

Maxim Sobolev

Sippy Software, Inc.

Juha Heinanen

TuTPro, Inc.

Edited by

Maxim Sobolev

Edited by

Bogdan-Andrei Iancu

Edited by

Juha Heinanen

Edited by

Sas Ovidiu

Edited by

Carsten Bock

ng-voice GmbH

Edited by

Richard Fuchs

Sipwise GmbH

Table of Contents

1. Admin Guide
1. Overview
2. Multiple RTP proxy usage
3. Dependencies
3.1. Kamailio Modules
3.2. External Libraries or Applications
4. Parameters
4.1. rtpengine_sock (string)
4.2. rtpengine_disable_tout (integer)
4.3. rtpengine_tout_ms (integer)
4.4. rtpengine_allow_op (integer)
4.5. queried_nodes_limit (integer)
4.6. rtpengine_retr (integer)
4.7. extra_id_pv (string)
4.8. setid_avp (string)
4.9. force_send_interface (string)
4.10. read_sdp_pv (string)
4.11. write_sdp_pv (string)
4.12. rtp_inst_pvar (string)
4.13. hash_table_size (integer)
4.14. hash_table_tout (integer)
4.15. db_url (string)
4.16. table_name (string)
4.17. setid_col (string)
4.18. url_col (string)
4.19. weight_col (string)
4.20. disabled_col (string)
4.21. setid_default (string)
5. Functions
5.1. set_rtpengine_set(setid[, setid])
5.2. rtpengine_offer([flags])
5.3. rtpengine_answer([flags])
5.4. rtpengine_delete([flags])
5.5. rtpengine_manage([flags])
5.6. start_recording()
6. Exported Pseudo Variables
6.1. $rtpstat
7. MI Commands
7.1. nh_enable_rtpp proxy_url/all 0/1
7.2. nh_show_rtpp proxy_url/all
7.3. nh_ping_rtpp proxy_url/all
7.4. nh_reload_rtpp
7.5. nh_show_hash_total
2. Frequently Asked Questions

List of Examples

1.1. Set rtpengine_sock parameter
1.2. Set rtpengine_disable_tout parameter
1.3. Set rtpengine_tout_ms parameter
1.4. Set rtpengine_allow_op parameter
1.5. Set queried_nodes_limit parameter
1.6. Set rtpengine_retr parameter
1.7. Set extra_id_pv parameter
1.8. Set setid_avp parameter
1.9. Set force_send_interface parameter
1.10. Set read_sdp_pv parameter
1.11. Set write_sdp_pv parameter
1.12. Set rtp_inst_pvar parameter
1.13. Set hash_table_size parameter
1.14. Set hash_table_tout parameter
1.15. Set db_url parameter
1.16. Set table_name parameter
1.17. Setup rtpengine table
1.18. Set setid_col parameter
1.19. Set url_col parameter
1.20. Set weight_col parameter
1.21. Set disabled_col parameter
1.22. Set setid_default parameter
1.23. set_rtpengine_set usage
1.24. rtpengine_offer usage
1.25. rtpengine_answer usage
1.26. rtpengine_delete usage
1.27. rtpengine_manage usage
1.28. start_recording usage
1.29. $rtpstat Usage
1.30. nh_enable_rtpp usage
1.31. nh_show_rtpp usage
1.32. nh_ping_rtpp usage
1.33. nh_reload_rtpp usage
1.34. nh_show_hash_total usage

Chapter 1. Admin Guide

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 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.

2. Multiple RTP proxy usage

The rtpengine module can support multiple RTP proxies for 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 id - the id being defined with the set. Refer to the rtpengine_sock module parameter definition for syntax description.

The balancing inside a set is done automatically by the module based on the weight of each RTP proxy from the set.

The selection of the set is done from script prior using rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions - see the set_rtpengine_set() function.

Another way to select the set is to define setid_avp module parameter and assign setid to the defined avp before calling rtpengine_offer() or rtpengine_manage() function. If forwarding of the requests fails and there is another branch to try, remember to unset the avp after calling rtpengine_delete() function.

For backward compatibility reasons, a set with no id take by default 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.

IMPORTANT: if you use multiple sets, take care and use the same set for 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.

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 node state might appear for concurent processes that might set the nodes enabled/disabled(e.g. by fifo command). This robustness problems are overcomed as follows.

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).

The 'kamctl fifo' commands (including rtpengin ones) are executed by an exclusive process which operate on the same shared memory node list.

All the nodes are pinged in the beginning by all the processes, even if the node list is shared memory.

3. Dependencies

3.1. Kamailio Modules

The following modules must be loaded before this module:

  • tm module - (optional) if you want to have rtpengine_manage() fully 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

4.1. rtpengine_sock (string)

Definition of socket(s) used to connect to (a set) RTP proxy. It may specify a UNIX socket or an IPv4/IPv6 UDP socket.

Default value is NONE (disabled).

Example 1.1. Set rtpengine_sock parameter

# single rtproxy
modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
# multiple rtproxies for LB with weights (missing weight defaults to 1)
modparam("rtpengine", "rtpengine_sock",
	"udp:localhost:12221=2 udp:localhost:12222=1")
# multiple sets of multiple rtproxies
modparam("rtpengine", "rtpengine_sock",
	"1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpengine", "rtpengine_sock",
	"2 == udp:localhost:12225")

4.2. rtpengine_disable_tout (integer)

Once an RTP proxy was found unreachable and marked as disabled, the rtpengine module will not attempt to establish communication to that RTP proxy for rtpengine_disable_tout seconds.

Default value is 60.

Example 1.2. Set rtpengine_disable_tout parameter

modparam("rtpengine", "rtpengine_disable_tout", 20)

4.3. rtpengine_tout_ms (integer)

Timeout value expressed in milliseconds in waiting for reply from RTP proxy.

Default value is 1000.

Example 1.3. Set rtpengine_tout_ms parameter

modparam("rtpengine", "rtpengine_tout_ms", 2000)

4.4. rtpengine_allow_op (integer)

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).

This is useful when deactivating a node for maintanance and reject new 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.

Default value is 0 to keep the current behaviour.

Example 1.4. Set rtpengine_allow_op parameter

modparam("rtpengine", "rtpengine_allow_op", 1)

4.5. queried_nodes_limit (integer)

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 would take too long. Max limit is 50.

By default all nodes in a set are tried before giving up communicating with the rtpengines.

Example 1.5. Set queried_nodes_limit parameter

modparam("rtpengine", "queried_nodes_limit", 5)

4.6. rtpengine_retr (integer)

How many times the module should retry to send and receive after timeout was generated.

Default value is 5.

Example 1.6. Set rtpengine_retr parameter

modparam("rtpengine", "rtpengine_retr", 2)

4.7. extra_id_pv (string)

The parameter sets the PV defination to use when the b parameter is used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or rtpengine_manage() command.

Default is empty, the b parameter may not be used then.

Example 1.7. Set extra_id_pv parameter

modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")

4.8. setid_avp (string)

The parameter defines an AVP that, if set, determines which RTP proxy set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and rtpengine_manage() functions use.

There is no default value.

Example 1.8. Set setid_avp parameter

modparam("rtpengine", "setid_avp", "$avp(setid)")

4.9. force_send_interface (string)

Forces all control messages between the SIP proxy and the RTP proxy to 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 necessarely because OS needs additional scope_id hint to communicate over IPv6 link locals. The scope_id is resolved based on the given IPv6.

There is no default value.

Example 1.9. Set force_send_interface parameter

modparam("rtpengine", "force_send_interface", "")
modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:fd99")

4.10. read_sdp_pv (string)

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.

Example 1.10. Set read_sdp_pv parameter

modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
route {
	$var(sdp) = $rb + "a=foo:bar\r\n";

4.11. write_sdp_pv (string)

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.

Example 1.11. Set write_sdp_pv parameter

modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
route {
	set_body("$avp(sdp)a=baz123\r\n", "application/sdp");

4.12. rtp_inst_pvar (string)

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.

Example 1.12. Set rtp_inst_pvar parameter

modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")

4.13. hash_table_size (integer)

Size of the hash table. Default value is 256.

NOTE: If configured size is less than 1, the size will be defaulted to 1.

Example 1.13. Set hash_table_size parameter

modparam("rtpengine", "hash_table_size", "123")

4.14. hash_table_tout (integer)

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.

Example 1.14. Set hash_table_tout parameter

modparam("rtpengine", "hash_table_tout", "300")

4.15. db_url (string)

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).

Example 1.15. Set db_url parameter

modparam("rtpengine", "db_url", "mysql://pass@localhost/db")

4.16. table_name (string)

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.

Example 1.16. Set table_name parameter

modparam("rtpengine", "table_name", "rtpengine_table_name")

Example 1.17. Setup rtpengine table

mysql> describe rtpengine;
| Field    | Type             | Null | Key | Default | Extra |
| setid    | int(10) unsigned | NO   |     | NULL    |       |
| url      | varchar(256)     | NO   |     | NULL    |       |
| weight   | int(10) unsigned | NO   |     | NULL    |       |
| disabled | int(11)          | NO   |     | NULL    |       |

mysql> select * from rtpengine;
| setid | url                       | weight | disabled |
|     0 | udp:rtpproxy1.domain:8800 |    100 |        0 |
|     0 | udp:rtpproxy2.domain:8800 |    200 |        1 |

mysql> select * from version;
| table_name                | table_version |
| rtpengine                 |             1 |

4.17. setid_col (string)

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".

Example 1.18. Set setid_col parameter

modparam("rtpengine", "setid_col", "setid_column_name")

4.18. url_col (string)

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".

Example 1.19. Set url_col parameter

modparam("rtpengine", "url_col", "url_column_name")

4.19. weight_col (string)

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".

Example 1.20. Set weight_col parameter

modparam("rtpengine", "weight_col", "weight_column_name")

4.20. disabled_col (string)

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".

Example 1.21. Set disabled_col parameter

modparam("rtpengine", "disabled_col", "disabled_column_name")

4.21. setid_default (string)

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.

Example 1.22. Set setid_default parameter

modparam("rtpengine", "setid_default", 11)

5. Functions

5.1.  set_rtpengine_set(setid[, setid])

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 variable holding an integer.

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().

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE.

Example 1.23. set_rtpengine_set usage


5.2.  rtpengine_offer([flags])

Rewrites SDP body to ensure that media is passed through an RTP proxy. 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.

Meaning of the parameters is as follows:

  • flags - flags to turn on some features.

    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 possible tokens are described below.

    • 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 take the value from a header, but instead use the value of the extra_id_pv variable. This can be used to create one media session per branch on the RTP proxy. When sending a subsequent delete command to the RTP proxy, you can then stop just the session for a specific branch when passing the flag '1' or '2' in the rtpengine_delete, or stop all sessions for a call when not passing one of those two flags there. This is especially useful if you have serially forked call scenarios where the RTP proxy gets an offer command for a new branch, and then a delete command for the previous branch, which would otherwise delete the full call, breaking the subsequent answer for the new branch. This flag is only supported by the Sipwise rtpengine RTP proxy at the moment!

    • asymmetric - flags that UA from which message is received doesn't support symmetric RTP. Disables learning of endpoint addresses in the Sipwise rtpengine proxy.

    • force-answer - force answer, that is, only rewrite SDP when corresponding session already exists in the RTP proxy. By default is on when the session is to be completed.

    • 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 use direction=priv direction=pub if those two logical network interfaces were called priv and pub in your RTP proxy's configuration respectively. The direction must only be specified in for initial SDP offer; answers or subsequent offers can omit this option.

    • internal, external - shorthand for direction=internal and direction=external respectively. Useful for brevity or as legacy option if the RTP proxy only supports two network interfaces instead of multiple, arbitrarily named ones.

    • auto-bridge - this flag an alternative to the internal and external flags in order to do automatic bridging between 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 particular family. Possible values are IP4 and IP6. For example, if the SDP body contains IPv4 addresses but the recipient only speaks IPv6, you would use address-family=IP6 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 address family in the offer, but not in the answer.

      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.

    • 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 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.

    • 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 received, support symmetric RTP must be forced. Does nothing with the Sipwise rtpengine proxy as it is the default.

    • 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 attributes within the SDP body. Possible values are: force - discard any ICE attributes already present in the SDP body and then generate and insert new ICE data, leaving itself as the only ICE candidates; force-relay - discard any relay type ICE attributes already present in the SDP body and then generate and insert itself as the only ICE relay candidates; remove instructs the RTP proxy to discard any ICE attributes and not insert any new ones into the SDP. The default (if no ICE=... is given at all), new ICE data will only be 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.

    • RTP, SRTP, 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, RTP/AVPF, 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.

    • 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 you to be more selective about which dialogues within a call are being torn down.

    • 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 combined with rtcp-mux-offer to always offer it.

    • 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 message. Can be combined with rtcp-mux-offer to always offer it.

    • media-address=... - force a particular media address to be used in the SDP body. Address family is detected automatically.

    • TOS=... - change the IP TOS value for all outgoing RTP packets within the entire call in both directions. Only honoured in an offer, ignored for an answer. Valid values are 0 through 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.

    • 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 values are no or off to suppress offering or accepting DTLS-SRTP, and passive to prefer participating in DTLS-SRTP 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.

This function can be used from ANY_ROUTE.

Example 1.24. rtpengine_offer usage

route {
    if (is_method("INVITE")) {
        if (has_body("application/sdp")) {
            if (rtpengine_offer())
        } else {
    if (is_method("ACK") && has_body("application/sdp"))

    if (has_body("application/sdp"))

    if (has_body("application/sdp"))

5.3.  rtpengine_answer([flags])

Rewrites SDP body to ensure that media is passed through an RTP proxy. 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.

See rtpengine_offer() function description above for the meaning of the parameters.


Example 1.25. rtpengine_answer usage

See rtpengine_offer() function example above for example.

5.4.  rtpengine_delete([flags])

Tears down the RTPProxy session for the current call.

See rtpengine_offer() function description above for the meaning of the parameters. Note that not all flags make sense for a delete.

This function can be used from ANY_ROUTE.

Example 1.26. rtpengine_delete usage


5.5.  rtpengine_manage([flags])

Manage the RTPProxy session - it combines the functionality of rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting internally based on message type and method which one to execute.

It can take the same parameters as rtpengine_offer(). The flags parameter to rtpengine_manage() can be a configuration variable containing the flags as a string.


  • If INVITE with SDP, then do rtpengine_offer()

  • 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 rtpengine_answer()

  • If ACK with SDP, then do rtpengine_answer()

  • 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).

  • If reply to INVITE with code >= 300 do rtpengine_delete()

  • If reply with SDP to INVITE having code 1xx and 2xx, then do rtpengine_answer() if the request had SDP or tm is not loaded, otherwise do rtpengine_offer()

This function can be used from ANY_ROUTE.

Example 1.27. rtpengine_manage usage


5.6.  start_recording()

This function will send a signal to the RTP proxy to record the RTP stream on the RTP proxy. This function is not supported by Sipwise rtpengine at the moment!

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

Example 1.28. start_recording usage


6. Exported Pseudo Variables

6.1. $rtpstat

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 packet counters. The statistics must be retrieved before the session is deleted (before rtpengine_delete()).

Example 1.29. $rtpstat Usage

    append_hf("X-RTP-Statistics: $rtpstat\r\n");

7. MI Commands

7.1. nh_enable_rtpp proxy_url/all 0/1

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.

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.

NOTE: If a RTP proxy is defined multiple times (in the same or diferent sets), all of its instances will be enabled/disabled.

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.

NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to escape the :: from the IPv6 address. See the example below.

Example 1.30.  nh_enable_rtpp usage

$ kamctl fifo nh_enable_rtpp udp: 0
$ kamctl fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
$ kamctl fifo nh_enable_rtpp all 1

7.2. nh_show_rtpp proxy_url/all

Displays all the RTP proxies and their information: set and status (disabled or not, weight and recheck_ticks). If a RTP proxy has been 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.

Example 1.31.  nh_show_rtpp usage

$ kamctl fifo nh_show_rtpp udp:
$ kamctl fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
$ kamctl fifo nh_show_rtpp all

7.3. nh_ping_rtpp proxy_url/all

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.

NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to escape the :: from the IPv6 address. See the example below.

Example 1.32.  nh_ping_rtpp usage

$ kamctl fifo nh_ping_rtpp udp:
$ kamctl fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
$ kamctl fifo nh_ping_rtpp all

7.4. nh_reload_rtpp

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.

Example 1.33.  nh_reload_rtpp usage

$ kamctl fifo nh_reload_rtpp

7.5. nh_show_hash_total

Print the total number of hash entries in the hash table at a given moment.

Example 1.34.  nh_show_hash_total usage

$ kamctl fifo nh_show_hash_total

Chapter 2. Frequently Asked Questions

2.1. How do I migrate from “rtpproxy” or “rtpproxy-ng” to “rtpengine”?
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?


How do I migrate from rtpproxy or rtpproxy-ng to rtpengine?

For the most part, only the names of the functions have changed, with rtpproxy in each name replaced with rtpengine. For example, rtpproxy_manage() has become rtpengine_manage(). A few name duplications have also been resolved, for example there is now a single rtpengine_delete() instead of unforce_rtp_proxy() and the identical rtpproxy_destroy().

The largest difference to the old module is how flags are passed to rtpengine_offer(), rtpengine_answer(), rtpengine_manage() and rtpengine_delete(). Instead of having a string of single-letter flags, they now take a string of space-separated items, with each item being either a single token (word) or a key=value pair.

For example, if you had a call rtpproxy_offer("FRWOC+PS");, this would then become:

rtpengine_offer("force trust-address symmetric replace-origin replace-session-connection ICE=force RTP/SAVPF");

Finally, if you were using the second paramater (explicit media address) to any of these functions, this has been replaced by the media-address=... option within the first string of flags.


Where can I find more about Kamailio?

Take a look at http://www.kamailio.org/.


Where can I post a question about this module?

First at all check if your question was already answered on one of our mailing lists:

E-mails regarding any stable Kamailio release should be sent to and e-mails regarding development versions should be sent to .

If you want to keep the mail private, send it to .


How can I report a bug?

Please follow the guidelines provided at: https://github.com/kamailio/kamailio/issues.