Mediaproxy

MediaProxy is an Open Source far-end NAT traversal solution for OpenSER. By using Traversal Using Relay NAT protocol (TURN), MediaProxy behaves as a media relay allowing audio and video traffic (RTP streams) to bypass broadband routers without setting up devices at customer premises.

Mediaproxy 1.1

Requirements

Mediaproxy 2.0

MediaProxy 2.0 is the second generation media relay application which is based on a completely new design that allows for major improvements in areas such as scalability (an order of magnitude more scalable than previous version) and security (communication between relay and dispatcher is encrypted).

Requirements

To run the software, you will need a server running the Linux Operating System using a kernel version 2.6.18 or higher that has been compiled with connection tracking support (conntrack). Because of this dependency on Linux, other operating systems are not supported. This dependency only applies to the media relay component. The dispatcher component which runs on the same host as OpenSIPs, can run on any platform that has a python interpreter and supports the twisted framework.

Communication between the dispatcher and the relays uses TLS encryption and requires a set of X509 certificates to work. For more information about this please read tls/README which contains information about the sample certificates that are included as well as information about how to generate your own.

MediaProxy is meant to be used together with OpenSIPs' mediaproxy module.

This version of MediaProxy (2.0 or higher) cannot be used in combination with any version of OpenSER older than 1.4 or any components of MediaProxy older than 2.0. You must completely upgrade any previous installation of OpenSER to OpenSIPs and MediaProxy to these new versions.

No STUN or TURN support are required in the clients.

The SIP User Agents must work symmetrically (that is to send and receive data on the same port for each stream), which is documented in RFC 4961.

To display the history of the media streams CDRTool 6.5 or higher is required.

Some features that were present in the previous version have been removed:

* Support for specifying media relays per domain has been discontinued
* Support for DNS records has been discontinued
* Support for asymmetric clients has been discontinued
* Support for other operating systems than Linux has been discontinued (only for the media relay, as the dispatcher has no such limitation)

In order to build and install, MediaProxy has the following requirements:

- Linux (at least 2.6.18) with the following features compiled in: - netfilter support - connection tracking support - connection tracking netlink interface - connection tracking event notification API - netfilter "NOTRACK" target support - netfilter "CONNMARK" target support - netfilter "connmark" match support - IPv4 connection tracking support - IP tables support - IP tables Full NAT support Distribution provided kernel images should normally provide of all these features as modules. The Debian kernel images have all these features available and can be used out of the box. - libnetfilter-conntrack (at least version 0.0.89) Most of the Linux distributions separate a library package into runtime and development packages. To build MediaProxy, the development version is needed (it usually has a -dev suffix in the package name). - Python (at least 2.4) http://python.org - Twisted framework (at least 2.5.0 with epollreactor support) http://twistedmatrix.com - python-zopeinterface (this is also a requirement for twisted) http://zope.org/Products/ZopeInterface - python-application (at least 1.0.9) http://pypi.python.org/pypi/python-application - GNU-TLS http://www.gnu.org/software/gnutls - python-gnutls http://pypi.python.org/pypi/python-gnutls - python-cjson http://pypi.python.org/pypi/python-cjson

For the database accounting module:

- SQLObject http://sqlobject.org

For the RADIUS accounting module:

- pyrad http://www.wiggy.net/code/pyrad/

Architecture

MediaProxy consists of a dispatcher and one or more media relays.

The dispatcher component always runs on the same host as OpenSIPS andcommunicates with its mediaproxy module through a UNIX domain socket. Therelay(s) connect to the dispatcher using TLS. This relay component may be onthe same or on a different host as OpenSIPS. There may be several relays forthe dispatcher to choose from and a relay may service more than onedispatcher.

When OpenSIPS requests that a call be relayed, the dispatcher will forwardthis request to one of its connected relays, along with some data from theSDP. The relay will allocate a set of UDP ports for this session, dependingon the number of proposed streams. It will inform the dispatcher which portsit has allocated so that it may in turn notify the mediaproxy module ofOpenSIPS, which will replace the relevant parts of the SDP.

