Installation and Configuration of Asterisell v3

Requirements

HTTP WEB Server
PHP 5.0 or greater (PHP 4.0 is not supported)
GD support enabled in PHP;
MySQL DBMS
Asterisk VoIP server

Software Infrastructure

VoIP calls are managed from Asterisk Server:

it routes the calls to the proper dial peer;
it associates to every customer a unique “accountcode”;
it writes Call Detail Records (CDRs) on a specific MySQL database table shared with Asterisell.

Asterisell is a PHP5 web application that:

reads calls information from the CDR table shared with Asterisk Server;
associate to every call a cost (what the service provider pays to other vendors for routing the customer’s call);
associate to every call an income (what the customer pays to the service provider);
displays calls info;

Download

Download through Git

The suggested way to download this release is using Git version control system. This allows to:

download application updates in an efficient way;
be advised of conflicts between your customizations and application updates;
send back to me bug-fixes and improvements;
receive improvements from other in an efficient way;
upgrade to commercial release easily without loosing your customizations;

For initial download:

git clone http://github.com/massimo-zaniboni/Asterisell.git

For updating/upgrading to new releases:

git commit -a -m "My custom changes."
git pull http://github.com/massimo-zaniboni/Asterisell.git

Then follow the Git procedure to resolve merge conflicts. Usually there will not merge conflicts, because Git tries to preserve both you customization and new version modifications.

In case of troubles, ask to forum. I will update these installation notes, according the signaled problems/suggestions.

Download through HTTP

The traditional download method is:

asterisell-free-stable-3.0.0.tar.gz

or connect to the Asterisell Project Page GitHub for more options.

Asterisell Installation

Asterisell File Installation

Choose a directory where installing Asterisell. For example “/var/www/asterisell3”.

In case of HTTP download, decompress the Asterisell archive.

cd /var/www
tar xfvz <asterisell-installation-file>
mv <asterisell-installation-dir> asterisell3

In Linux Debian make sure that the “www-data” user can read the content of the installation directory:

chown -R :www-data asterisell3
chmod -R g+rwx asterisell3

Asterisell Configuration

Read and change according your needs

  apps/asterisell/config/app.yml

MySQL Database Configuration

Up to date Asterisell is tested only with MySQL DBMS, but the Symfony framework support many other popular open source DBMS.

Database Access Parameters

Update

config/databases.yml
config/propel.ini
scripts/initdb.sh

according your needs using the correct host, username and password for MySQL access.

Initially you must use the root/admin account of MySQL, because configuration scripts will create a new database. Later you can create a specific user for the Asterisell database, in order to limit the capability of the Asterisell user.

The suggested database name is “asterisell3” in order to avoid conflicts with previous or new version of Asterisell needing different database schemas.

How to create a Database User with Limited Access to Asterisell Database

Enter into MySQL shell:

mysql -u root -p mysql

Create a user that can invoke MySQL only from localhost (supposing that Asterisell webserver hosts also the MySQL DBMS):

CREATE USER 'asterisell3user'@'localhost' IDENTIFIED BY 'some-password-here';
GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP ON asterisell3.* TO 'asterisell3user'@'localhost';

This example, supposes that “asterisell3” is the name of created Asterisell database.

Installation Script

The installation script will:

create a new “asterisell3” database;
load the tables;
initializing the Asterisell application with demo data;
fix directory permissions;
reset the Symfony cache;

It must not be used if it is an update of Asterisell, because otherwise all data will be lost.

In any case the script will warn you about this.

Execute

cd scripts
sh initdb.sh

and answer to questions. Typically you must enter two or more times the database access password.

Change Demo Data Later

The installation script will load also some demo data in order to test Asterisell.

If you want later, start with an empty database, you can execute

cd scripts
php reset_db_and_init_data.php init <some-password-for-root-user-access>

for creating an empty database, with only minimal data, and a “root” user with the chosen password for initial login.

The scripts supports other type of data initialization. This command will display all its options:

cd scripts
php reset_db_and_init_data.php

You can also inspect the content of “scripts/initdb.sh” in order to see the details of performed actions.

Optional Configuration for Developers

If you are a developer, and you are changing Asterisell source code, maybe you want to change also its database schema, contained in “config/schema.yml”.

