Intro
This document serves as a more in-depth guide to installing the TABS asterisk billing system and was written by Dave Ross (ImplyIT) using various existing sources of TABS documentation available at the time. If you are fairly new to installing web apps then this document should help you.
This document started as sort of a quick Tabs installation reminder doc for myself, so may find a few hiccups, but feel free to add to this or change anything you think might not be totally right. Feel free to contact me at davidr at implyit dot co dot za.
Tabs Requirements
Well so far we've only done a few Tabs installations but it's fairly straight forward. All of our Tabs installations have been on Gentoo linux boxes, you shouldn't have any problems installing Tabs on other linux flavour's though.
You basically need a linux box running the follwing:
* Apache Web Server (we've tested with apache-2.0.58-r2) - Make sure you have allow_url_fopen set to On in your php.ini file(s). These files are usually located at /etc/php/cli-php5/php.ini and /etc/php/apache2-php5/php.ini. If you've had to make any changes here make sure you restart apache so that the php changes are applied. You also might want to set your max_execution_time php variable to something like 300 seconds (suggested by Tristan). (we're tested with php-5.2.2-r1)
* MySQL Database Server (we've tested with mysql-5.0.42)
* Asterisk (we've tested with asterisk-1.2.21.1) - CDR database support needs to be enabled and must contain entries.
Installing Tabs
1. Download the Latest Tabs Source & set Apache Permissions
Download the latest Tabs source from the Thusa SVN server:
yourserver ~ # svn co http://open.thusa.co.za/svn/tabs/trunk/web
or
Download the latest release from: http://open.thusa.net/svn/tabs/releases/tabs-1.3.0.tar.gz
If you followed the above step, you should now have a directory called web in your home directory. Rename web to tabs and move it to the apache www directory:
yourserver ~ # mv web tabs yourserver ~ # mv tabs /var/www/localhost/htdocs
Now change the ownership of your Tabs web directory to the apache user. One some systems apache might run as 'apache', 'www-data', 'www'... it all depends on the linux distro you are using and how you have configured apache. Check the options 'User' and 'Group' in your Apache httpd.conf config file if you are unsure.
yourserver ~ # chown -R apache.apache /var/www/localhost/htdocs/tabs
2. MySQL Configuration
Create a new MySQL user for tabs to use and give this user full access to the Asterisk CDR MySQL database (usually asteriskcdrdb):
yourserver ~ # mysql -u root -p
yourserver ~ # mysql> grant all on asteriskcdrdb.* to tabsuser@localhost;
yourserver ~ # mysql> set password for tabsuser@localhost=password('password');
yourserver ~ # mysql> exit
Note: replace tabsuser and password with the username and password you wish to use for your new database user. You'll be prompted for the root MySQL user's password here so make sure you know this before running the above.
Ok now would be a good time to back up the client's current Asterisk CDR database (asteriskcdrdb) just incase something goes wrong:
yourserver ~ # mysqldump -u root -p --opt asteriskcdrdb > ~/client_asteriskcdrdb-`date "+%F"`.sql
Next you need to create some new tables required by tabs in the Asterisk CDR database. Import the /var/www/localhost/htdocs/tabs/setup/setup.sql file into asteriskcdrdb:
yourserver ~ # mysql -u tabsuser -p asteriskcdrdb < /var/www/localhost/htdocs/tabs/setup/setup.sql
Note: You will be prompted to enter the tabs user's password, this will be password if you followed the example above in step 4.
3. Tabs Configuration
Copy the configs/config.ini.php.dist to configs/config.ini.php and fire up config.ini.php in your favourite text editor:
yourserver ~ # cp /var/www/localhost/htdocs/tabs/configs/config.ini.php /var/www/localhost/htdocs/tabs/configs/config.ini.php yourserver ~ # vim /var/www/localhost/htdocs/tabs/configs/config.ini.php
These are pretty much the only options you will need to edit in this file, browse through the config file and read the comments next to each option to find out how to tweak Tabs to your specific needs.
[Asterisk] user = "tabsuser" # Username of MySQL user who has rights to 'asteriskcdrdb' pass = "password" # Password of MySQL user who has rights to 'asteriskcdrdb' [DB] user = "tabsuser" # Username of MySQL user who has rights to 'asteriskcdrdb' pass = "password" # Password of MySQL user who has rights to 'asteriskcdrdb'
Once you're done, save the file and exit.
4. Log into Tabs
Fire up your browser to http://<hostname>/tabs/ and enter login with admin / test
5. System Health Checks
This will be a good time to check that everything is in order, point your browser to http://<hostnam>/tabs/system_health.php. This page will show you any errors...etc. Examine closely and fix anything thats gone wrong. If for some reason you receive a wierd php timeout error message when trying to view this page try turning off php_agi_enabled in your config file by setting it to false. Or you might want to increase the php_max_execution_time variable in your php.ini file to something around 300 or so (as per Tristan's suggestion).
6. Configure your Asterisk Extensions in Tabs
While you are logged into Tabs as an administrator, click ADMIN then Bulk User Setup. Here you can add a whole range of extensions, useful when you are adding for examples all extension numbers from 1001 to say 1100. You can also add single extensions at a later stage should you need to add more. Check your asterisk extensions.conf file for a list of the extension numbers you use. Make sure you have Direct Inbound Dialing ticked when using this feature.
It's all great having your extensions loaded, but it's also pretty cool to have actual names assigned to each extension in the Tabs extensions lists. To do this go to ADMIN then Manage Users then Edit User. If you have say 100+ extensions this could take you a while though... up to you.
7. Upload the Telkom Tariff and Zone Files
Telkom offer a free service (w00t) where they can provide you with up-to-date call rates for multiple PABX billing systems. Apparently they update their rates about once or twice a year, so it's a good idea to keep track of this so you can keep your Tabs installation up to date with the new rates.
To get the latest tariff and zone files, go to http://www.telkom.co.za/ and sign up for a user account. Once you have an account, go to http://www.telkom.co.za/mpi and log in with your new account. You can now download the MPI software designed to create the tariff files you require. The MPI software is a windows based program but seems to work OK under wine if you are using Linux/Unix. The software is pretty straight forward to use, basically to generate the tariff/zone file for your specific call costing needs, enter the source number your PABX uses to make outgoing calls then export your new zone/tariff file and upload into Tabs. See below:
Go to ADMIN and click Import Data Files. Upload your zones.csv file and your tariffs.csv files.
Check your zone and ratetimetables tables in the asteriskcdrdb database, if you have entries in these tables then your zone and tariff uploads were successful. If not, try uploading the files again.
8. Lastly - Add a Cron Job for Tabs
Add the following to your /etc/crontab (change to suit your tabs web directory location):
# Tabs 15,45 * * * * root cd /var/www/localhost/htdocs/tabs/process && /usr/bin/php billing_main.php
Note: You can run the billing script manually if need be (useful for testing), run it from a browser or just directly from the command line. You can turn on debug in your tabs config file to see debug messages. Remember though, if debug is enabled, the billing script won't actually write the changes to the database so make sure you turn debug off afterwards to let Tabs do it's thing again.
9. Done
That's it. Tabs should be running fine though, if you run into any problems see the section Troubleshooting below. Now would be a good time to change that default admin password to something a little more complex than test.... ;)
Troubleshooting
If you've done the above steps, run your billing script and Tabs still won't log the calls correctly then something could have gone wrong with your zone and tariff file uploads. Try uploading your zone and tariff files again, this has worked for me in the past. If this still doesn't help, take a look at the cdr table in your asteriskcdrdb database. If you see cost entries of -2 then you have a problem. Tabs tried to run the billing script but ran into problems (maybe you should have enabled debug in the config file and run the billing script manually first...), so it set the costs for CDR entries to -2. This tells Tabs not to try process these entries. Ok. Try setting the entries with a cost value of -2 to -1 and Tabs will try process the entries again. Here's a quick MySQL statement to do this:
UPDATE cdr SET cost=-1 WHERE cost=-2;
Remember, the billing script will only be successful if your CDR zones and ratestimetable database tables have entries in them.
Also, when adding extensions, take note that you cannot have 2 users/extensions configured with the same "handle", even if their asterisk extension numbers are different.
Notes Regarding Direct Number Dialing & Extension Numbers
If you tick direct number dialing when adding extensions (Eg. 100 to 200, it will extensions 0100, 0101...0200. This can cause problems when tabs tries to search through your CDR database if your extensions are infact '101' and not '0101'. To fix, go into manage users and update the extensions handle and extension number manually.
This document was last updated by Dave on the 1st April 2008