The same is done for any SIP messages from the callee, thus all the mediastreams will be sent through the relay. When the session between caller andcallee has finished, either through a SIP BYE or because the media is nolonger flowing and has timed out, the relay will send session information tothe dispatcher, which can store this information using one or more accountingmodules.

The session information may also be queried using a management interface onthe dispatcher.

All of this is illustrated in the following diagram:

+---+ +---+
| +---------------------+ |
| | SIP Proxy | |
| | +----------+ | SIP |
|<--+->| OpenSIPS |<------+------------------->|
| | +----------+ | |
| | ^ | |
| | | UNIX socket | |
C | | v | | C
A | | +------------+ | +------------+ | A
L | | | Dispatcher |<-----+-->| Management | | L
L | | +------------+ TCP | | client | | L
E | | ^ /TLS | +------------+ | E
R | | | | | E
| +---------+-----------+ |
| | |
| | TLS |
| v |
| +-------------+ UDP |
|<---->| Relay |<----------------------->|
| +-------------+ RTP / RTCP |
+---+ +---+

Please note that the accounting modules are not shown.

Database accounting

The database backend logs all the information related to the media streams thatwere created/closed during the whole session. This information is stored as aJSON encoded string in a BLOB column in the database, along with the call_id,from_tag, to_tag and start_time columns that can be used to retrieve the mediainformation for a given call. The database table name and column names arefully configurable in the configuration file, in the database section.

The table used to store these records, is automatically created by the mediadispatcher on startup, if it's not present. For this to happen, the user thatis configured in the dburi option in the database section, must have the CREATEand ALTER rights on the database specified in the same dburi. If this is notpossible, then the media dispatcher will log an error indicating why it couldnot create the table and also output the table definition that can be used bysome human operator to manually create the table. However, the recommendedway is to grant the CREATE and ALTER privileges to the user in the dburi overthe database specified in the same dburi.

The database module uses SQLObject to access the database, which means it canwork with a lot of databases, by simply changing the scheme in the dburi.Currently the following databases are supported: mysql, postgres, sqlite,firebird, maxdb, mssql and sybase.

Closing expired calls

Starting with version 2.1.0, MediaProxy supports closing calls for which allthe media streams did timeout, but for which no BYE was received to close thecall in the standard way.

This feature will only work, when the OpenSIPS mediaproxy module uses theengage_media_proxy() command to start MediaProxy for a given call. In thiscase the mediaproxy module uses the dialog module to keep track of the calland can pass the dialog id to the media dispatcher. When a media session isexpired because all streams did timeout, but no closing request was receivedfrom the proxy, the media dispatcher will use the dialog id that was receivedfrom the mediaproxy module, to issue a dlg_end_dlg request into the OpenSIPS'MI interface, instructing OpenSIPS to generate the BYEs for the call, closingit in a clean way and generating the accounting records.

To use this, the mi_datagram module must be loaded and configured to use aUNIX filesystem socket which must also be configured into the OpenSIPS sectionof the MediaProxy configuration as socket_path.

This feature is not available when using the use_media_proxy/end_media_sessionfunctions in the proxy configuration, because in that case there is no dialogthat is tracked by the proxy which could be terminated using dlg_end_dlg.

Installation

For people running Debian testing or unstable on an i386 architecture there isan official public repository provided by AG Projects. To use it, add theselines in /etc/apt/sources.list

# AG Projects softwaredeb http://ag-projects.com/debian unstable maindeb-src http://ag-projects.com/debian unstable main

Install the AG Projects debian software signing key:

wget http://download.ag-projects.com/agp-debian-gpg.keyapt-key add agp-debian-gpg.key

After that, run:

apt-get updateapt-get install mediaproxy-dispatcher mediaproxy-relay mediaproxy-web-sessions

to install all the packages, or you can install only the packages you actuallyneed on that specific system.

In case you want to build your own, please look below to Packaging section.

Installing from source

