Installation Guide

Download

You can install CDRTool in the following ways:

1. As a debian package from ag-projects repository

2. Generating the debian package

3. Installing from the tar archive

4. From the version control repository

# AG Projects software
deb http://ag-projects.com/debian unstable main
deb-src http://ag-projects.com/debian unstable main

sudo wget -O /etc/apt/trusted.gpg.d/agp-debian-key.gpg http://download.ag-projects.com/agp-debian-key.gpg

sudo apt-get update
sudo apt-get install cdrtool

cd CDRTool
debuild

dpkg -i cdrtool_version_all.deb

darcs get http://devel.ag-projects.com/repositories/cdrtool

cd cdrtool
darcs pull -a

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:

/var/www/CDRtool/setup/mysql/setup_mysql.sh

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 its dependencies. If you have chosen to install the debian package, the dependencies will be resolved during installation.

Configure php both the command line and apache module to support mysql.

Configure Apache2 server to support php scripting.

Create a virtual host for cdrtool web pages:

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

Edit /etc/apache2/sites-available/cdrtool.example.com to suit your environment. Enable the virtual site using:

a2enconf cdrtool.conf
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 CDRTool 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. The file global.inc.complex.sample contains a more elaborate example for setting up multiple datasources.

You must change at least the following settings:

• The RatingEngine IP address

• The mysql connection details to cdrtool, radius, opensisps, siptrace and mediaproxy MySQL databases, which are described in the following sections of this document

• The mediaDispatcher address

Enable rating engine

The rating engine is used by the prepaid application and as price calculator for postpaid traffic. More info about rating engine you can find in the RATING.txt document.

For prepaid, an external call controll application is required, CDRTool itself provides only the maxsession time and debit balance functions. Call Control can be used to terminate the session based on these functions. For setting up Call Control see PREPAID.txt.

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

$RatingEngine = array(
    "socketIP"   => "IP.address.of.cdrtool.example.com",
    "socketPort" => "9024",
    "cdr_source" => "opensips_radius",
    "allow"      => array('10.0.0')
);

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 restart the rating engine, which you must do every time you made changes to global.inc:

/etc/init.d/cdrtool restart

To verify that the rating engine has started correctly check syslog for errors. To verify the connection to the rating engine you can telnet to port 9024 and type ‘help’ command.

cp /var/www/CDRTool/setup/csv/\* /var/spool/cdrtool
/var/www/CDRTool/scripts/importRatingTables.php

CRON jobs 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. This is done automatically if you install the debian package. For other Linux systems modify and install the cron file from /var/www/CDRTool/setup/crontabs/

Freeradius setup

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

OpenSIPS generates START and STOP radius messages when a session is established by INVITE request, 200 OK response combination and respectively terminated by a BYE request, these packets are handled by the Freeradius server, which writes them into the hosting MySQL database. For failed SIP sessions a radius packet type FAILED is generated. A failed SIP session is a session that has been rejected by the Proxy server or by the destination.

Unfortunately Freeradius server is not able to cope with FAILED packets. The server must be patched and recompiled if you wish to support accounting for failed SIP sessions.

The patches and instructions for how to apply them are found in setup/radius/FreeRadius/ and contrib/freeradius-brandinger/.

Install the server from Debian package or your own compiled version after you applied the patches:

apt-get install freeradius freeradius-mysql

Alternatively you can install the freeradius-xs debian package provided in the AG Projects debian repository that contains all required patches:

apt-get install freeradius-xs freeradius-xs-mysql

Create the database for radius tables on the MySQL server:

mysqladmin -u root create radius

Create RADIUS tables:

mysql -u root radius < /var/www/CDRTool/setup/radius/OpenSIPS/radacct.mysql

Configure Freeradius to write data into mysql:

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

Load the MySQL stored procedures that create the monthly tables:

mysql -u root radius < /var/www/CDRTool/setup/radius/OpenSIPS/radius\_accounting.proc

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

