Mediaproxy Module
Dan Pascu
<dan@ag-projects.com>
Edited by
Dan Pascu
<dan@ag-projects.com>
Copyright � 2004 Dan Pascu
Revision History
Revision $Revision$ $Date: 2008-05-30 17:58:10 +0200
(Fr, 30 Mai 2008) $
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Principle of operation
1.3. Features
1.4. Dependencies
1.4.1. Kamailio Modules
1.4.2. External Libraries or Applications
1.5. Exported parameters
1.5.1. disable (int)
1.5.2. mediaproxy_socket (string)
1.5.3. mediaproxy_timeout (int)
1.5.4. signaling_ip_avp (string)
1.5.5. media_relay_avp (string)
1.6. Exported Functions
1.6.1. engage_media_proxy()
1.6.2. use_media_proxy()
1.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. Using the engage_media_proxy function
1.7. Using the use_media_proxy function
1.8. Using the end_media_session function
Chapter 1. Admin Guide
1.1. Overview
Mediaproxy is an Kamailio 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.
1.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 Kamailio 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 Kamailio
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.
Kamailio 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 Kamailio the IP address and port(s) for
them. Then Kamailio 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.
1.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.
1.4. Dependencies
1.4.1. Kamailio 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).
1.4.2. External Libraries or Applications
The following libraries or applications must be installed
before running Kamailio with this module loaded:
* None.
1.5. Exported parameters
1.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)
...
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/dispatc
her.sock")
...
1.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)
...
1.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(s:signaling_ip)".
Example 1.4. Setting the signaling_ip_avp parameter
...
modparam("mediaproxy", "signaling_ip_avp", "$avp(s:nat_ip)")
...
1.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(s:media_relay)".
Example 1.5. Setting the media_relay_avp parameter
...
modparam("mediaproxy", "media_relay_avp", "$avp(s:media_relay)")
...
1.6. Exported Functions
1.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.6. Using the engage_media_proxy function
...
if (method==INVITE && !has_totag()) {
# We can also use a specific media relay if we need to
#$avp(s:media_relay) = "1.2.3.4";
engage_media_proxy();
}
...
1.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.7. Using the use_media_proxy function
...
if (method==INVITE) {
# We can also use a specific media relay if we need to
#$avp(s:media_relay) = "1.2.3.4";
use_media_proxy();
}
...
1.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.8. Using the end_media_session function
...
if (method==BYE) {
end_media_session();
}
...