rtpproxy 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


Table of Contents

1. Admin Guide
1. Overview
2. Multiple RTPProxy usage
3. Dependencies
3.1. Kamailio Modules
3.2. External Libraries or Applications
4. Parameters
4.1. rtpproxy_sock (string)
4.2. rtpproxy_disable_tout (integer)
4.3. rtpproxy_tout (integer)
4.4. rtpproxy_retr (integer)
4.5. force_socket (string)
4.6. nortpproxy_str (string)
4.7. timeout_socket (string)
5. Functions
5.1. set_rtp_proxy_set()
5.2. rtpproxy_offer([flags [, ip_address]])
5.3. rtpproxy_answer([flags [, ip_address]])
5.4. rtpproxy_destroy([flags])
5.5. unforce_rtp_proxy()
5.6. rtpproxy_manage([flags [, ip_address]])
5.7. rtpproxy_stream2uac(prompt_name, count),
5.8. rtpproxy_stream2uas(prompt_name, count)
5.9. rtpproxy_stop_stream2uac(),
5.10. start_recording()
5.11. rtpproxy_stop_stream2uas(prompt_name, count)
6. Exported Pseudo Variables
6.1. $rtpstat
7. MI Commands
7.1. nh_enable_rtpp
7.2. nh_show_rtpp
2. Frequently Asked Questions

List of Examples

1.1. Set rtpproxy_sock parameter
1.2. Set rtpproxy_disable_tout parameter
1.3. Set rtpproxy_tout parameter
1.4. Set rtpproxy_retr parameter
1.5. Set force_socket parameter
1.6. Set nortpproxy_str parameter
1.7. Set timeout_socket parameter
1.8. fix_nated_contact usage
1.9. rtpproxy_offer usage
1.10. rtpproxy_answer usage
1.11. rtpproxy_destroy usage
1.12. rtpproxy_manage usage
1.13. rtpproxy_stream2xxx usage
1.14. start_recording usage
1.15. $rtpstat-Usage
1.16. nh_enable_rtpp usage
1.17. nh_show_rtpp usage

Chapter 1. Admin Guide

1. Overview

This is a module that enables media streams to be proxied via an rtpproxy.

Known devices that get along over NATs with rtpproxy are ATAs (as clients) and Cisco Gateways (since 12.2(T)) as servers. See http://www.cisco.com/en/US/products/sw/iosswrel/ps1839/products_feature_guide09186a0080110bf9.html">

2. Multiple RTPProxy usage

Currently, the rtpproxy module can support multiple rtpproxies for balancing/distribution and control/selection purposes.

The module allows the definition of several sets of rtpproxies - load-balancing will be performed over a set and the user has the ability to choose what set should be used. The set is selected via its id - the id being defined along with the set. Refer to the rtpproxy_sock module parameter definition for syntax description.

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

The selection of the set is done from script prior using unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() functions - see the set_rtp_proxy_set() function.

For backward compatibility reasons, a set with no id take by default the id 0. Also if no set is explicitly set before unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() the 0 id set will be used.

IMPORTANT: if you use multiple sets, take care and use the same set for both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!

3. Dependencies

3.1. Kamailio Modules

The following modules must be loaded before this module:

  • tm module - (optional) if you want to have rtpproxy_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. rtpproxy_sock (string)

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

Default value is NONE (disabled).

Example 1.1. Set rtpproxy_sock parameter

...
# single rtproxy
modparam("rtpproxy", "rtpproxy_sock", "udp:localhost:12221")
# multiple rtproxies for LB
modparam("rtpproxy", "rtpproxy_sock",
	"udp:localhost:12221 udp:localhost:12222")
# multiple sets of multiple rtproxies
modparam("rtpproxy", "rtpproxy_sock",
	"1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpproxy", "rtpproxy_sock",
	"2 == udp:localhost:12225")
...

4.2. rtpproxy_disable_tout (integer)

Once RTPProxy was found unreachable and marked as disable, rtpproxy will not attempt to establish communication to RTPProxy for rtpproxy_disable_tout seconds.

Default value is 60.

Example 1.2. Set rtpproxy_disable_tout parameter

...
modparam("rtpproxy", "rtpproxy_disable_tout", 20)
...

4.3. rtpproxy_tout (integer)

Timeout value in waiting for reply from RTPProxy.

Default value is 1.

Example 1.3. Set rtpproxy_tout parameter

...
modparam("rtpproxy", "rtpproxy_tout", 2)
...

4.4. rtpproxy_retr (integer)

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

Default value is 5.

Example 1.4. Set rtpproxy_retr parameter

...
modparam("rtpproxy", "rtpproxy_retr", 2)
...

4.5. force_socket (string)

Socket to be forced in communicating to RTPProxy. It makes sense only for UDP communication. If no one specified, the OS will choose.

Default value is NULL.

Example 1.5. Set force_socket parameter

...
modparam("rtpproxy", "force_socket", "localhost:33333")
...