client 10.0.0.0/8 {
        secret=YourSecret
        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 the radius dictionaries from OpenSIPS and MediaProxy:

cp /var/www/CDRTool/setup/radius/OpenSIPS/dictionary.opensips to /etc/freeradius
cp /var/www/CDRTool/setup/radius/MediaProxy/dictionary.mediaproxy to /etc/freeradius

Edit /etc/freeradius/dictionary as follows:

# standard radius dictionary
$INCLUDE        /usr/share/freeradius/dictionary

# OpenSER dictionary
$INCLUDE        /etc/freeradius/dictionary.opensips

# MediaProxy dictionary
$INCLUDE        /etc/freeradius/dictionary.mediaproxy

Grant access to radius user to the radius database, replace PASSWORD and PRIVATE_IP_NETWORK with the real values:

GRANT ALL ON radius.*  TO radius@'PRIVATE_IP_NETWORK.%' IDENTIFIED by 'PASSWORD';

CREATE ALGORITHM=UNDEFINED DEFINER=`root`@`localhost` SQL SECURITY
DEFINER VIEW `trusted` AS select `address`.`id` AS `id`,`address`.`ip`
AS `src_ip`,`address`.`proto` AS `proto`,`address`.`pattern` AS
`from_pattern`,`address`.`context_info` AS `tag` from `address` where
(`address`.`grp` = 1)

ALTER TABLE opensips.subscriber ADD COLUMN quota int NOT NULL;

loadmodule "siptrace.so"
loadmodule "acc.so"

# global acc parameters
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/opensips/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=$ru; \
                                       Sip-RPid=$avp(s:rpid); \
                                       Source-IP=$avp(s:source_ip); \
                                       Source-Port=$avp(s:source_port); \
                                       SIP-Proxy-IP=$avp(s:sip_proxy_ip); \
                                       Canonical-URI=$avp(s:can_uri); \
                                       Billing-Party=$avp(billing_party); \
                                       Divert-Reason=$avp(s:divert_reason); \
                                       User-Agent=$hdr(user-agent); \
                                       Contact=$hdr(contact); \
                                       Event=$hdr(event); \
                                       ENUM-TLD=$avp(s:enum_tld)")

modparam("siptrace", "db_url", "mysql://opensips:password@localhost/opensips")
modparam("siptrace", "traced_user_avp", "$avp(s:traced_user)")
modparam("siptrace", "trace_on",        1)
modparam("siptrace", "trace_flag",      2)

loadmodule "aaa_radius.so"
loadmodule "acc.so"
loadmodule "siptrace.so"


 global acc parameters
 modparam("acc", "failed_transaction_flag", 1)
 modparam("acc", "report_cancels",     0)
 modparam("acc", "early_media",        0)

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

 modparam("acc", "aaa_url",            "radius:/etc/opensips/radius/client.conf")
 modparam("acc", "aaa_flag",           1)
 modparam("acc", "aaa_missed_flag",    1)
 modparam("acc", "aaa_extra",          "User-Name=$Au; \
                                        Calling-Station-Id=$avp(calling_station); \
                                        Called-Station-Id=$to; \
                                        Sip-Translated-Request-URI=$ru; \
                                        Sip-RPid=$avp(asserted_identity); \
                                        Source-IP=$avp(source_ip); \
                                        Source-Port=$avp(source_port); \
                                        SIP-Proxy-IP=$avp(sip_proxy_ip); \
                                        Canonical-URI=$avp(can_uri); \
                                        Billing-Party=$avp(billing_party); \
                                        Divert-Reason=$avp(diversion_reason); \
                                        User-Agent=$hdr(user-agent); \
                                        Contact=$hdr(contact); \
                                        Event=$hdr(event); \
                                        ENUM-TLD=$avp(enum_tld); \
                                        From-Header=$hdr(from); \
                                        SIP-Application-Type=$avp(sip_application_type)")

modparam("siptrace", "db_url", "mysql://opensips:password@localhost/opensips")
modparam("siptrace", "traced_user_avp", "$avp(s:traced_user)")
modparam("siptrace", "trace_on",        1)
modparam("siptrace", "trace_flag",      2)

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

MediaProxy setup

MediaProy can log the IP bandwidth utilization, the codecs and the User Agents. MediaProxy logs this information into the database used by the Freeradius server in radacct table. !MediaProxy also corrects the session duration of CDRs for which no BYE messages have been received. See project:MediaProxy documentation for how to enable Radius and database accounting.

MediaProxy logs detailed information about each individual stream (its type, duration, time-out end point ports). The logging is performed in a separate mysql table (default mediaproxy.media_sessions). The MySQL schema is defined in setup/radius/MediaProxy/create_table_media_sessions.mysql. You do not need to create that table, the mediaproxy does it automatically if it has the rights to the configured database.

The detailed information about the media streams is displayed in the SIP trace web page, follow the link about media trace.

Enable accounting in /etc/mediaproxy/config.ini:

[Dispatcher]
accounting = radius,database

[Database]
dburi = mysql://mediaproxy:password@db/mediaproxy

[Radius]
config_file = /etc/opensips/radius/client.conf
additional_dictionary = radius/dictionary

It is possible to retrieve also real-time information about the ongoing sessions and streams, this can be used to plot usage statistics from external applications. The Usage and Sessions web pages display this information. The information is obtained from any mediaproxy dispatcher, which has connections to all configured relays.

Create or copy both a media relay certificate and its key to /etc/cdrtool/mediaproxy.hostname.pem:

cat /etc/mediaproxy/tls/relay.crt >> /etc/cdrtool/mediaproxy.hostname.pem
cat /etc/mediaproxy/tls/relay.key >> /etc/cdrtool/mediaproxy.hostname.pem

and set the option:

"mediaDispatcher"      => "tls:hostname:25061"

for each datasource that uses MediaProxy in global.inc.

Replace the hostname with the real IP or hostname of the mediaproxy dispatcher.

Make sure your php is compiled with openssl support

Login accounts

To login to the web interface you must create login accounts. During the initial database the username 'admin' with the password 'admin' has been automatically created. You should change this password after the first time you login.

Click on the Login link to add or change existing login accounts. Each account has a set of Permissions that grant the login account with certain right. Also you must specify which datasource may be accessed by a login account.

You can experiment with the set of Permissions, their name should be self explanatory.

Beware that the 'admin' right simply mean that you can create other login accounts. You still need to select the appropriate permissions for the admin account in order to have access to various functionality controlled by the Permissions system.