MediaProxy installation procedure --------------------------------- Copyright (c) 2008 AG Projects http://ag-projects.com Authors: Ruud Klaver, Dan Pascu Home page: http://www.ag-projects.com/MediaProxy.html Architecture ------------ MediaProxy is made up of (at least) two components: A dispatcher and a relay. The dispatcher component always runs on the same host as OpenSER 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 OpenSER. There may be several relays for the dispatcher to choose from and a relay may service more than one dispatcher. When OpenSER 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 OpenSER, 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 | | | |<--+->| OpenSER |<-------+------------------->| | | | | +---------+ | | | | | | ^ | | | | | | | 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. Installation ------------ 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 - 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/ 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. Operation --------- Before the relay is run, please make sure that /proc/sys/net/ipv4/ip_forward is 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. Both the dispatcher and the relay read their configuration from /etc/mediaproxy/config.ini. A sample configuration file is provided which should be self-explanatory. 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. 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.