4.6. nortpproxy_str (string)

The parameter sets the SDP attribute used by rtpproxy to mark the packet SDP informations have already been mangled.

If empty string, no marker will be added or checked.

Note

The string must be a complete SDP line, including the EOH (\r\n).

Default value is a=nortpproxy:yes\r\n.

Example 1.6. Set nortpproxy_str parameter

...
modparam("rtpproxy", "nortpproxy_str", "a=sdpmangled:yes\r\n")
...

4.7. timeout_socket (string)

The parameter sets timeout socket, which is transmitted to the RTP-Proxy.

If it is an empty string, no timeout socket will be transmitted to the RTP-Proxy.

Default value is (nothing).

Example 1.7. Set timeout_socket parameter

...
modparam("nathelper", "timeout_socket", "xmlrpc:http://127.0.0.1:8000/RPC2")
...

5. Functions

5.1.  set_rtp_proxy_set()

Sets the Id of the rtpproxy set to be used for the next unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() command.

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

Example 1.8. fix_nated_contact usage

...
set_rtp_proxy_set("2");
rtpproxy_offer();
...

5.2.  rtpproxy_offer([flags [, ip_address]])

Rewrites SDP body to ensure that media is passed through an RTP proxy. To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK and on 200 OK when SDPs are in 200 OK and ACK.

Meaning of the parameters is as follows:

  • flags - flags to turn on some features.

    • 1 - append first Via branch to Call-ID when sending command to rtpproxy. This can be used to create one media session per branch on the rtpproxy. When sending a subsequent delete command to the rtpproxy, you can then stop just the session for a specific branch when passing the flag '1' or '2' in the unforce_rtpproxy, 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 rtpproxy gets an update command for a new branch, and then a delete command for the previous branch, which would otherwise delete the full call, breaking the subsequent lookup for the new branch. This flag is only supported by the ngcp-mediaproxy-ng rtpproxy at the moment!

    • 2 - append second Via branch to Call-ID when sending command to rtpproxy. See flag '1' for its meaning.

    • a - flags that UA from which message is received doesn't support symmetric RTP. (automatically sets the 'r' flag)

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

    • i, e - these flags specify the direction of the SIP message. These flags only make sense when rtpproxy is running in bridge mode. 'i' means internal network (LAN), 'e' means external network (WAN). 'i' corresponds to rtpproxy's first interface, 'e' corresponds to rtpproxy's second interface. You always have to specify two flags to define the incoming network and the outgoing network. For example, 'ie' should be used for SIP message received from the local interface and sent out on the external interface, and 'ei' vice versa. Other options are 'ii' and 'ee'. So, for example if a SIP requests is processed with 'ie' flags, the corresponding response must be processed with 'ie' flags.

      Note: As rtpproxy is in bridge mode per default asymmetric, you have to specify the 'w' flag for clients behind NAT! See also above notes!

    • f - instructs rtpproxy to ignore marks inserted by another rtpproxy in transit to indicate that the session is already goes through another proxy. Allows creating chain of proxies.

    • r - flags that IP address in SDP should be trusted. Without this flag, rtpproxy ignores address in the SDP and uses source address of the SIP message as media address which is passed to the RTP proxy.

    • o - flags that IP from the origin description (o=) should be also changed.

    • c - flags to change the session-level SDP connection (c=) IP if media-description also includes connection information.

    • w - flags that for the UA from which message is received, support symmetric RTP must be forced.

    • zNN - requests the RTPproxy 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 RTPproxy 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.

  • ip_address - new SDP IP address.

This function can be used from ANY_ROUTE.

Example 1.9. rtpproxy_offer usage

route {
...
    if (is_method("INVITE")) {
        if (has_sdp()) {
            if (rtpproxy_offer())
                t_on_reply("1");
        } else {
            t_on_reply("2");
        }
    }
    if (is_method("ACK") && has_sdp())
        rtpproxy_answer();
...
}

onreply_route[1]
{
...
    if (has_sdp())
        rtpproxy_answer();
...
}

onreply_route[2]
{
...
    if (has_sdp())
        rtpproxy_offer();
...
}

5.3.  rtpproxy_answer([flags [, ip_address]])

Rewrites SDP body to ensure that media is passed through an RTP proxy. To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK and on ACK when SDPs are in 200 OK and ACK.

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

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

Example 1.10. rtpproxy_answer usage

See rtpproxy_offer() function example above for example.


5.4.  rtpproxy_destroy([flags])

Tears down the RTPProxy session for the current call.

This function can be used from ANY_ROUTE.

Meaning of the parameters is as follows:

  • flags - flags to turn on some features.

    • 1 - append first Via branch to Call-ID when sending command to rtpproxy. This can be used to create one media session per branch on the rtpproxy. When sending a subsequent delete command to the rtpproxy, you can then stop just the session for a specific branch when passing the flag '1' or '2' in the unforce_rtpproxy, 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 rtpproxy gets an update command for a new branch, and then a delete command for the previous branch, which would otherwise delete the full call, breaking the subsequent lookup for the new branch. This flag is only supported by the ngcp-mediaproxy-ng rtpproxy at the moment!

    • 2 - append second Via branch to Call-ID when sending command to rtpproxy. See flag '1' for its meaning.

