kamailio/modules/mediaproxy/README

Mediaproxy Module

Dan Pascu

   <dan@ag-projects.com>

Edited by

Dan Pascu

   <dan@ag-projects.com>

   Copyright © 2004 Dan Pascu
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Principle of operation
        3. Features
        4. Dependencies

              4.1. SIP Router Modules
              4.2. External Libraries or Applications

        5. Exported parameters

              5.1. disable (int)
              5.2. mediaproxy_socket (string)
              5.3. mediaproxy_timeout (int)
              5.4. signaling_ip_avp (string)
              5.5. media_relay_avp (string)
              5.6. ice_candidate (string)
              5.7. ice_candidate_avp (string)

        6. Functions

              6.1. engage_media_proxy()
              6.2. use_media_proxy()
              6.3. end_media_session()

   List of Examples

   1.1. Setting the disable parameter
   1.2. Setting the mediaproxy_socket parameter
   1.3. Setting the mediaproxy_timeout parameter
   1.4. Setting the signaling_ip_avp parameter
   1.5. Setting the media_relay_avp parameter
   1.6. Setting the ice_candidate parameter
   1.7. Setting the ice_candidate_avp parameter
   1.8. Using the engage_media_proxy function
   1.9. Using the use_media_proxy function
   1.10. Using the end_media_session function

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Principle of operation
   3. Features
   4. Dependencies

        4.1. SIP Router Modules
        4.2. External Libraries or Applications

   5. Exported parameters

        5.1. disable (int)
        5.2. mediaproxy_socket (string)
        5.3. mediaproxy_timeout (int)
        5.4. signaling_ip_avp (string)
        5.5. media_relay_avp (string)
        5.6. ice_candidate (string)
        5.7. ice_candidate_avp (string)

   6. Functions

        6.1. engage_media_proxy()
        6.2. use_media_proxy()
        6.3. end_media_session()

1. Overview

   Mediaproxy is an SIP Router module that is designed to allow automatic
   NAT traversal for the majority of existing SIP clients. This means that
   there will be no need to configure anything in particular on the NAT
   box to allow these clients to work behind NAT when using the mediaproxy
   module.

2. Principle of operation

   This NAT traversal solution operates by placing a media relay in the
   middle between 2 SIP user-agents. It mangles the SDP messages for both
   of them in a way that will make the parties talk with the relay while
   they think they talk directly with each other.

   Mediaproxy consists of 2 components:
     * The SIP Router mediaproxy module
     * An external application called MediaProxy which employs a
       dispatcher and multiple distributed media relays. This is available
       from http://ag-projects.com/MediaProxy.html (version 2.0.0 or newer
       is required by this module).

   The mediaproxy dispatcher runs on the same machine as SIP Router and
   its purpose is to select a media relay for a call. The media relay may
   run on the same machine as the dispatcher or on multiple remote hosts
   and its purpose is to forward the streams between the calling parties.
   To find out more about the architecture of MediaProxy please read the
   documentation that comes with it.

   To be able to act as a relay between the 2 user agents, the machine(s)
   running the module/proxy server must have a public IP address.

   SIP Router will ask the media relay to allocate as many ports as there
   are media streams in the SDP offer and answer. The media relay will
   send back to SIP Router the IP address and port(s) for them. Then SIP
   Router will replace the original contact IP and RTP ports from the SDP
   messages with the ones provided by the media relay. By doing this, both
   user agents will try to contact the media relay instead of
   communicating directly with each other. Once the user agents contact
   the media relay, it will record the addresses they came from and will
   know where to forward packets received from the other endpoint. This is
   needed because the address/port the NAT box will allocate for the media
   streams is not known before they actually leave the NAT box. However
   the address of the media relay is always known (being a public IP) so
   the 2 endpoints know where to connect. After they do so, the relay
   learns their addresses and can forward packets between them.

   The SIP clients that will work transparently behind NAT when using
   mediaproxy, are the so-called symmetric clients. The symmetric clients
   have the particularity that use the same port to send and receive data.
   This must be true for both signaling and media for a client to work
   transparently with mediaproxy without any configuration on the NAT box.

3. Features

     * make symmetric clients work behind NAT transparently, with no
       configuration needed on the client's NAT box.
     * have the ability to distribute RTP traffic on multiple media relays
       running on multiple hosts.

4. Dependencies

   4.1. SIP Router Modules
   4.2. External Libraries or Applications

4.1. SIP Router Modules

   The following modules must be loaded before this module:
     * dialog module - if engage_media_proxy is used (see below the
       description of engage_media_proxy).

4.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running SIP Router with this module loaded:
     * Mediaproxy version 2.4.2 or higher (but not necessarily on the same
       host as SIP Router).

5. Exported parameters

   5.1. disable (int)
   5.2. mediaproxy_socket (string)
   5.3. mediaproxy_timeout (int)
   5.4. signaling_ip_avp (string)
   5.5. media_relay_avp (string)
   5.6. ice_candidate (string)
   5.7. ice_candidate_avp (string)

5.1. disable (int)

   Boolean flag that specifies if mediaproxy should be disabled. This is
   useful when you want to use the same openser configuration in two
   different context, one using mediaproxy, the other not. In the case
   mediaproxy is disabled, calls to its functions will have no effect,
   allowing you to use the same configuration without changes.

   Default value is “0”.

   Example 1.1. Setting the disable parameter
...
modparam("mediaproxy", "disable", 1)
...

5.2. mediaproxy_socket (string)

   It is the path to the filesystem socket where the mediaproxy dispatcher
   listens for commands from the module.

   Default value is “/var/run/mediaproxy/dispatcher.sock”.

   Example 1.2. Setting the mediaproxy_socket parameter
