mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
367 lines
13 KiB
367 lines
13 KiB
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();
|
|
}
|
|
...
|