In this case, you must also instruct “config/propel.ini” about how to access the MySQL database. These are the same parameters of “config/databases.yml”, but they are used from a different tool, and so they must be repeated here.

Update “config/propel.ini” according your needs.

Adapt it, using the same parameters of the “databases.yml”. This file contains a lot of parameters, but you must only change these lines:

  propel.database.createUrl  = mysql://localhost/
  propel.database.url        = mysql://localhost/asterisell3
  propel.output.dir          = /var/www/asterisell3

If you have changed the database structure in the file “config/schema.yml”, you must also update the SQL instructions creating the MySQL database. You can use the script “scripts/makedb.sh”. It will recreate the SQL commands and then it call “initdb.sh” in order to load the new database.

Web Server

Installation

The typical installation requires:

Apache2 HTTP server
mod_php5
mod_ssl
MySQL database server

Asterisell use some PHP5 libraries. On Fedora/Centos for example you must install

  yum install php
  yum install php-bcmath
  yum install php-xml

and then execute

  /etc/init.d/httpd restart

Website Configuration

Create the file “asterisell.conf” inside the directory:

“/etc/httpd/conf.d/” or
“/etc/apache2/conf.d/”

The content is something like:

  Alias /your-voip-service /var/www/asterisell3/web/

  <Location /your-voip-service>
    Order allow,deny
    Allow from all 

    # If you have mod_ssl installed 
    # then with these lines you can force the usage of https connections
    # for all Asterisell access.
    # If you omit them, then the passwords are sent in plain text and
    # they can be intercepted from hackers...
    #
    AllowOverride All
    <IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteCond %{HTTPS} off
      RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
    </IfModule>

  </Location>

NOTE: remember to add “/web” to your Asterisell installation directory. This because it is only the “web” subdirectory of Asterisell project that must be part of the web-space.

Restart the apache2 httpd server in order to render active the configurations using a command like:

  /etc/init.d/httpd restart

  /etc/init.d/apache2 restart

If it is all correct then “http://your-voip-service” will display the login form.

PHP Resources

The administrator can invoke heavy jobs, for example graph and stats about calls. In this case it is usefull to increase the resources of PHP scripts inside on-line sessions.

In CENTOS the settings are in “/etc/php.ini”, in Debian are in “/etc/php5/apache2/php.ini”. Change somethiing like:

;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 30     ; Maximum execution time of each script, in seconds
max_input_time = 60 ; Maximum amount of time each script may spend parsing request data
;max_input_nesting_level = 64 ; Maximum input variable nesting level
memory_limit = 128M      ; Maximum amount of memory a script may consume (128MB)

into something like

;;;;;;;;;;;;;;;;;;;
; Resource Limits ;
;;;;;;;;;;;;;;;;;;;

max_execution_time = 180     ; Maximum execution time of each script, in seconds
max_input_time = 60 ; Maximum amount of time each script may spend parsing request data
;max_input_nesting_level = 64 ; Maximum input variable nesting level
memory_limit = 128M      ; Maximum amount of memory a script may consume (128MB)

encreasing the execution time from 30 seconds to 180 seconds.

NOTE: heavy jobs like email sending, are done from the cron-job, in off-line mode, and they are not affected from these settings / constraints.

PHP Speedup

APC is a free, open source framework that caches data and compiled code from the PHP bytecode compiler in shared memory.

I suggest installing it, because it is well tested, and it speeds-up a lot the execution of Asterisell and other PHP applications.

For installing it in Debian

aptitude install php-apc

or in CENTOS follow the instruction of this webpage (up to date the APC package is not part of CENTOS).

IMPORTANT: In order to activate it, the Apache web server must be restarted.

IMPORTANT: Up to date there can be conflicts between APC (version 3.0.19) and SwiftMailer. If after the sending of the first mail, an error message appears in the problem table (something like “Fatal error: Cannot inherit previously-inherited or override constant LEVEL_TOP from interface Swift_Mime_Message”), then try to upgrade APC or disactivate APC.

MySQL

Rates based on CSV files can be rather big, because they contain a lot of data. Asterisell save them in a record, and the SQL command can be rather big.

So you must use a reasonable “max_allowed_packet” size, for communication between PHP and MySQL.

