1   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;

2   Asterisk Configuration

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

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

3   Web Server

3.1   Installation

The typical installation requires:

• Apache2 HTTP server
• mod_php5
• mod_ssl
• MySQL database server

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

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

and then execute

/etc/init.d/httpd restart

3.2   Directory 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-asterisell-web-name /your-asterisell-installation-directory/web/

<Location /your-asterisell-web-name>
  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 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>

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

/etc/init.d/httpd restart

or

/etc/init.d/apache2 restart

If it is all correct then “http://your-host/your-asterisell-web-name” will display the login form.

4   Asterisell Configuration

Rename

  apps/asterisell/config/_app.yml

to

  apps/asterisell/config/app.yml

and then inspect / change its content.

4.1   Important

After any change of configuration files or PHP code execute

  ./symfony cc

in order to clear the Asterisell execution cache.

IMPORTANT: in YAML files use only spaces and not tabs because they are not allowed!

4.2   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;

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

5   Database Installation

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

5.1   Database Creation

  mysqladmin -u your-root-user-name -p create your-asterisell-db-name

5.2   Access

Rename

config/_databases.yml

to

config/databases.yml

and adapt it to yours needs:

 all:
 propel:
   class:        sfPropelDatabase
   param:
     phptype:    mysql
     host:       your-mysql-server-host--typically-localhost
     database:   your-asterisell-db-name
     username:   your-root-user-name
     password:   your-root-password
     encoding:   utf8

with the correct

• root-user-name and
• asterisell-db-name

Rename

config/_propel.ini

to

config/propel.ini

and adapt it to something like:

propel.project             = asterisell
propel.database            = mysql
propel.database.createUrl  = mysql://localhost/
propel.database.url        = mysql://localhost/asterisell
propel.mysql.tableType = InnoDB

; directories
propel.output.dir              = /your-asterisell-install-dir

5.3   Schema Creation

5.3.1   From YAML to SQL

config/schema.yml

contains the asterisell database schema description. It is defined using the YAML syntax.

Typically you must not change this file, but in case remember to regenerate the SQL counterpart with:

  ./symfony propel-build-model
  ./symfony propel-build-sql

5.3.2   From SQL to Database

In order to create the Asterisell database:

  mysql -u your-root-user-name -p your-asterisell-db-name < data/sql/lib.model.schema.sql

WARNING: this command will delete all previous data inside the previous Asterisell tables / databases.

5.4   Add Asterisell Root User

  cd /your-asterisell-directory/batch
  php create_root your-password

These commands will create:

• an admin user with login “root” and
• password “your-password”

5.5   Insert Demo-Data

FIXME: due to incompatibility with the new version of the Symfony framework the current “demo-data” does not work. So skip this section. However you can use the root-user created in the previous section, but without any demo data…

WARNING: these commands will delete all previous data from the Asterisell database. So do not execute if you have important data on the database.

If you want to populate the database with some demo data then execute:

  cd /your-asterisell-directory/batch
  php insert_demo_data.php

In this case the default admin user is “root” with password “root”.

5.6   Asterisk Database-Related Configuration

Asterisell reads info from the your-asterisell-database-name.CDR table (Call Details Records table). So you must configure Asterisk server to write calls info inside this table.

6   Mail Configuration

Asterisell can send mails to the administrator or to the customers with invoice information. It uses the PHP mail function. In order to enable it you must follow the notes on PHP documentation site .

7   Cron Job

7.1   Calls Rating

Asterisell rates the calls:

• “just-in-time” when users navigate in the reports and
• “off-line” using a cron-job process.

The cron job process is important because it tests also if there is a Customer who does not respect his cost limits.

In case of errors the process sends an email to the administrator as configured in the “apps/asterisell/config/app.yml” configuration file.

The process must be executed from the same user that is associated to http connection. On Fedora it is “apache”, on Debian “www-data”. In order to retrieve it you can execute

ls -l /your-asterisell-dir/log/

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

crontab -u apache -e

Add to the apache user crontab this line:

5,20,35,45 * * * * sh -c "cd /your-asterisell-dir/batch/ ; php rate_all_and_test.php"

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

NOTE: in order to enter the above line using “vi” editor digit:

:i
5,20,35,45 * * * * sh -c "cd /your-asterisell-dir/batch/ ; php rate_all_and_test.php" 
"press ctrl-c" 
:wq

7.2   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

7.3   VoIP Accounts

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

WARNING: If there is an “accountcode” not registered as “Asterisk VoIP Account” then (for current technical limitation) it will not registered on the CDR table.

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

8   Troubleshooting

8.1   Directory Permissions

Often there are problems related files and directories permissions. In this case run

  ./symfony fix-perms

8.2   Log File Permission

Often 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

Try also to restart the web server.

8.2.1   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 or a configuration file you must not execute ”./symfony cc”, because the development version recreate all files every time in order to speed up development at the expense of run-time executions.

8.3   Potential Loss of Data

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

If there is an “accountcode” not registered as “Asterisk VoIP Account” then (for current technical limitation) it will not registered on the CDR table.

8.3.1   Reasons

CDR table has the field “accountcode” that is defined as foreign key of the Asterisell.ar_asterisk_account table.

Symfony generates the schema and it imposes through a database constraint the presence of a corresponding accountcode for each cdr record added.

If there is no accountcode then the MySQL database signals a referential integrity error and it does not permit the insertion of the Call.

So the “nasty effects” is that the CDR table does not contain a potentially billable record.

This type of errors are showed only in the Asterisk server log error messages.

8.4   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;

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

9   Upgrade

All files except “apps/asterisell/config/app.yml”, “config/databases.yml”, “config/propel.ini” will be overwritten with the new version. So create a backup of them before upgrade Asterisell.

Discard the Symfony cache executing

./symfony cc

inside Asterisell root directory.