Example 1.11. rtpproxy_destroy usage

...
rtpproxy_destroy();
...

5.5.  unforce_rtp_proxy()

Same as rtpproxy_destroy().

5.6.  rtpproxy_manage([flags [, ip_address]])

Manage the RTPProxy session - it combines the functionality of rtpproxy_offer(), rtpproxy_answer() and unfroce_rtpproxy(), detecting internally based on message type and metod which one to execute.

It can take same kind of parameters as rtpproxy_offer().

Functinality:

  • if INVITE with SDP, then do rtpproxy offer

  • if INVITE with SDP, when tm is loaded, mark transaction with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for rtpproxy answer

  • if ACK with SDP, then do rtpproxy answer

  • if BYE or CANCEL, or called within a failure_route[], then do unforce rtpproxy

  • if reply to INVITE with code >= 300 do unfrce rtp proxy

  • if reply with SDP to INVITE having code 1xx and 2xx, then do rtpproxy answer if the request had SDP or tm is not loaded, otherwise do rtpproxy offer

This function can be used from ANY_ROUTE.

Example 1.12. rtpproxy_manage usage

...
rtpproxy_manage();
...

5.7.  rtpproxy_stream2uac(prompt_name, count),

Instruct the RTPproxy to stream prompt/announcement pre-encoded with the makeann command from the RTPproxy distribution. The uac/uas suffix selects who will hear the announcement relatively to the current transaction - UAC or UAS. For example invoking the rtpproxy_stream2uac in the request processing block on ACK transaction will play the prompt to the UA that has generated original INVITE and ACK while rtpproxy_stop_stream2uas on 183 in reply processing block will play the prompt to the UA that has generated 183.

Apart from generating announcements, another possible application of this function is implementing music on hold (MOH) functionality. When count is -1, the streaming will be in loop indefinitely until the appropriate rtpproxy_stop_stream2xxx is issued.

In order to work correctly, functions require that the session in the RTPproxy already exists. Also those functions don't alted SDP, so that they are not substitute for calling rtpproxy_offer or rtpproxy_answer.

This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

Meaning of the parameters is as follows:

  • prompt_name - name of the prompt to stream. Should be either absolute pathname or pathname relative to the directory where RTPproxy runs.

  • count - number of times the prompt should be repeated. The value of -1 means that it will be streaming in loop indefinitely, until appropriate rtpproxy_stop_stream2xxx is issued.

Example 1.13. rtpproxy_stream2xxx usage

...
    if (is_method("INVITE")) {
        rtpproxy_offer();
        if (detect_hold()) {
            rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
        } else {
            rtpproxy_stop_stream2uas();
        };
    };
...

5.8.  rtpproxy_stream2uas(prompt_name, count)

See function rtpproxy_stream2uac(prompt_name, count).

5.9.  rtpproxy_stop_stream2uac(),

Stop streaming of announcement/prompt/MOH started previously by the respective rtpproxy_stream2xxx. The uac/uas suffix selects whose announcement relatively to tha current transaction should be stopped - UAC or UAS.

These functions can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

5.10.  start_recording()

This command will send a signal to the RTP-Proxy to record the RTP stream on the RTP-Proxy.

This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.

Example 1.14. start_recording usage

...
start_recording();
...

5.11.  rtpproxy_stop_stream2uas(prompt_name, count)

See function rtpproxy_stop_stream2uac(prompt_name, count).

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

Example 1.15. $rtpstat-Usage

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

7. MI Commands

7.1. nh_enable_rtpp

Enables a rtp proxy if parameter value is greater than 0. Disables it if a zero value is given.

The first parameter is the rtp proxy url (exactly as defined in the config file).

The second parameter value must be a number in decimal.

NOTE: if a rtpproxy is defined multiple times (in the same or diferente sete), all its instances will be enables/disabled.

Example 1.16.  nh_enable_rtpp usage

...
$ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
...

7.2. nh_show_rtpp

Displays all the rtp proxies and their information: set and status (disabled or not, weight and recheck_ticks).

No parameter.

Example 1.17.  nh_show_rtpp usage

...
$ kamctl fifo nh_show_rtpp
...

Chapter 2. Frequently Asked Questions

2.1. What happend with “rtpproxy_disable” parameter?
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.

What happend with rtpproxy_disable parameter?

It was removed as it became obsolete - now rtpproxy_sock can take empty value to disable the rtpproxy functionality.

2.2.

Where can I find more about Kamailio?

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

2.3.

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 .

2.4.

How can I report a bug?

Please follow the guidelines provided at: http://sip-router.org/tracker.