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

   Copyright © 2003-2008 Sippy Software, Inc.

   Copyright © 2005 Voice Sistem SRL

   Copyright © 2009-2014 TuTPro Inc.

   Copyright © 2010 VoIPEmbedded Inc.

   Copyright © 2013-2014 Sipwise GmbH
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Multiple RTP proxy usage
        1.3. Dependencies

              1.3.1. OpenSIPS Modules
              1.3.2. External Libraries or Applications

        1.4. Parameters

              1.4.1. rtpengine_sock (string)
              1.4.2. rtpengine_disable_tout (integer)
              1.4.3. rtpengine_tout (integer)
              1.4.4. rtpengine_retr (integer)
              1.4.5. extra_id_pv (string)
              1.4.6. setid_avp (string)

        1.5. Functions

              1.5.1. rtpengine_use_set(setid)
              1.5.2. rtpengine_offer([flags])
              1.5.3. rtpengine_answer([flags])
              1.5.4. rtpengine_delete([flags])
              1.5.5. rtpengine_manage([flags])
              1.5.6. rtpengine_start_recording()

        1.6. Exported Pseudo Variables

              1.6.1. $rtpstat

        1.7. MI Commands

              1.7.1. rtpengine_enable
              1.7.2. rtpengine_show

   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 parameter
   1.4. Set rtpengine_retr parameter
   1.5. Set extra_id_pv parameter
   1.6. Set setid_avp parameter
   1.7. rtpengine_use_set usage
   1.8. rtpengine_offer usage
   1.9. rtpengine_answer usage
   1.10. rtpengine_delete usage
   1.11. rtpengine_manage usage
   1.12. rtpengine_start_recording usage
   1.13. $rtpstat Usage
   1.14. rtpengine_enable usage
   1.15. rtpengine_show usage

Chapter 1. Admin Guide

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

1.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 rtpengines.
   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 rtpengine_use_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.

1.3. Dependencies

1.3.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * tm module - (optional) if you want to have
       rtpengine_manage() fully functional

1.3.2. External Libraries or Applications

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

1.4. Parameters

1.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
modparam("rtpengine", "rtpengine_sock",
        "udp:localhost:12221 udp:localhost:12222")
# multiple sets of multiple rtproxies
modparam("rtpengine", "rtpengine_sock",
        "1 == udp:localhost:12221 udp:localhost:12222")
modparam("rtpengine", "rtpengine_sock",
        "2 == udp:localhost:12225")
...

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

1.4.3. rtpengine_tout (integer)

   Timeout value in waiting for reply from RTP proxy.

   Default value is “1”.

   Example 1.3. Set rtpengine_tout parameter
...
modparam("rtpengine", "rtpengine_tout", 2)
...

1.4.4. rtpengine_retr (integer)

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

   Default value is “5”.

   Example 1.4. Set rtpengine_retr parameter
...
modparam("rtpengine", "rtpengine_retr", 2)
...

1.4.5. 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.5. Set extra_id_pv parameter
...
modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
...

1.4.6. 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.6. Set setid_avp parameter
...
modparam("rtpengine", "setid_avp", "$avp(setid)")
...

1.5. Functions

1.5.1.  rtpengine_use_set(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.

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

   Example 1.7. rtpengine_use_set usage
...
rtpengine_use_set("2");
rtpengine_offer();
...

1.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 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.
       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. (automatically
            sets the 'r' flag)
          + 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.
          + internal, external - these flags specify the direction
            of the SIP message. These flags only make sense when
            the RTP proxy is running in bridge mode. “internal”
            corresponds to the proxy's first interface, “external”
            corresponds to the RTP proxy's second interface. You
            always have to specify two flags to define the
            incoming network and the outgoing network. For
            example, “internal external” should be used for SIP
            message received from the local interface and sent out
            on the external interface, and “external internal”
            vice versa. Other options are “internal internal” and
            “external external”. So, for example if a SIP requests
            is processed with “internal external” flags, the
            corresponding response must be processed with
            “internal external” flags.
          + 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. Without this flag, the RTP proxy ignores
            address in the SDP and uses source address of the SIP
            message as media address which is passed to the RTP
            proxy.
          + 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.
          + 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; “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 an 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.

   This function can be used from ANY_ROUTE.

   Example 1.8. rtpengine_offer usage
route {
...
    if (is_method("INVITE")) {
        if (has_body("application/sdp")) {
            if (rtpengine_offer())
                t_on_reply("1");
        } else {
            t_on_reply("2");
        }
    }
    if (is_method("ACK") && has_body("application/sdp"))
        rtpengine_answer();
...
}

onreply_route[1]
{
...
    if (has_body("application/sdp"))
        rtpengine_answer();
...
}

onreply_route[2]
{
...
    if (has_body("application/sdp"))
        rtpengine_offer();
...
}

1.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 SDPs are in
   INVITE and 200 OK and on ACK when SDPs are in 200 OK and ACK.

   See rtpengine_offer() 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.9. rtpengine_answer usage

   See rtpengine_offer() function example above for example.

1.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.10. rtpengine_delete usage
...
rtpengine_delete();
...

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

   Functionality:
     * 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
       do rtpengine_delete()
     * 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.11. rtpengine_manage usage
...
rtpengine_manage();
...

1.5.6.  rtpengine_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.12. rtpengine_start_recording usage
...
rtpengine_start_recording();
...

1.6. Exported Pseudo Variables

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

1.7. MI Commands

1.7.1. rtpengine_enable

   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 RTP proxy is defined multiple times (in the same or
   diferente sete), all of its instances will be enables/disabled.

   Example 1.14.  rtpengine_enable usage
...
$ opensipsctl fifo rtpengine_enable udp:192.168.2.133:8081 0
...

1.7.2. rtpengine_show

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

   No parameter.

   Example 1.15.  rtpengine_show usage
...
$ opensipsctl fifo rtpengine_show
...

Chapter 2. Frequently Asked Questions

   2.1.

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

   2.2.

   Where can I find more about OpenSIPS?

   Take a look at http://www.opensips.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.opensips.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://lists.opensips.org/cgi-bin/mailman/listinfo/devel

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

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

   2.4.

   How can I report a bug?

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