Asterisell Management

Management tool

Instances are administered from the Management Tool installed in the host.

Management commands

The most useful management commands are described in

fab help

Inside every instance, there is also a low level management shell. For viewing the available commands:

fab help
fab connect:INSTANCE_NAME
php asterisell.php

You must not know all of them, because they are used mainly during development. Some useful commands are:

  • php asterisell.php cron force-execution-of-all-jobs for forcing the execution of all pending jobs, also jobs scheduled to start later
  • php asterisell.php data backup make a full backup of the database, dumping its content on a separate file
  • php asterisell.php debug jobs run jobs in debug mode, signaling more problems respect normal mode$

Docker management

Asterisell does not use Docker in the suggested way, because it puts in the same container all the required servers. In any case log rotation, and other maintanance tasks are regularly done on the server, because it is managed by supervisord.

You can see how the container is configured studying the content of directory fabric_data/config_files_templates/docker.

One disavantage of a monolithic Docker container, it is that for each instance there will be a distinct MySQL server running and using a lot of RAM, mainly for caching the DB data. In case of multiple instances, it should be better using a unique database server, sharing the RAM between different instances.

Up to date there is no automatic update of the Docker container Linux system. So you can do it manually, in a non-dockerized way, executing something like

fab connect:INSTANCE
yum update

For seeing the active Docker containers, and managing them, execute

docker ps -a
docker inspect SOME_CONTAINER_NAME
docker restart SOME_CONTAINER_NAME

# warning: you are removing a container
# but the VOLUME with data will remain

See the instance deletion howto for a description of how to remove completely an instance, and its volume with data.

Application upgrade

Git repository upgrade

Instances can be upgraded to a new version of Asterisell, using the Instance Management Tool, and Git.

The Instance Management Tool is a Git repository. Thanks to this Asterisell official versions can be merged with local customizations.

The passage are something like this:


# view pending local changes
git status

# add new files

# save local customizations
git commit -a -m "Custom settings."

# download a new version and merge
git pull

In case there are conflicts to merge, Git signal them to you. Then you must:

  • git status for seeing the files with problems
  • edit one of the file with problems, searching for strings like >>>>> inserted from Git
  • git add <file-with-problem> for signaling that the problems in file are fixed
  • git status for seeing if there are other files with problems
  • git commit -a -m "Resolved conflicts." for merging the changes, when all the files are fixed

Instances upgrade

When the Instance Management Tool contains the last version of Asterisell, with applied customizations, single instances on Docker containers can be upgraded.

fab help

returns the list of upgradable instances.

The command

fab upgrade_app:INSTANCE

can be used for upgrading an instance.

For upgrading all the instances

fab upgrade_app:all

Change of configurations

Instance configurations are on fabric_data/ file.

After changing the file you must upgrade the instances, using

fab upgrade_conf:INSTANCE

Some configurations (signaled in the comments of the same file) requires a restart of the Docker container

fab restart:INSTANCE

Data backup

Quick undo/restore

Asterisell saves partial copies of rates, and organization/customer changes, in case they must be quickly restored after a bad change from an administrator. It is a sort of UNDO function.

The web interface contains info on how restoring quickly this information.

Container data backup

Asterisell performs a daily backup of configurations, reports, rated CDRs on the directory data_files/messages/backup, that can be the backuped on external hosts.

It is a fast incremental backup of data, storing always the last state of the system. From the content of this directory, it is possible recreating the complete Asterisell instance.

The only disavantage it is that the CDRs are repeated in many places:

  1. source CDRs in ar_source_cdr table, stored in VoIP server native format. They are compressed from TokuDB engine.
  2. rated CDRs in ar_cdr table, stored in Asterisell format. They are compressed from the TokuDB engine.
  3. daily CDRs backup copy of source CDRs in VoIP server format
  4. daily CDRs backup copy of rated CDRs in Asterisell format

Nowdays storage is cheap, so in this case reliability and full access to data, is favored respect reduction of data duplication.

Maybe in future a compressed file system can be used, for reducing further the space usage.

Remote backup

Create a backup server, distinct from Asterisell server.

Install on it the rdiff-backup utility.

Create a unix backup user, something like asterisell_backup.

Enable the automatic SSH login from Asterisell instance, to this server, using asterisell_backup user.

In Asterisell deploy management directory, configure a new job for making the backup. Create the file apps/asterisell/lib/jobs/data_backup/MyRDIffBackupJob.php