Check that inside “/etc/mysql/my.cnf” there is something like

[mysqld]
max_allowed_packet = 16M

In case of problems, increase this limit, and then restart MySQL (NOTE: during restart new inserted CDR records will be lost).

/etc/init.d/mysql restart

Additional File Access Permissions

If you have not used the default installation script (“scripts/initdb.sh”), then make sure to execute

  ./symfony fix-perms

  chmod -R a+rw log
  chmod -R a+rw cache

in order to enable the write rights on (only) these two directories.

Asterisk Configuration

You must configure Asterisk server to write calls info inside the CDR table of your created MySQL database.

See Asterisk manual.

Account Code

An “accountcode” is the code of the user requesting the call. It is assigned from Asterisk server after the user validation.

There must be a unique “accountcode” for each different customer.

Note: the Asterisk standard documentation pretends that this code is specified on a per-channel basis, but this is not the case in Asterisell configuration. So each accountcode has the same associated customer for every channel. This is also useful/practical in case of the same customer using different channels.

Amaflags

amaflags stands for “Automated Message Accounting flags”.

You must configure Asterisk to use certain “amaflags” in order to classify a call as documentation or to bill or to ignore etc..

As in the case of “accountcode” in theory every different channel can have its set of “amaflags”, but Asterisell supports only a unique set of flags that are assumed valid and with the same meaning for all channels.

Cron Job

Calls Rating and Jobs Processing

Asterisell rates the calls and execute other jobs off-line, using a cron-job process. This allows to use all the resources of the machine, without the constraints of online sessions.

The list of jobs to execute and the various parameters are inside “apps/asterisell/config/app.yml”.

In case of problems during job execution, a mail is sent to the administrator.

User Permissions

The process must be executed from the same user that is associated to the http connection.

On Fedora/Centos it is typically “apache”, on Debian “www-data”. In order to retrieve it, you can enter into Asterisell web interface, select Help menu and PHP-INFO option. Then you can search the element “User/Group”. The first value is the name of the PHP/webserver user.

Cron Job Setting

Supposing the http user is “apache” you can associate to it a cron job using the command

crontab -u apache -e

This command will open an editor. If the defalt editor is “vi”, then digit “:i” (and press enter) in order to start editing, and “:wq” (and press enter) at the end of editing, in order to “write” and “quit/exit” from the editor.

Add this line:

5,10,15,20,25,30,35,40,45,50,55 * * * * sh -c "cd /your-asterisell-dir/scripts/ ; nice php process_jobs.php > /dev/null "

The meaning of the line is to execute at minutes 5, 10, 15, 20, … of every hour the “php rate_all_and_test.php” command inside the Asterisell directory.

Log Rotate

In order to reduce log file size put “asterisell-logrotate” with execution privileges in “/etc/cron.monthly” directory:

  #!/bin/sh
  cd /your-asterisell-install-dir
  ./symfony log-rotate asterisell prod

and set it as an executable file

chmod u+x asterisell-logrotate

Note that “asterisell” after “symfony” command is the name of the application and it is not depends from the directory installation.

VoIP Accounts

You must define an “Asterisk VoIP Account” using Asterisell Web-Interface for each corresponding Asterisell “accountcode”.

In case of missing accounts, Asterisell will be signal the problem, and affected calls will be not rated. When the problem will be fixed, they will be automatically rated, without any loss of data.

Asterisell Customization

Reset of the Cache

VERY IMPORTANT: every time you change the configuration files make sure to execute

 sh configure.sh

in order to clear the Symfony cache, and regenerate Asterisell modules depending from certain configuration values.

Otherwise changes will be not effective, or worse, some modules already in the cache will use the old parameters, new modules will use the new (different) parameters.

The initial installation script (“script/initdb.sh”) execute this action.

Global Behaviour

“apps/asterisell/config/app.yml”

contains params about the behavior of asterisell.

Runtime Params

Inside Asterisell application, the administrator can change many parameters, using the “Main Params” module.

In this case the Asterisell cache must not be cleared.

Appareance Customizations

“web/css/asterisell.css” contains the Cascading Style Sheets;
“apps/asterisell/templates/asterisell_layout.php” contains the html page template;
“web/images/” contains the available images;
“config/properties.ini” contains the project/web-site name;