When installing from source, first make sure the above mentioned prerequisitesare installed. If the distribution you are running has them already packaged,you should install the distribution provided packages, else you'll have toinstall them from source. If you install them as packages, make sure that youalso install the development versions for python and libnetfilter-conntrack inorder to be able to build MediaProxy. If you have to install something fromsource, please consult the installation instructions for that specific packagein order to find out how to install it. For python packages there is a simplemethod to install them by running easy_install (make sure to run them as root):

easy_install twistedeasy_install zope.interfaceeasy_install python-applicationeasy_install python-cjsoneasy_install python-gnutls # this needs libgnutls-dev >= 2.4.1 installedeasy_install sqlobjecteasy_install pyrad

All of the above should work out of the box, except python-gnutls which needslibgnutls-dev at least version 2.4.1 to be installed to succeed.

An alternative method to install the python packages is to download, unpackand run (as root):

./setup.py build; ./setup.py install

for each of them in the directories where they were unpacked.

It should be noted that this only needs to be done for the packages that arenot provided already by your distribution, otherwise it is recommended to usethe distribution provided packages unless they do not meet the minimum versionrequirements mentioned above of it they exhibit problems at runtime.

After all the prerequisites are installed, MediaProxy can be installed eitheras a system wide package or in a standalone directory.

1. To install it as a system wide package, run (as root):

./setup.py build./setup.py install

in the directory where you unpacked MediaProxy.

2. To install in a standalone directory, unpack MediaProxy to the directorywhere you want it placed. Then change to that directory and run:

./build_inplace

After this MediaProxy components can be run from that directory.

In both cases, you can use the Debian startup scripts in the Debiansubdirectory, mediaproxy-dispatcher.init and mediaproxy-relay.init asexamples to create your own startup scripts for your distribution.

Packaging

The MediaProxy source already includes the necessary files to build Debianpackages. They should probably also work without changes for Ubuntu, thoughthey have not been tested with it.

To build Debian/Ubuntu packages, you can do the following (this is known towork with Debian testing and unstable and should work without changes inUbuntu 8.04 Hardy as well, though they were not tested there):

apt-get updateapt-get install devscripts cdbs debhelper python-all-dev python-support libnetfilter-conntrack-dev python-application python-cjson python-gnutls python-twisted-core python-twisted-names python-zopeinterface python-pyrad python-sqlobject

then unpack MediaProxy and in the directory where it was unpacked run:

debuild

You can safely ignore the pgp signing error at the end of the build process,that is only because you do not have the pgp key for the person who is listedas maintainer for the package. The packages are build fine even if they arenot signed.

After building them is done, you can find the .deb packages in the parentdirectory, from where you can install them using dpkg:

cd ../dpkg -i mediaproxy-*.deb

or you can install just the ones you need on that particular system.Please note that mediaproxy-dispatcher and mediaproxy-relay both depend onmediaproxy-common so you have to install it too along with either of them.

Configuration file

The configuration file is named config.ini and a config.ini.sample file isprovided in the source. You can copy config.ini.sample to config.ini andmodify it to suit your needs. The sample configuration file is commented andself-explanatory. Both the dispatcher and the relay read their configurationfrom the same file but from different sections. If either of them is notinstalled on a given system, its specific sections are ignored, so you onlyneed to configure the sections for the installed component(s).

MediaProxy will look for both a local configuration file, which is placed inthe same directory as the media-relay and media-dispather scripts, and asystem configuration file which is placed in /etc/mediaproxy/

Even though a local configuration file can be used in any case, it only makessense to be used in the standalone installation case, where MediaProxy livesin its own directory and there is a reason to contain all the MediaProxyrelated files to a single directory.

For system wide installations, where the media-relay and media-dispatcherscripts reside in /usr/bin or /usr/local/bin, it makes little sense toplace a local configuration file there, so in this case using the systemconfiguration file in /etc/mediaproxy/config.ini is recommended.

When both configuration files are present, both will be read and the settingsin the local configuration will override the ones in the system configuration.

Links

[http://mediaproxy-ng.org/ Mediaproxy 1.9.1]

[http://mediaproxy-ng.org/ Mediaproxy 2.0]