root/doc/INSTALL.txt

CDRTool installation
--------------------

Obtain the software from http://cdrtool.ag-projects.com. The software is
available as a tar archive or as a debian package. 

Installing from the tar archive:

Change directory to your web root (/var/www on Debian systems)

tar zxvf cdrtool*.tgz 

You must create /etc/cdrtool config directory unless you have installed the
debian package.

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

# 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 cdrtool


Create CDRTool database
-----------------------

You need MySQL root access with GRANT priviledges from the machine where
CDRTool runs, otherwise copy the files required by setup/setup_mysql.sh to
the MySQL machine and run the script locally.

Change the MySQL password of the cdrtool user from file
setup/create_users.mysql

Then run the database setup script:

cd /var/www/CDRtool/setup/mysql/
./setup_mysql.sh <password> <dbserver>

The script performs the following: 

1. It adds to the MySQL server a user for cdrtool software
2. It creates a new MySQL database "cdrtool" 
3. It creates a default web user admin/admin, you may use 
   this initial account to login in the web interface
4. It populates the cdrtool database with initial values


PHP setup and Apache setup
--------------------------

Install PHP and dependencies. If you have chosen to install the debian
package, the dependencies will be resolved during installation. 

Example for Debian systems and php5:

Enable php-mysql module in /etc/php5/*/php.ini:

extension=mysql.so

Enable php in apache web server. Configuration example for apache on
Debian systems:

/etc/apache/httpd.conf 

DirectoryIndex index.phtml index.php index.html index.htm index.shtml index.cgi
AddType application/x-httpd-php .php
AddType application/x-httpd-php .phtml

Make sure php module is enbaled in apache configuration. For apache this is
done in /etc/apache/modules.conf: 

LoadModule php4_module /usr/lib/apache/1.3/libphp4.so

Change AllowOverride None  to
    AllowOverride All 

For apache2 us a2enmode php command.

Create a virtual host for cdrtool. Example for apache2:

cp setup/apache2/sites-available/cdrtool.example.com /etc/apache2/sites-enabled 
cp setup/apache2/conf.d/cdrtool /etc/apache2/conf.d/

<VirtualHost cdrtool.example.com:80>

   ServerName          cdrtool.example.com
   DocumentRoot        /var/www/
   CustomLog           /var/log/apache2/cdrtool-access.log combined
   ErrorLog            /var/log/apache2/cdrtool-errors.log
   SetEnvIf User-Agent ".*MSIE.*"      nokeepalive ssl-unclean-shutdown

   # To enable SSL:
   # a2enmode ssl
   # add Listen 443 to ports.conf file
   # generate site certificates

   # SSLEngine           On
   # SSLCertificateFile    /etc/apache2/ssl/snakeoil-rsa.crt
   # SSLCertificateKeyFile /etc/apache2/ssl/snakeoil-rsa.key

</VirtualHost>

Enable the virtual site using:

a2ensite cdrtool.example.com

You may enable ssl using "a2enmod ssl" command. If you use ssl you must also
generate a site certificate using the instructions provided by apache2
software.


Create a configuration file
---------------------------

cp /var/www/CDRTool/setup/global.inc.simple.sample /etc/cdrtool/global.inc 

Edit global.inc and setup your variables to match your system.

For each different datasource you must instantiate a new class
extending one of the existing classes (ser, asterisk or cisco).

global.inc.in contains a more elaborate example for setting up 
datasources


Enable rating engine
--------------------

The rating engine is used for prepaid applications and as price calculator
for postpaid traffic. It provides access to the rating tables and stays in
memory (running as a daemon).

See the information in the head of the scripts/ratingEngine.php daemon for
how to enable prepaid or other rating functionality. For prepaid, an
external B2BUA is required, CDRTool provides only the rating and update
balance functions.

Set the IP and port where the rating engine listens to and the OpenSIPs
datasource in global.inc:

$RatingEngine=array("socketIP"   =>  "IP.address.of.the.private.interface.of.cdrtool.example.com",
                     "socketPort" => "9024",
                     "CDRS_class" => "ser_radius",
                     "allow"      => array('10.0.0')
                   );

The MSQL schema for prepaid accounts: setup/mysql/create_prepaid.mysql 

For non Debian systems you must create /etc/default/cdrtool as follows:

RUN_ratingEngine=yes

For non Debian systems copy the init script from setup/init.d/cdrtool to
/etc/init.d/cdrtool 

Then start the rating engine:

/etc/init.d/cdrtool restart


High availability
-----------------  

Setup heartbeat and MySQL replication.


CRON setup
----------

Some operations must be scheduled to run periodically by cron. Such
operations are the scripts that block fraudulous accounts in OpenSIPs,
normalize the call detail records, purge the old SIP traces.

The sample cron file is in /var/www/CDRTool/setup/crontabs/ 

This is done automatically if you install the debian package.


RADIUS setup
------------

CDRTool works with FreeRadius server from http://www.freeradius.org

apt-get install freeradius freeradius-mysql 
Create the database for radius tables on MySQL server

mysqladmin -u root create radius

Create RADIUS tables

The paths might differ depending on freeradius installation

cp /usr/share/doc/freeradius/examples/db_mysql.sql.gz .
gunzip db_mysql.sql.gz 
mysql -u root radius < /usr/share/doc/freeradius/examples/db_mysql.sql

Patch radacct table for storage of CISCO VSA and rating. Apply a patch to
the default radacct table. This will add fields necessary to store Vendor
Specific Atributes from Cisco or OpenSIPs.

It is not possible to mix call details records from CISCO and OpenSIPs
in the same radius table. You need to create multiple radius server
profiles and save the CDRs into dedicated tables for each datasource.

Modify the default radacct table for OpenSIPs by running:

/var/www/CDRTool/setup/radius/OpenSIPs/radacct-patch.sh

and for CISCO by running:

/var/www/CDRTool/setup/radius/CISCO/radacct-patch.sh 

Configure Freeradius to write data into the radacct table:

cp /var/www/CDRTool/setup/radius/OpenSIPs/sql.conf /etc/freeradius/sql.conf  

For large volume of CDRs it is usefull automatically rotate the tables in
which the data is written. 

/var/www/CDRTool/setup/radius/OpenSIPs/radius_accounting.*, contain mysql
procedures that automatically create monthly tables in the format
radacctYYYYMM. To use mysql procedures, your must use MySQL server version 5
or greater and Freeradius server mysql module must be compiled to support
CLIENT_MULTI_RESULTS mysql connection flag. This must be done in
src/modules/rlm_sql/drivers/rlm_sql_mysql/sql_mysql.c:

if (!(mysql_sock->sock = mysql_real_connect(&(mysql_sock->conn),
                                            config->sql_server,
                                            config->sql_login,
                                            config->sql_password,
                                            config->sql_db,
                                            atoi(config->sql_port),
                                            NULL, 
                                            CLIENT_FOUND_ROWS|CLIENT_MULTI_RESULTS ))) {

Also, if you use MediaProxy for accounting in combination with OpenSIPs you
must use the MediaProxy version that supports the same mysql procedures.
 
Edit the database connection details in sql.conf and restart Freeradius
server.

Add RADIUS clients in clients.conf. Each device sending RADIUS accounting
requests must be added to /etc/radddb/clients.conf. Examples:

client 10.0.0.0/8 {
        secret=DssUET01
        nastype=other
        shortname=localnet
}

Enable MySQL accounting in FreeRadius server. Edit radius.conf "sql" must be uncommented
or added if missing.   

# accounting { 
        detail 
        sql 
        }

Copy /var/www/CDRTool/setup/radius/OpenSIPs/dictionary.ser to /etc/freeradius


OpenSIPs setup
------------- 

Enable MySQL storage for subscribers and Radius accounting. For SIP tracing
you need to configure the OpenSIPs siptrace module. To enable quota you must
add an extra column in the subscriber table:

alter table openser.subscriber add column quota int not null;

Entries required in openser.cfg:

loadmodule "acc.so"

modparam("acc", "failed_transaction_flag", 1)
modparam("acc", "report_cancels",     0)
modparam("acc", "report_ack",         0)
modparam("acc", "early_media",        0)

modparam("acc", "log_level",          1)
modparam("acc", "log_flag",           1)
modparam("acc", "log_missed_flag",    1)

modparam("acc", "radius_config",      "/etc/openser/radius/client.conf")
modparam("acc", "radius_flag",        1)
modparam("acc", "radius_missed_flag", 1)
modparam("acc", "radius_extra",       "User-Name=$Au; \
                                       Calling-Station-Id=$from; \
                                       Called-Station-Id=$to; \
                                       Sip-Translated-Request-URI=$ruri; \
                                       Sip-RPid=$avp(s:rpid); \
                                       Source-IP=$si; \
                                       Source-Port=$sp; \
                                       Canonical-URI=$avp(s:can_uri); \
                                       Billing-Party=$avp(billing_party); \
                                       Divert-Reason=$avp(s:divert_reason); \
                                       X-RTP-Stat=$hdr(X-RTP-Stat); \
                                       User-Agent=$hdr(user-agent); \ 
                                       Contact=$hdr(contact); \
                                       Event=$hdr(event); \
                                       SIP-Proxy-IP=$avp(s:sip_proxy_ip); \
                                       ENUM-TLD=$avp(s:enum_tld)")

Further, you must enable accounting in various parts of the routing script
by setting the accounting flag and saving the AVP containing the proxy IP
address. It is important to save $avp(s:can_uri) after the Proxy has performed
all possible lookups except DNS. The Canonical-URI will be used for rating
the session. Example:

route {
       ...
       setflag(ACCOUNTING_FLAG);
       $avp(s:can_uri) = $ru;
       ...
}

Copy /var/www/CDRTool/setup/radius/OpenSIPs/dictionary.ser to /etc/openser/radius/
and uncomment the line:

$INCLUDE               /etc/radiusclient-ng/dictionary

Note
----

Many of the standard Radius attributes previously logged by default in the
accounting packets must be added manually to "radius_extra" parameter of the
acc module when using OpenSIPs >= 1.2.


MediaProxy setup
----------------

MediaProy can log into CDRTool the IP bandwidth utilization, the codecs and
the User Agents. MediaProxy logs this information into the database used by
the Radiusserver, the radacct table.

MediaProxy can also correct the session duration of CDRs for which no BYE
messages have been received.

The following information is logged: 

- InputOctets and OutputOctets
- CodecType (like GSM or G711)
- ApplicationType (text/audio/video)
- User Agent(s)
- Media IP source and IP destination

See MediaProxy documentation for how to enable Radius or database accounting.


Asterisk setup
--------------

Download from cvs the asterisk-addons and patch asterisk to store CDRs in
MySQL.

See /var/www/CDRTool/setup/asterisk for more information.


Cisco setup
-----------

Use the CISCO CLI, enter enable mode and configuration from terminal:

>enable
config terminal
aaa new-model
aaa group server radius aaa.router
server RADIUS_SERVER_IP auth-port 1812 acct-port 1813
aaa accounting connection h323 start-stop group radius
gw-accounting h323
gw-accounting h323 vsa
gw-accounting voip


Manual CDR uploads
------------------

If MySQL is down you will miss CDRs written by RADIUS. These CDRs can be
reload manually from radius accounting files using the supplied upload
scripts in scripts directory (IPNX, OpenSIPs and CISCO import scripts available).


Q931 Release codes for Cisco
----------------------------

In CDRTool CISCO hexadecimal release codes are automatically mapped to Q931
release codes.


Rating engine
-------------

See RATING file.


Monitoring
----------

Monit can check if the rating engine stopped working and restart it. A
sample configuration file for monit is available in setup/monit/monitrc.
Edit the IP address and hostname where the rating engine runs and copy
/var/www/CDRTool/setup/monit/monitrc /etc/monit/monit.d/cdrtool

Usage statistics
----------------

CDRTool can build  usage statistics of the number of online SIP devices from
OpenSIPs, simultaneous number of media streams and relayed IP traffic by
MediaProxy.

Define DB_siponline as a new database class in global.inc. Example:

class DB_siponline extends DB_Sql {
  var $Host     = "db";
  var $Database = "openser";
  var $User     = "openser";
  var $Password = "password";
  var $Halt_On_Error ="no";
}

Define all media proxy servers as follows:

For MediaProxy 1.x: mediaServers variable of each data source 
For MediaProxy 2.x: mediaDispatcher variable of each data source 

The script that gathers the usage information and builds the graphical
statistics is /var/www/CDRTool/scripts/buildStatistics.php

This script runs as a cron job every 5 minutes.

The usage information is cumulated in /tmp/CDRTool-sip-statistics.txt file,
which is a plain text file with one line per domain and values separated by
tabs. This file can be easily parsed by external scripts to build statistics
using other tools like SNMP.

To see the graphical statistics, follow the Usage link.