Jobs/Workflow Customization

Asterisell uses a blackboard approach to process information:

events are put inside the database/blackboard;
customizable/configurable jobs react to events;
jobs can produce new events;

In this way it is possible to add new jobs, changing the behaviour of the application.

If you add new “jobs” make sure to add them to the “apps/asterisell/lib/jobs/userjobs”, otherwise during subsequent update of Asterisell application, all new jobs could be lost or there can be a lot of Git merge conflicts.

Some Jobs like PDF invoicing, email composition and so on require some customization. You can create a custom Job modifying already existing jobs, put them in “apps/asterisell/lib/jobs/userjobs” directory. The more elegant way is to change also the name of the job, add it to the “apps/asterisell/config/app.yml” file, removing the old job.

Source Code

It is normally not needed but you can customize low level Asterisell behavior modifying its source code or Symfony PHP Framework related configuration files.

If you customize Asterisell code, then if you later update Asterisell, you must merge your changes with the changes inside Asterisell code-base. This is easy to do if you choose Git download method.

If you improve Asterisell, you can give back your improvements.

Other Configurations

Every call is associated to a VoIP account. Every VoIP account is associated to a Customer who is the responsible for the account. The Customer is who pays the calls cost. A Customer can have more than one VoIP account.

Every customer or VoIP account can have a Web Access Account. It is a login and a password. If you connect as VoIP account you can inspect only the calls made from you. If you connect as a Customer you can inspect all the calls of your VoIP accounts. If you connect as Admin you can inspect all the calls.

Customer Categories (normal, discounted, etc..)
Dial Peer Telephone Operators
Telephone Operators Prefixes Numbers
Vendors
Rate Methods
Currency Conversions
Customers
VoIP accounts
Web Access Accounts

A rate can be applied to a customer category. In this case it specifies an income from a specific class of Customer. Otherwise it can be applied from a “Vendor”. In this case it specifies a cost due to a specific vendor.

Troubleshooting

File Permissions

Log Directory

Often after upgrades there are problems related to the Asterisell log files inside log directory.

If this file was created from root then the “apache” user is not able to add info to it and the entire Asterisell application is blocked. In this case change the permissions of file with something like:

  cd log
  chmod a+rw asterisell_prod.log
  chmod a+rw asterisell_dev.log

or better change the owner in something like

  cd log
  chown apache asterisell_prod.log
  chown apache asterisell_dev.log

or execute

  ./symfony fix-perms

Try also to restart the web server.

Created Files

During initial Asterisell configuration new files can be created. Check if these files are readable from web-server process. For example on my debian machine I performs

   chown -R :www-data * 
   chmod -R g+rx *
   sh configure.sh

where “www-data” is the group used from my webserver.

Additional Run-Time Debug Info

In case of problems you can enable the development/debug version of Asterisell that shows useful informations about its execution and related problems.

Execute:

  ./symfony enable asterisell dev

and open the url

  http://your-web-url/asterisell_dev.php/login

When finished remember to execute

  ./symfony disable asterisell dev

NOTE: on the contrary of Asterisell production version, in the development version if you change Asterisell source code, you must not execute “sh configure.sh”, because the development version recreate all files every time in order to speed up development at the expense of run-time executions.

NOTE: as in the Asterisell product version, in the development version if you change some configuration parameters you must execute “sh configure.sh” because certain Asterisell modules are regenerated according the configured values.

Run Time Configuration Problems

Every problem encountered from Asterisell during the call rating process is clearly reported to the administrator with hints of how to resolve it.

The presence of problems is signaled also via email to the administrator.

In case of dubious configurations Asterisell advise the administrator and suspend the rate of affected calls.

The rate process is rather robust and error-free regarding ill defined configurations because:

re-rating of calls is always possible;
problems are always signaled;

Security

The end user interacts only with the “Call Report” form. The content of user input fields is checked by a very conservative function that removes every non proper character.

No particular care is put on other forms because they are accessible only from the administrator.

User session handling is managed directly from Symfony and PHP engine.

Feedback

Web servers, PHP environment, libraries, and os on… can interact in strange ways. If something is not working properly let me know!

2010 March 09

Asterisell

open source web application for rating, showing to customers, and billing Asterisk VoIP calls.