

MediaProxy is a far-end NAT traversal solution for OpenSER (http://OpenSER.org) 
and SIP Express Router (http://iptel.org/ser).

For details about the design and how it works please consult the README file.


Support
-------

Please report bugs to serusers@iptel.org. Before reporting bugs, please read
the mailing list archives (http://mail.iptel.org/mailman/listinfo/serusers)
to make sure your questions have not already been answered.

MediaProxy is developed and supported by AG Projects. AG Projects
offers best-effort gratis support for MediaProxy. "best-effort" means that
we try to solve the bugs you report or help fix your problems as soon as we
can, subject to available resources.

Commercial support
------------------

For commercial support, please contact 
AG Projects http://ag-projects.com

If you have a support contract, please login with your account at
http://support.ag-projects.com and create a trouble-ticket with your
problem.

Installation
------------

Prerequisites:
- ser version 8.14 (stable) or newer
- python 2.2 or newer, 2.3 is recommended.
  for python versions older than 2.3, the python-optik module
  (version 1.4.1 or newer) is required.
- For accounting python-mysqldb module is required

MediaProxy consists of three components:

1. mediaproxy.so is the SER module
2. proxydispatcher.py does distribution and load balancing of SER requests
3. mediaproxy.py is the server doing the media relay

The first two components must run on the same machine where SER runs.
The third component may run either on the same machine or on (multiple)
remote servers. 

For details about the mediaproxy architecture please read the included README
file as well as the Readme file from the mediaproxy module from SER.
Details about command line options for the programs can be found in the
Readme file as well. A summary of the command line options is displayed by
each command when using the -h or --help command line option.


Installation of the mediaproxy dispatcher and server
----------------------------------------------------

Download Mediaproxy from

http://www.ag-projects.com/MediaProxy.html 

Unpack the archive in /usr/local/ (all necessary files will be under the 
mediaproxy/ subdirectory).

Rename mediaproxy.ini.sample to mediaproxy.ini and edit the various options to
match your environment. The configuration file has detailed explanations for
every option you can set.

Copy the startup script (depending on your platfrom) from
/usr/local/mediaproxy/boot/ to /etc/init.d/mediaproxy

Make the necessary symlinks in the rc?.d directories in etc if you want it to
start at boot time. For debian this can be easily accomplished by running:

update-rc.d mediaproxy defaults 20 90 

Run as root: /etc/init.d/mediaproxy start

Add DNS SRV records in the for the SIP domains you wish to serve.
Put them at the same priority with different weights to allow load balancing
of traffic. Put them at different priorities to allow fallback.

Example1:
---------

Considering your domain is mydomain.com and you wan to dedicate 3 main
servers and 2 fallbacks. The main servers you want to distribute traffic
among are 2 1Ghz machines (named nat1 and nat2) and a 2Ghz machine (nat3).
You want 25% from the traffic to go to each 1Ghz machine and 50% to the 2Ghz
machine. For the fallbacks (nat4 and nat5) you want to distribute the
traffic equally among the 2 machines.

_mediaproxy._tcp.mydomain.com.  IN SRV   0  25 25060 nat1.mydomain.com.
_mediaproxy._tcp.mydomain.com.  IN SRV   0  25 25060 nat2.mydomain.com.
_mediaproxy._tcp.mydomain.com.  IN SRV   0  50 25060 nat3.mydomain.com.
_mediaproxy._tcp.mydomain.com.  IN SRV  10  50 25060 nat4.mydomain.com.
_mediaproxy._tcp.mydomain.com.  IN SRV  10  50 25060 nat5.mydomain.com.

If your DNS provider does not support SRV records, take a look at Managed
DNS http://www.managed-dns.org

In this setup, the traffic will be distributed between the nat1, nat2 and
nat3 machines in a proportion of 25%+25%+50%. If one goes offline the other
2 will take it's traffic share redistributing the load balancing according
to their own weight. If all of nat1, nat2, nat3 stop responding, nat4 and
nat5 will be used distributing the traffic among them equally (50%+50%)


Example2:
---------

You don't want to distribute traffic based on SIP domain of the
caller/destination, but you want to distribute all media traffic no matter
what SIP domain is from among multiple proxy servers.

In this case choose a domain under your control (you have access to its DNS
zone). Add SRV records (like in the example above) to define all the servers
you wish to spread traffic to. Start the proxy servers on those hosts,
listening on a network address for remote control.  Start the dispatcher on
the same host as the SER server itself with the following option:
--proxy=domain://mydomain.com

This way the dispatcher will use the servers defined in the mydomain.com for
all domains that don't have SRV records to define proxy servers. Since you
don't care about this, you only added SRV records in the mydomain.com and
all calls (since their domains don't define their own records) will fallback
to use the default proxies as defined in the mydomain.com domain.


Performance
-----------

This is a rough estimate, it might vary to some extend. A 1GHz CPU might be
able to handle 10 Mbit/s in and 10Mbit/s out of RTP traffic with 80 calls
using the G711 codec. The limitations are imposed by the number of
concurrent calls rather by the bandwidth utilization.

Use mediaproxy/utils/rtpgenerator.py to test the load on your system.

Accounting
----------

Accounting is done by sending the accounting information from the MediaProxy
servers back to the proxy dispatcher, which will log it into the database.
If the media session timeouts (there is no BYE that closes the session),
MediaProxy will contact back the proxy dispatcher and pass the session media
information to be logged.
Using this architecture, only the proxy dispatcher needs to have direct
access to the database. This addresses the issue of the MediaProxy servers
being distributed and not having access to the database.

A MediaProxy server will pass accounting information back to the proxy
dispatcher if the request came through the proxy dispatcher (in this case it
will ignore the dbaccounting configuration option). Else it will log into the
database directly if the dbaccounting configuration option is enabled. If none
of the above conditions are met the accounting information will be discarded.

The proxy dispatcher will log into the database if the dbaccounting option
is true, else will discard the accounting information.
For security reasons, the proxy dispatcher will only accept accounting
information from the same MediaProxy server where the requests were sent.

Accounting of network traffic is available by applying a patch to radacct
table to hold information about media sessions and configuring the
mediaproxy.ini Accounting section with the MySQL connection information.

The patch for the standard Radius radacct table can be found in CDRTool
distribution available at http://cdrtool.ag-projects.com in the file
CDRTool/setup/radius/OpenSER/radacct-patch.mysql

The following table lists the corespondence between mediaproxy
information and the fields from the radacct table:

    startTimeField   = 'AcctStartTime'
    stopTimeField    = 'AcctStopTime'
    durationField    = 'AcctSessionTime'
    callerBytesField = 'AcctInputOctets'
    calledBytesField = 'AcctOutputOctets'
    sessionIdField   = 'AcctSessionId'
    userAgentField   = 'SipUserAgents'
    codecTypesField  = 'SipCodecs'
    streamTypeField  = 'SipApplicationType'
    fromTagField     = 'SipFromTag'
    toTagField       = 'SipToTag'
    startInfoField   = 'ConnectInfo_start'
    stopInfoField    = 'ConnectInfo_stop'
    mediaInfoField   = 'MediaInfo'
    normalizedField  = 'Normalized'

A future version of MediaProxy will have the MySQL query configurable. 

The accounting can be syncronized with SER RADIUS accounting providing
complete service usage information for each call (duration, bandwidth, codec
and application type).

The accounting module is also able to cleanly close a session that dies
without sending a BYE. In such a case, the accounting module will update the
time for the call when the session does timeout after no RTP traffic is
received for the idle timeout period, making it possible to avoid fraud
attempts or issues generated by network problems and still get correct
accounting records.

Note:
In the current version of MediaProxy (1.7.2), the python-mysqldb module
should be installed on all mediaproxy nodes even if they don't make use of
MySQL access, but instead pass the information back to the dispatcher.
If the python-mysqldb module is not installed, no media session information
will be sent to the proxy dispatcher and no accounting will be done.
Even if accounting is disabled, mediaproxy/proxydispatcher will write an
error message to syslog about accounting being enabled but not available
because the accounting module is missing. This error message is inaccurate
and it means in fact that the python-mysqldb is not installed.

This is a known issue which is a leftover from an older implementation and
will be fixed in the next release.

