---
title: "Mediaproxy Module"
description: "Mediaproxy is an OpenSIPS module that is designed to allow automatic NAT traversal for the majority of existing SIP clients."
---

## Admin Guide


### Overview


Mediaproxy is an OpenSIPS 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.


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


OpenSIPS 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 OpenSIPS the IP address and port(s) for them. Then OpenSIPS 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.


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


### Dependencies


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


#### External Libraries or Applications


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


- *None*.


### Exported Parameters


#### disable (int)


Boolean flag that specifies if mediaproxy should be disabled. This
is useful when you want to use the same OpenSIPS 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".*


```opensips title="Setting the disable parameter"
...
modparam("mediaproxy", "disable", 1)
...
        
```


#### mediaproxy_socket (string)


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


*Default value is 
"/run/mediaproxy/dispatcher.sock".*


```opensips title="Setting the mediaproxy_socket parameter"
...
modparam("mediaproxy", "mediaproxy_socket", "/run/mediaproxy/dispatcher.sock")
...
        
```


#### mediaproxy_timeout (int)


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


*Default value is "500".*


```opensips title="Setting the mediaproxy_timeout parameter"
...
modparam("mediaproxy", "mediaproxy_timeout", 500)
...
        
```


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


```opensips title="Setting the signaling_ip_avp parameter"
...
modparam("mediaproxy", "signaling_ip_avp", "$avp(nat_ip)")
...
        
```


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


```opensips title="Setting the media_relay_avp parameter"
...
modparam("mediaproxy", "media_relay_avp", "$avp(media_relay)")
...
        
```


#### 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 added 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".*


```opensips title="Setting the ice_candidate parameter"
...
modparam("mediaproxy", "ice_candidate", "low-priority")
...
        
```


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

Note that if use_media_proxy() and end_media_session() functions are
being used, the AVP will not be available in the reply route unless 
you set onreply_avp_mode from the tm module to '1', and if the AVP 
is not set, the default value will be used.


*Default value is "$avp(ice_candidate)".*


```opensips title="Setting the ice_candidate_avp parameter"
...
modparam("mediaproxy", "ice_candidate_avp", "$avp(ice_candidate)")
...
        
```


### Exported Functions


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


```opensips title="Using the engage_media_proxy function"
...
if (is_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();
}
...
        
```


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


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


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


```opensips title="Using the end_media_session function"
...
if (is_method("BYE")) {
    end_media_session();
}
...
        
```
<!-- CONTRIBUTORS -->

### License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0
