kamailio/modules/rtpengine/README

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 (c) 2003-2008 Sippy Software, Inc.

   Copyright (c) 2005 Voice Sistem SRL

   Copyright (c) 2009-2014 TuTPro Inc.

   Copyright (c) 2010 VoIPEmbedded Inc.

   Copyright (c) 2013-2014 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 (integer)
              4.4. rtpengine_retr (integer)
              4.5. extra_id_pv (string)
              4.6. setid_avp (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
              7.2. nh_show_rtpp

   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. set_rtpengine_set usage
   1.8. rtpengine_offer usage
   1.9. rtpengine_answer usage
   1.10. rtpengine_delete usage
   1.11. rtpengine_manage usage
   1.12. start_recording usage
   1.13. $rtpstat Usage
   1.14. nh_enable_rtpp usage
   1.15. nh_show_rtpp usage

Chapter 1. Admin Guide

   Table of Contents

   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 (integer)
        4.4. rtpengine_retr (integer)
        4.5. extra_id_pv (string)
        4.6. setid_avp (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
        7.2. nh_show_rtpp

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.

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:
     * 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)
   4.2. rtpengine_disable_tout (integer)
   4.3. rtpengine_tout (integer)
   4.4. rtpengine_retr (integer)
   4.5. extra_id_pv (string)
   4.6. setid_avp (string)

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

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

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

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

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

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

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.7. set_rtpengine_set usage
...
set_rtpengine_set("2");
rtpengine_offer();
...

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

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

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.

   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.

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

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

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

6. Exported Pseudo Variables

   6.1. $rtpstat

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

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

   Example 1.14.  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.15.  nh_show_rtpp usage
...
$ kamctl fifo nh_show_rtpp
...

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?

   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-session-co
nnection 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 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.sip-router.org/cgi-bin/mailman/listinfo/sr-users
     * Developer Mailing List -
       http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev

   E-mails regarding any stable Kamailio release should be sent to
   <[email protected]> and e-mails regarding development
   versions should be sent to <[email protected]>.

   If you want to keep the mail private, send it to
   <[email protected]>.

   2.4.

   How can I report a bug?

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