...
modparam("mediaproxy", "mediaproxy_socket", "/var/run/mediaproxy/dispatcher.sock
")
...

5.3. mediaproxy_timeout (int)

   How much time (in milliseconds) to wait for an answer from the
   mediaproxy dispatcher.

   Default value is “500”.

   Example 1.3. Setting the mediaproxy_timeout parameter
...
modparam("mediaproxy", "mediaproxy_timeout", 500)
...

5.4. signaling_ip_avp (string)

   Specification of the AVP which holds the IP address from where the SIP
   signaling originated. If this AVP is set it will be used to get the
   signaling IP address, else the source IP address from where the SIP
   message was received will be used. This AVP is meant to be used in
   cases where there are more than one proxy in the call setup path and
   the proxy that actually starts mediaproxy doesn't receive the SIP
   messages directly from the UA and it cannot determine the NAT IP
   address from where the signaling originated. In such a case attaching a
   SIP header at the first proxy and then copying that header's value into
   the signaling_ip_avp on the proxy that starts mediaproxy will allow it
   to get the correct NAT IP address from where the SIP signaling
   originated.

   Default value is “$avp(signaling_ip)”.

   Example 1.4. Setting the signaling_ip_avp parameter
...
modparam("mediaproxy", "signaling_ip_avp", "$avp(nat_ip)")
...

5.5. media_relay_avp (string)

   Specification of the AVP which holds an optional application defined
   media relay IP address of a particular media relay that is preferred to
   be used for the current call. If an IP address is written to this AVP
   before calling use_media_proxy(), it will be preferred by the
   dispatcher over the normal selection algorithm.

   Default value is “$avp(media_relay)”.

   Example 1.5. Setting the media_relay_avp parameter
...
modparam("mediaproxy", "media_relay_avp", "$avp(media_relay)")
...

5.6. ice_candidate (string)

   Indicates the type of ICE candidate that will be added to the SDP. It
   can take 3 values: 'none', 'low-priority' or 'high-priority'. If 'none'
   is selected no candidate will be adeed to the SDP. If 'low-priority' is
   selected then a low priority candidate will be added and if
   'high-priority' is selected a high priority one.

   Default value is “none”.

   Example 1.6. Setting the ice_candidate parameter
...
modparam("mediaproxy", "ice_candidate", "low-priority")
...

5.7. ice_candidate_avp (string)

   Specification of the AVP which holds the ICE candidate that will be
   inserted in the SDP. The value specified in this AVP will override the
   value in ice_candidate module parameter. If the AVP is not set, the
   default value will be used.

   Default value is “$avp(ice_candidate)”.

   Example 1.7. Setting the ice_candidate_avp parameter
...
modparam("mediaproxy", "ice_candidate_avp", "$avp(ice_candidate)")
...

6. Functions

   6.1. engage_media_proxy()
   6.2. use_media_proxy()
   6.3. end_media_session()

6.1. engage_media_proxy()

   Trigger the use of MediaProxy for all the dialog requests and replies
   that have an SDP body. This needs to be called only once for the first
   INVITE in a dialog. After that it will use the dialog module to trace
   the dialog and automatically call use_media_proxy() on every request
   and reply that belongs to the dialog and has an SDP body. When the
   dialog ends it will also call automatically end_media_session(). All of
   these are called internally on dialog callbacks, so for this function
   to work, the dialog module must be loaded and configured.

   This function is an advanced mechanism to use a media relay without
   having to manually call a function on each message that belongs to the
   dialog. However this method is less flexible, because once things were
   set in motion by calling this function on the first INVITE, it cannot
   be stopped, not even by calling end_media_session(). It will only stop
   when the dialog ends. Until then it will modify the SDP content of
   every in-dialog message to make it use a media relay. If one needs more
   control over the process, like starting to use mediaproxy only later in
   the failure route, or stopping to use mediaproxy in the failure route,
   then the use_media_proxy and end_media_session functions should be
   used, and manually called as appropriate. Using this function should
   NOT be mixed with either of use_media_proxy() or end_media_session().

   This function can be used from REQUEST_ROUTE.

   Example 1.8. Using the engage_media_proxy function
...
if (method==INVITE && !has_totag()) {
    # We can also use a specific media relay if we need to
    #$avp(media_relay) = "1.2.3.4";
    engage_media_proxy();
}
...

6.2. use_media_proxy()

   Will make a call to the dispatcher and replace the IPs and ports in the
   SDP body with the ones returned by the media relay for each supported
   media stream in the SDP body. This will force the media streams to be
   routed through the media relay. If a mix of supported and unsupported
   streams are present in the SDP, only the supported streams will be
   modified, while the unsupported streams will be left alone.

   This function should NOT be mixed with engage_media_proxy().

   This function has the following return codes:

     * +1 - successfully modified message (true value)
     * -1 - error in processing message (false value)
     * -2 - missing SDP body, nothing to process (false value)

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

   Example 1.9. Using the use_media_proxy function
...
if (method==INVITE) {
    # We can also use a specific media relay if we need to
    #$avp(media_relay) = "1.2.3.4";
    use_media_proxy();
}
...

6.3. end_media_session()

   Will call on the dispatcher to inform the media relay to end the media
   session. This is done when a call ends, to instruct the media relay to
   release the resources allocated to that call as well as to save logging
   information about the media session. Called on BYE, CANCEL or failures.

   This function should NOT be mixed with engage_media_proxy().

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

   Example 1.10. Using the end_media_session function
...
if (method==BYE) {
    end_media_session();
}
...