kamailio/modules_k/rtpproxy

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

   Copyright © 2003-2008 Sippy Software, Inc.

   Copyright © 2005 voice-system.ro

   Copyright © 2009 TuTPro Inc.

   Copyright © 2010 VoIPEmbedded Inc.
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

   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. Exported 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)
              4.8. timeout_socket_type (int)

        5. Exported Functions

              5.1. set_rtp_proxy_set()
              5.2. force_rtp_proxy([flags [, ip_address]])
              5.3. rtpproxy_offer([flags [, ip_address]])
              5.4. rtpproxy_answer([flags [, ip_address]])
              5.5. unforce_rtp_proxy()
              5.6. rtpproxy_stream2uac(prompt_name, count),
                      rtpproxy_stream2uas(prompt_name, count)

              5.7. rtpproxy_stop_stream2uac(), rtpproxy_stop_stream2uas()
              5.8. start_recording()

        6. Exported Pseudo Variables

              6.1. $rtpstart

        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. Set timeout_socket_type parameter
   1.9. fix_nated_contact usage
   1.10. force_rtp_proxy usage
   1.11. rtpproxy_offer usage
   1.12.
   1.13. unforce_rtp_proxy usage
   1.14. rtpproxy_stream2xxx usage
   1.15. start_recording usage
   1.16. $rtpstat-Usage
   1.17. nh_enable_rtpp usage
   1.18. nh_show_rtpp usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Multiple RTPProxy usage
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Exported 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)
        4.8. timeout_socket_type (int)

   5. Exported Functions

        5.1. set_rtp_proxy_set()
        5.2. force_rtp_proxy([flags [, ip_address]])
        5.3. rtpproxy_offer([flags [, ip_address]])
        5.4. rtpproxy_answer([flags [, ip_address]])
        5.5. unforce_rtp_proxy()
        5.6. rtpproxy_stream2uac(prompt_name, count),
                rtpproxy_stream2uas(prompt_name, count)

        5.7. rtpproxy_stop_stream2uac(), rtpproxy_stop_stream2uas()
        5.8. start_recording()

   6. Exported Pseudo Variables

        6.1. $rtpstart

   7. MI Commands

        7.1. nh_enable_rtpp
        7.2. nh_show_rtpp

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
   [un]force_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
   [un]force_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 force_ and unforce_rtpproxy()!!

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:
     * None

3.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

4. Exported 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)
   4.8. timeout_socket_type (int)

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

   Example 1.7. Set timeout_socket parameter
...
modparam("nathelper", "timeout_socket", "http://127.0.0.1:8000/RPC2")
...

4.8. timeout_socket_type (int)

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

   If it is not set, type 1 (Kamailio XML-RPC-Socket) is transmitted to
   the RTP-Proxy.

   Default value is “1”.

   Example 1.8. Set timeout_socket_type parameter
...
modparam("nathelper", "timeout_socket_type", 42)
...

   The only supported Type on the RTP-Proxy is currently “1” or “0” which
   is the default socket-type of the RTP-Proxy which is not compatible to
   Kamailio.

5. Exported Functions

   5.1. set_rtp_proxy_set()
   5.2. force_rtp_proxy([flags [, ip_address]])
   5.3. rtpproxy_offer([flags [, ip_address]])
   5.4. rtpproxy_answer([flags [, ip_address]])
   5.5. unforce_rtp_proxy()
   5.6. rtpproxy_stream2uac(prompt_name, count),
          rtpproxy_stream2uas(prompt_name, count)

   5.7. rtpproxy_stop_stream2uac(), rtpproxy_stop_stream2uas()
   5.8. start_recording()

5.1.  set_rtp_proxy_set()

   Sets the Id of the rtpproxy set to be used for the next
   [un]force_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() command.

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

   Example 1.9. fix_nated_contact usage
...
set_rtp_proxy_set("2");
force_rtp_proxy();
...

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

   Rewrites SDP body to ensure that media is passed through an RTP proxy.
   It can have optional parameters to force additional features. If
   ip_address is provided, it will be used to replace the one in SDP.

   Note: Behavior of rtpproxy depends on the mode in which rtpproxy is
   running: If rtpproxy listens only to a single interface, then rtpproxy
   is default symmetric (port), if rtpproxy listens to two interfaces (so
   called bridge-mode), then rtpproxy is default asymmetric (port).

   Note: Regardless of symmetric/asymmetric rtpproxy mode, per default
   rtpproxy accepts incoming RTP packets only from the same IP address as
   the SIP signaling was received. Thus, if a SIP client uses different IP
   for media and SIP (often seen with SBCs), the 'r' flag must be
   specified.

   The function is considered depreciated and provided for the
   compatibility purposes. Use rtpproxy_offer() or rtpproxy_answer()
   instead.

   Meaning of the parameters is as follows:
     * flags - flags to turn on some features.
          + 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 (reply in
            non-swap or ACK in swap mode).
          + 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.
          + s - flags to swap creation with confirmation between requests
            and replies. By default, a request creates the RTP session and
            a reply confirms it. If swapped, a reply will create the RTP
            session and a request will confirm it. The flag is considered
            depreciated and provided for the compatibility purposes. Use
            rtpproxy_offer() or rtpproxy_answer() instead.
          + 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.

   It returns value -2 when a rtp proxy has already mangled the packet,
   making possible to determine in the script if an rtpproxy is in the
   audio path.

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

   Example 1.10. force_rtp_proxy usage
...
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy();};
if (src_ip=1.2.3.4) {force_rtp_proxy("i");};
if (search("User-Agent: Cisco ATA.*") {force_rtp_proxy("","1.2.3.4");};
...

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

   Rewrites SDP body to ensure that media is passed through an RTP proxy.
   Equivalent of force_rtp_proxy() function 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.

   See force_rtp_proxy() 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.11. 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.4.  rtpproxy_answer([flags [, ip_address]])

   Rewrites SDP body to ensure that media is passed through an RTP proxy.
   Equivalent of force_rtp_proxy() function 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 force_rtp_proxy() 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.12.

   See rtpproxy_offer() function example above for example.

5.5.  unforce_rtp_proxy()

   Tears down the RTPProxy session for the current call.

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

   Example 1.13. unforce_rtp_proxy usage
...
unforce_rtp_proxy();
...

5.6.  rtpproxy_stream2uac(prompt_name, count),
rtpproxy_stream2uas(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, rtpproxy_answer or
   force_rtp_proxy.

   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.14. 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.7.  rtpproxy_stop_stream2uac(), rtpproxy_stop_stream2uas()

   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.8.  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.15. start_recording usage
...
start_recording();
...

6. Exported Pseudo Variables

   6.1. $rtpstart

6.1. $rtpstart

   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.16. $rtpstat-Usage
...
    append_hf("X-RTP-Statistics: $rtpstat\r\n");
...

7. MI Commands

   7.1. nh_enable_rtpp
   7.2. nh_show_rtpp

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.17.  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.18.  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:
         * User Mailing List -
           http://lists.kamailio.org/cgi-bin/mailman/listinfo/users
         * Developer Mailing List -
           http://lists.kamailio.org/cgi-bin/mailman/listinfo/devel

       E-mails regarding any stable Kamailio release should be sent to
       <users@lists.kamailio.org> and e-mails regarding development versions
       should be sent to <devel@lists.kamailio.org>.

       If you want to keep the mail private, send it to
       <team@lists.kamailio.org>.

   2.4.

       How can I report a bug?

       Please follow the guidelines provided at:
       http://sourceforge.net/tracker/?group_id=139143.