You can configure also additional parameters, consulting the RDiffBackupJob source code. This command by default will make an incremental backup using an rsync encrypted protocol, and retaining old versions of the files (in change-diff compressed format) for 7 days before deleting them.

Add the backup job to the list of jobs to execute. In file fabric_data/directly_managed_instances/<your-instance-code>/, find the definition of your instance, and add a line like this:

custom_export_cdrs_jobs = [ 'MyRDiffBackupJob' ]

Upgrade your instance

fab help
fab upgrade_conf:INSTANCE

If you want force the test of the backup

fab help
fab connect:INSTANCE
php asterisell.php cron force-execution-of-all-jobs
php asterisell.php run jobs

The Asterisell job will backup all important directories:

  • /etc of your instance
  • instance/web/uploads
  • instance/data_files/messages/backup

Backup of management tool

The backup of instances does not suffices, because you need also a backup of the Instance Management Tool, on your host system, containing all the configurations, for recreating the instances.

In the host add this file /etc/cron.daily/ with a content like this content




rdiff-backup  --create-full-path $SRC_DIR $BACKUP_USER@$BACKUP_SERVER::asterisell5-deploy
rdiff-backup  --remove-older-than 12M $BACKUP_USER@$BACKUP_SERVER::asterisell5-deploy

Make it executable

chmod u+x /etc/cron.daily/

Test it


Data restore

Recreate an instance of the application.

Put data backup

fab help
fab connect:INSTANCE

# TODO RESTORE_DATA IN DIRECTORY data_files/messages/backup

php asterisell.php data restore

fab upgrade_conf:INSTANCE


Asterisell tries to enforce security applying different strategies.

Every Asterisell instance exposes two distinct PHP WEB applications:

  • admin application
  • customer application

The admin application is accessed using a MySQL database user with complete rights on the database.

The customer application is accessed using a MySQL database user, that can only read the content of the table, but he can not write anything, except the information about the read reports.

The Asterisell code accessed from Customer is very few, and it is carefully reviewed. All input strings are sanitized both from Symfony framework code, and from Asterisell code.

The Asterisell code accessed from Admin is very complex, but it is on a separate application, and it can be executed only from Admins, having no reason to compromise the application.

The Asterisell code processing the calls, is called from the cron processor at regular interval. The code process the CDRs, and there is no info inserted explicitely from the customer, so it can not be directly compromised.

A customer can change his password. He has access only in append mode (“insert mode”), to a separated table, containing only the requests of change of password, and nothing else.

Up to date, Asterisell jobs are executed using the root account, instead of a specific account, with limited privileges. This is not best practice, but as mitigation, there is the fact that there is no input from regular users, but only from administrators.

How exporting data to a different container

These are guidelines that must be adapted to your specific case.

First create a destination container, with maybe correct configurations, but without real data inside.

Then on the source container:

fab connect:your-source-instance
# if it is a Docker image

php asterisell.php data backup

If the source container is in a Docker image you had to move the backup file to the hosting file system:

docker inspect your-source-container-name | grep volume
# you obtain a result like
# > "/var/lib/docker/volumes/af44ab14c07c8322027dedbb8ed2f24cbc2e02ab439235a9bb01a/_data",

mv /var/lib/docker/volumes/af44ab14c07c8322027dedbb8ed2f24cbc2e02ab439235a9bb01a/_data/tmp/your-backup-file.sql .

Then you had to move the file to your destination Docker container

docker inspect your-dest-instance | grep volume
# you obtain a result like
# > "/var/lib/docker/volumes/14c07c8322027dedbb8ed2f24cbc2e02ab439235a9bb01a/_data",

mv your-backup-file.sql /var/lib/docker/volumes/14c07c8322027dedbb8ed2f24cbc2e02ab439235a9bb01a/_data/tmp/your-backup-file.sql .

fab connect:your-dest-instance

php asterisell.php cron disable
mv asterisell.php asterisell_disable_cron.php
# force the block of the cron-job

# determine the password for accessing the database using
cat config/database.yml

# NOTE: drop database so all triggers and indexes are deleted,
# because during upgrade there can be indexes with different names
# and there can be repetitions
mysql -uroot -psomepassword
drop database your-dest-instance;
create database your-dest-instance;

# import the data
mysql -uroot -psomepassword your-dest-instance < /var/tmp/your-backup-file.sql
rm /var/tmp/your-backup-file.sql

# restore the entry point
mv asterisell_disable_cron.php asterisell.php
php asterisell.php cron disable

fab upgrade_conf:your-instance
# this will apply database upgrade jobs,
# and this enable the cron job again