Page MenuHomePhabricator
Files F7159158

No OneTemporary
Actions

View Options

diff --git a/INSTALL b/INSTALL
index f8ba6fc..7bd7663 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,221 +1,218 @@
MediaProxy installation procedure
---------------------------------
-Copyright (c) 2008-2012 AG Projects
+Copyright (c) 2008-2020 AG Projects
http://ag-projects.com
Authors: Ruud Klaver, Dan Pascu, Saul Ibarra
Home page: http://mediaproxy.ag-projects.com
For the list of changes between revisions please consult debian/changelog
For information about the MediaProxy architecture, configuring and running
the dispatcher and the relay, as well as details about the supported
features and how to use them, please consult the README file.
Prerequisites
-------------
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)
+ - libnetfilter-conntrack
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).
- - iptables (at least version 1.4.3)
+ - iptables
To build MediaProxy, the development version is needed (usually has a -dev
suffix in the package name). For running the development package is not
needed, only plain iptables is enough.
- - Python (at least 2.5)
+ - Python3
http://python.org
- - Twisted framework (at least 2.5.0 with epollreactor support)
+ - Twisted framework
http://twistedmatrix.com
- - python-zopeinterface (this is also a requirement for twisted)
- http://zope.org/Products/ZopeInterface
- - python-application (at least 1.2.8)
- http://pypi.python.org/pypi/python-application
+ - python3-zope.interface
+ http://zope.org
+ - python3-application
+ http://download.ag-projects.com/others/
- GNU-TLS
http://www.gnu.org/software/gnutls
- - python-gnutls (at least 3.0.0)
- http://pypi.python.org/pypi/python-gnutls
- - python-cjson
- http://pypi.python.org/pypi/python-cjson
+ - python3-gnutls (at least 3.0.0)
+ http://download.ag-projects.com/others/
For the database accounting module:
- SQLObject
http://sqlobject.org
For the RADIUS accounting module:
- - pyrad (at least 1.1)
- http://www.wiggy.net/code/pyrad/
+ - pyrad
+ https://pypi.org/project/pyrad/
Installation
------------
For people running Debian or Ubuntu on an i386 or amd64 architecture there are
official public repositories provided by AG Projects.
Modify your /etc/apt/sources.list depending on the distribution you are using,
check here for the appropriate lines:
http://mediaproxy.ag-projects.com/wiki/InstallationGuide
Install the AG Projects debian software signing key:
wget http://download.ag-projects.com/agp-debian-gpg.key
apt-key add agp-debian-gpg.key
After that, run:
apt-get update
apt-get install mediaproxy-dispatcher mediaproxy-relay mediaproxy-web-sessions
to install all the packages, or you can install only the packages you actually
need 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 prerequisites
are installed. If the distribution you are running has them already packaged,
you should install the distribution provided packages, else you'll have to
install them from source. If you install them as packages, make sure that you
also install the development versions for python and libnetfilter-conntrack in
order to be able to build MediaProxy. If you have to install something from
source, please consult the installation instructions for that specific package
in order to find out how to install it. For python packages there is a simple
method to install them by running easy_install (make sure to run them as root):
easy_install twisted
easy_install zope.interface
-easy_install python-application
-easy_install python-cjson
-easy_install python-gnutls # this needs libgnutls-dev >= 2.4.1 installed
easy_install sqlobject
easy_install pyrad
-All of the above should work out of the box, except python-gnutls which needs
-libgnutls-dev at least version 2.4.1 to be installed to succeed.
+python3-application and python3-gnutls can be downloaded from
+
+http://download.ag-projects.com/others/
+
An alternative method to install the python packages is to download, unpack
and 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 are
not provided already by your distribution, otherwise it is recommended to use
the distribution provided packages unless they do not meet the minimum version
requirements mentioned above or if they exhibit problems at runtime.
After all the prerequisites are installed, MediaProxy can be installed either
as 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 directory
where 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 Debian
subdirectory, mediaproxy-dispatcher.init and mediaproxy-relay.init as
examples to create your own startup scripts for your distribution.
Packaging
---------
The MediaProxy source already includes the necessary files to build Debian
packages. They should probably also work without changes for Ubuntu, though
they have not been tested with it.
To build Debian/Ubuntu packages, you can do the following (this is known to
work with Debian testing and unstable and should work without changes in
Ubuntu 8.04 Hardy as well, though they were not tested there):
apt-get update
-apt-get install devscripts cdbs debhelper python-all-dev python-support \
- iptables-dev libnetfilter-conntrack-dev python-application python-cjson \
- python-gnutls python-twisted-core python-twisted-names \
- python-zopeinterface python-pyrad python-sqlobject
+apt-get install devscripts cdbs debhelper python3-all-dev \
+ iptables-dev libnetfilter-conntrack-dev python3-application \
+ python3-gnutls python3-twisted python3-zope.interface \
+ python3-pyrad python3-sqlobject
then unpack MediaProxy and in the directory where it was unpacked run:
debuild -us -uc
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 listed
as maintainer for the package. The packages are build fine even if they are
not signed.
After building them, you can find the .deb packages in the parent directory,
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 on
mediaproxy-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 is
provided in the source. You can copy config.ini.sample to config.ini and
modify it to suit your needs. The sample configuration file is commented and
self-explanatory. Both the dispatcher and the relay read their configuration
from the same file but from different sections. If either of them is not
installed on a given system, its specific sections are ignored, so you only
need to configure the sections for the installed component(s).
MediaProxy will look for both a local configuration file, which is placed in
the same directory as the media-relay and media-dispather scripts, and a
system configuration file which is placed in /etc/mediaproxy/
Even though a local configuration file can be used in any case, it only makes
sense to be used in the standalone installation case, where MediaProxy lives
in its own directory and there is a reason to contain all the MediaProxy
related files to a single directory.
For system wide installations, where the media-relay and media-dispatcher
scripts reside in /usr/bin or /usr/local/bin, it makes little sense to
place a local configuration file there, so in this case using the system
configuration file in /etc/mediaproxy/config.ini is recommended.
When both configuration files are present, both will be read and the settings
in the local configuration will override the ones in the system configuration.
diff --git a/README b/README
index 36e9470..89a1b79 100644
--- a/README
+++ b/README
@@ -1,333 +1,329 @@
MediaProxy
----------
Authors: Ruud Klaver, Dan Pascu, Saul Ibarra
Home page: http://mediaproxy.ag-projects.com
License
-------
This software is licensed according to the GNU General Public License
version 2. See LICENSE file for more details.
For other licensing options please contact sales-request@ag-projects.com
Description
-----------
MediaProxy is a media relay for RTP/RTCP and UDP streams that works in
tandem with OpenSIPS to provide NAT traversal capability for media streams
from SIP user agents located behind NAT.
When using MediaProxy, NAT traversal for RTP media will work without any
settings in the SIP User Agents or the NAT router.
Features
--------
- Scalability of thousands of calls per server limited only by the Linux
kernel networking layer and network interface bandwidth
- Supports multiple chained relays as long as each has a public IP
- TLS encryption between the relays and dispatcher
- T.38 fax support
- Graceful shutdown capability
- Automatic load balancing and redundancy among all media relays
- Real-time sessions statistics
- Configurable IP and UDP port range
- Support for any combination of audio and video streams
- Ability to use OpenSIPS' MI interface to close a call that did timeout
- Radius accounting of IP network traffic
- Database accounting of complete media information including all streams,
their type, codecs and duration.
- Supports ICE negotiation by behaving like a TURN relay candiate
Background
-----------
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).
New features have been added to support call flows related to user mobility
and fax transmission.
Architecture
------------
MediaProxy consists of a dispatcher and one or more media relays.
The dispatcher component always runs on the same host as OpenSIPS and
communicates with its mediaproxy module through a UNIX domain socket. The
relay(s) connect to the dispatcher using TLS. This relay component may be on
the same or on a different host as OpenSIPS. There may be several relays for
the dispatcher to choose from and a relay may service more than one
dispatcher.
When OpenSIPS requests that a call be relayed, the dispatcher will forward
this request to one of its connected relays, along with some data from the
SDP. The relay will allocate a set of UDP ports for this session, depending
on the number of proposed streams. It will inform the dispatcher which ports
it has allocated so that it may in turn notify the mediaproxy module of
OpenSIPS, which will replace the relevant parts of the SDP.
The same is done for any SIP messages from the callee, thus all the media
streams will be sent through the relay. When the session between caller and
callee has finished, either through a SIP BYE or because the media is no
longer flowing and has timed out, the relay will send session information to
the dispatcher, which can store this information using one or more accounting
modules.
The session information may also be queried using a management interface on
the 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.
Compatibility and pre-requisites
--------------------------------
Both OpenSIPS and MediaProxy must use a public IP address.
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). IPtables 1.4.3 or higher is also
required. 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 OpenSIPS older than 1.4 or any components of MediaProxy
older than 2.0. You must completely upgrade any previous installation of
OpenSER to OpenSIPS to use this version of MediaProxy.
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)
For information of how to install MediaProxy, please consult the INSTALL
file.
Operation
---------
Before the relay is run, please make sure that /proc/sys/net/ipv4/ip_forward
is set to "1". Also for newer kernels ACCT on connection tracking needs to
be enabled. Therefore /proc/sys/net/netfilter/nf_conntrack_acct must be set to
"1".
Both the dispatcher and the relay should be executed with root privileges.
With no arguments, both applications will automatically fork into the
background and log to syslog. They can remain in the foreground and log to
console when given the --no-fork argument.
The relay can be shut down in two ways. When receiving either an INT or TERM
signal, the relay will terminate all of its sessions immediately and inform
the dispatcher that those sessions have expired. When given the HUP signal,
it will not accept any new sessions from the dispatcher and wait for all of
the running sessions to expire, thus terminating gracefully.
At the very least a set of TLS credentials is required. Sample certificates
for this are included in the tls/ subdirectory.
DO NOT USE THESE IN A PRODUCTION ENVIRONMENT, but only for testing purposes.
For more information about TLS certificates and how to generate your own,
check the tls/README file.
Accounting
----------
MediaProxy is capable to do additional per call accounting with information
related to the media streams used by the call. MediaProxy has a modular
interface to the accounting system, allowing for new modules to be easily
implemented. Currently it supports database and radius backends. Multiple
backends can be configured and used simultaneously.
Radius accounting
-----------------
The radius backend logs very basic information about the media streams. The
limited nature of the logged information is mainly given by the limitations
imposed by the radius protocol to the data size.
The information sent in the radius packet is shown below:
Acct-Status-Type = "Update"
User-Name = "mediaproxy@default"
Acct-Session-Id = call_id
Sip-From-Tag = from_tag
Sip-To-Tag = to_tag
Acct-Session-Time = call duration
Acct-Input-Octets = bytes received from caller
Acct-Output-Octets = bytes received from callee
NAS-IP-Address = media-relay address
Sip-User-Agents = caller + callee user agents
Sip-Applications = "Audio", "Video", ...
Media-Codecs = codecs used by streams (comma separated)
Media-Info = "timeout" or ""
Acct-Delay-Time = post dial delay (seconds from INVITE to 1st media packet)
Database accounting
-------------------
The database backend logs all the information related to the media streams that
were created/closed during the whole session. This information is stored as a
JSON encoded string in a BLOB column in the database, along with the call_id,
from_tag and to_tag columns that can be used to retrieve the media information
for a given call. The database table and column names are fully configurable
in the database section of the configuration file.
The table used to store these records, is automatically created by the media
dispatcher on startup, if it's not present. For this to happen, the user that
is configured in the dburi option in the database section, must have the CREATE
and ALTER rights on the database specified in the same dburi. If this is not
possible, then the media dispatcher will log an error indicating why it could
not create the table and also output the table definition that can be used by
some human operator to manually create the table. However, the recommended
way is to grant the CREATE and ALTER privileges to the user in the dburi over
the database specified in the same dburi.
The database module uses SQLObject to access the database, which means it can
work 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 all
the media streams did timeout, but for which no BYE was received to close the
call in the standard way.
This feature will only work, when the OpenSIPS mediaproxy module uses the
engage_media_proxy() command to start MediaProxy for a given call. In this
case the mediaproxy module uses the dialog module to keep track of the call
and can pass the dialog id to the media dispatcher. When a media session is
expired because all streams did timeout, but no closing request was received
from the proxy, the media dispatcher will use the dialog id that was received
from the mediaproxy module, to issue a dlg_end_dlg request into the OpenSIPS'
MI interface, instructing OpenSIPS to generate the BYEs for the call, closing
it in a clean way and generating the accounting records.
To use this, the mi_datagram module must be loaded and configured to use a
UNIX filesystem socket which must also be configured into the OpenSIPS section
of the MediaProxy configuration as socket_path.
This feature is not available when using the use_media_proxy/end_media_session
functions in the proxy configuration, because in that case there is no dialog
that is tracked by the proxy which could be terminated using dlg_end_dlg.
Gracefull shutdown
------------------
To tell media-relay component to gracefully shutdown when using systemd:
sudo systemctl reload mediaproxy-relay
The reload command will send the HUP signal to the PID of the relay
component and the software will shutdown when the last relayed call has
ended.
Management interface
--------------------
The management interface will accept commands terminated by \r\n. It will
return the results of the command, one per line, terminated by an empty
line (also \r\n terminated).
Currently two commands are supported:
sessions : This will have the dispatcher query all of its connected relays
for active sessions. For every sessions it finds it will return
one line with a JSON encoded dictionary containing session
information.
summary : This will have the dispatcher present a summary of each of its
connected relays. The results are returned as a JSON encoded
dictionary, one line per relay.
Free support
------------
MediaProxy is developed and supported by AG Projects. AG Projects offers
best-effort free 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.
You may report bugs or feature request to:
users@lists.opensips.org
A mailing list archive is available at:
http://lists.opensips.org/cgi-bin/mailman/listinfo/users
Commercial support
------------------
-Commercial support options are available by purchasing:
-
-1. Multimedia Service Platform: http://ag-projects.com/Products or
-2. MediaProxy and support: https://secure.dns-hosting.info/buyer_guide.phtml
-
+Visit http://ag-projects.com

File Metadata

Mime Type
text/x-diff
Expires
Sat, Nov 23, 3:16 AM (13 h, 31 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
3408641
Default Alt Text
(23 KB)

Event Timeline