root/INSTALL

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

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)
   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 (at least 1.1)
   http://www.wiggy.net/code/pyrad/


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

For people running Debian testing or unstable on an i386 architecture there is
an official public repository provided by AG Projects. To use it, add these
lines in /etc/apt/sources.list (use unstable/testing as appropriate):

# AG Projects software
deb     http://ag-projects.com/debian unstable main
deb-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.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.

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