The Asterisk A2Billing Calling-Card-Platform Documentation
Transcription
The Asterisk A2Billing Calling-Card-Platform Documentation
The Asterisk A2Billing Calling-Card-Platform Documentation Arezqui Belaid areski @NOSPAM gmail.com The Asterisk A2Billing Calling-Card-Platform Documentation by Arezqui Belaid Copyright © 2005 Copyright @ 2005 The Asterisk Calling Card platform A guide to the basics of using A2Billing This document may be distributed subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/ ) Revision History Revision 0.1 $Date: 2005/19/15 16:29:00 $ Table of Contents 1. Introduction .......................................................................................................................1 General concept of the calling card platform ...........................................................1 AreskiCC, is it the same ?............................................................................................1 Prerequisite knowledge and skills .............................................................................1 What to expect ? ...........................................................................................................1 Key Solution Features..................................................................................................2 How does it work (briefly)..........................................................................................3 Licence ...........................................................................................................................4 2. Preparing your system for A2Billing ............................................................................5 Choose an Operating System / Distribution ...........................................................5 Install Asterisk & have it up running........................................................................5 Get Asterisk from precompiled Binary Packages ..........................................5 Get Asterisk from sources & compile ..............................................................5 Link for Asterisk installation ............................................................................6 Linux Requirements.....................................................................................................6 Required Packages..............................................................................................6 Verify the server installation .............................................................................6 Conclusion.....................................................................................................................8 3. Getting & Installing A2Billing ....................................................................................11 Getting the tarball ......................................................................................................11 Create the application’s database - Postgres ..........................................................11 Create A2Billing system/database user........................................................11 Create the database and populate it with the sql dump - postgresql .......11 Create the application’s database - Mysql ..............................................................12 Create A2Billing system/database user........................................................12 Create the database and populate it with the sql dump - mysql...............13 Install the file for the a2billing configuration.........................................................13 Install the file for the currencies table .....................................................................14 Install the php web management interface ............................................................15 Install management interface..........................................................................15 Configure & customize the Interface : a2billing.conf ..................................15 Files / directory right.......................................................................................16 SIP/IAX friends include ..................................................................................17 Configure the manager ....................................................................................17 Configure MusicOnHold.................................................................................17 Give a try! ..........................................................................................................18 Increase security of the Admin interface with an htaccess.........................18 Install the customer web interface ...........................................................................18 Install customer web interface ........................................................................18 Install The AGI components : IVR CallingCard application ...............................18 Install ..................................................................................................................19 Install Sounds files............................................................................................19 Configure & customize the AGI : a2billing.conf ..........................................19 Configure extensions to run A2Billing into Asterisk ..................................21 4. Specific information for Installation according to the distribution......................23 RedHat .........................................................................................................................23 Files Locations differences...............................................................................23 Commands Syntax differences .......................................................................23 Fedora ..........................................................................................................................23 Debian ..........................................................................................................................23 Ubuntu .........................................................................................................................23 CentOS .........................................................................................................................23 Mandriva .....................................................................................................................23 Suse...............................................................................................................................23 Dos 5.0..........................................................................................................................23 Windows 3.11..............................................................................................................23 iii Xbox..............................................................................................................................23 5. User Guideline ................................................................................................................25 Entities interaction in the callingcard platform .....................................................25 Create customer/card................................................................................................26 Card properties .................................................................................................26 CallerID Authentication ..................................................................................27 Billing Engine..............................................................................................................27 Introduction.......................................................................................................27 TariffGroup ........................................................................................................28 Ratecard .............................................................................................................28 Rate .....................................................................................................................28 Trunk ..................................................................................................................28 Import Ratecard ................................................................................................28 SIP/IAX Friends .........................................................................................................28 Make card recharge & notify payment....................................................................29 Reporting tools ...........................................................................................................29 cdr report ...........................................................................................................29 calls compare .....................................................................................................29 monthly traffic...................................................................................................29 daily load ...........................................................................................................29 Invoice ................................................................................................................29 Edit/Add administrator (& define ACL) ...............................................................29 Customer web interface ............................................................................................29 6. Contribution ....................................................................................................................31 Code contribution ......................................................................................................31 Development Donation .............................................................................................31 Audio files & Translations.........................................................................................31 Bounty..........................................................................................................................31 Feedback & success story ..........................................................................................31 7. Conclusion .......................................................................................................................33 Conclusion...................................................................................................................33 8. FAQ (Frequent Asked Question) .................................................................................35 FAQ installation..........................................................................................................35 FAQ Utilization...........................................................................................................35 iv Chapter 1. Introduction General concept of the calling card platform The phone cards are a well-known product in telecommunication sector, which can be employed from any country where a number of access is available. The phone calling card is a printed card containing the access information and the information of account to make international as well as national calls. The Card carry a limit on the maximum use and are normally sold by on Internet or in the street distribution. Today the Calling Cards is one of the top business in the VoIP Industry and A2Billing with Asterisk is trying to complete the needs for large, medium-sized companies and start-up who appreciate the Calling Cards business model. A2Billing allows to craft a calling card management system over your Asterisk Server. It’s powerful calling card platform can be easily deployed with Asterisk, it is providing wide set of tools to manage a complex & advanced calling card system! With A2Billing & Asterisk, prepaid/postpaid calling card services are just as easy to implement as to make a few entries through a web interface. With its user-friendly, powerful functionality, A2Billing try to end to be the preferred billing software for Calling services. As Asterisk, the most valuable of A2Billing is the open source nature. The source are provided and the soft can be enhanced by the asterisk community or peoples that use it. This concept will ensure that the soft will grow up and continue to fill the billing needs of the asterisk users. This solution aims to manage all aspects of the calling card service and it takes care of the calling card service through real-time integration for card activation, authentication and debiting the account balance of users. The solution provides a Web interface for administrator to manage all the billing system and for customer to see their own call history, balances and user data. AreskiCC, is it the same ? Many of you knew this application under the name of AreskiCC... well after little bit of thinking, I realize it was not such good idea to use the name of the author as the name of the product. It was kind of difficult to find a name for this software... Anyway get confused to see my name associated to a software, I finally opted for another name that I believe more attractive :D A2Billing is the Version 3 of AreskiCC. We will try to be more professional with this label and I hope to see other developers to join/get involved to the project. Prerequisite knowledge and skills Configuring the Asterisk system requires more than a passing familiarity with several technical concept, most notably Linux Installation and configuration, as well as an understanding of the Telephony. Concerning A2Billing is a bit easier as the application is only PHP based with Database. A2Billing will require a working installation of Apache with PHP, different PHP modules (described later), a postgresql or mysql server and of course, a working installation of the Asterisk PBX software :D In this document, we will try to be as precise as possible, by describing each single step of the installation. If any section is not well/enough described, we will invite you to notify us and we would greatly appreciate helps, such as completing the documentation, etc... 1 Chapter 1. Introduction What to expect ? A2Billing is a complex software and it can take a little while to get use to. It’s not yet well-documented (not at the moment I am writing this sentence), that’s what we are trying to resolve with the aids of this handbook. We don’t pretend A2billing is easy to install for someone with poor linux basics, so please before starting to flame over the mailing-list or the wiki (I saw there is always some expert to make public offense :D) * What to expect ? Once you will have install and after you will play a bit with, you will discover a flexible billing software that is suitable for many different use, with a great rate-engine, reporting features, invoice generation, customer followup, etc... Key Solution Features AreskiCC includes tens of powerful features to fit your needs & customize your calling card platform. Below, the most popular features are listed and described briefly. • * * Authenticate with the use of a Cardnumber the Cardnumber can also be defined as accountcode into sip.conf, iax.conf, etc.. • * * take care of multiple calls using the same Cardnumber • * * Caller gets informed about his credit Announce the remaining credit • * * Caller is requested to enter a destination number • * * Announce the maximal call time for the given destination number It calculates the remaining duration of the actual call (based on tariffrate tables), informs the caller about this and sets a timeout • * * Interrupt the call if the card balance gets zero Warn the caller about the call interrupt X seconds before the call gets interrupted • * * It connects the Caller to the destination through the configured trunk note : different trunks can be configured and associated by prefix • * * After disconnecting the call AGI updates the credit and stores the concerning Call-Detail-Records with CallingPartyNumber, CalledPartyNumber, CallSetupTime, Duration, Charge and the remaining credit • * * Reporting - Monthly & daily reporting - monthly traffic reports (pie graph) - Daily load compare call-load with previous days - criteria definition for reporting - export report to PDF & CSV - Generate Invoices to PDF format • * * Powerful rate-engine - LCR & LCD management - Billing Increment - Progressive Rate - Scheduled Rates (days of the weeks) - Expiration rates - importation ratecard from csv file • * * Simultaneous access for same card 2 Chapter 1. Introduction • * * SIP/IAX Friends Management • * * Generate conf file for SIP/IAX Friends • * * Reload Asterisk through UI & manager • * * IVR Customization - many options such as use DNID, Directcall, saybalance, ... • * * Free Call on SIP/IAX Friends on AGI (press 9) • * * USE DNID to pass through calls • * * Internal help/info • * * Multi-language • * * post-pay & prepay • * * callerID authentication • * * Setup musiconhold according to the destination ;) • * * failover trunk configuration • * * Recurring service over the card • * * Complex expiration setup for the card • * * Voucher support • * * Currencies support management - use www.oanda.com for currencies list How does it work (briefly) • 1. The administrator generates cards in series • 2. The Serial/Cardnumber numbers can be exported for outsourced printing of cards • 3. The customer call the asterisk server with a supported client or dials a local or toll-free access number provided to him or show on the card. • 4. Asterisk answers the call and prompts the caller to enter his PIN number. • 5. After validating the PIN through the VoIP billing server, Asterisk announces to the caller his account balance and invites him to dial a destination number. • 6. Upon entering such number, Asterisk announces the amount of calling time available and connects the caller to the destination number according to the predefined ratecards & trunks. • 7. Upon call completion, Asterisk save advanced CDR information for the call that would be used for billing, reporting and invoice. 3 Chapter 1. Introduction • 8. When the balance bottoms out, the service is disabled in real time and the customer must then recharge the account. Licence This software is released under GNU GPL license. The GNU GPL license can be found at : http://www.gnu.org/copyleft/gpl.html This code is distributed WITHOUT ANY WARRANTY OF ANY KIND. 4 Chapter 2. Preparing your system for A2Billing This chapter aims to help you to prepare you system for A2Billing. Choose an Operating System / Distribution The Asterisk PBX was originally designed for Linux Operating system. Due to the Asterisk popularity, it has since been ported to BSD and OS X. Nevertheless, Digium PSTN card are designed to work on Linux i386. It’s recommended to peoples to use Linux. I personally love Fedora :D but it’s a question of preferences. Install Asterisk & have it up running Information are from the Wiki : http://voip-info.org Get Asterisk from precompiled Binary Packages There are precompiled binary packages available for download, created by nonDigium contributors: • RPM packages for index.php?page=Asterisk+RPM Linux : http://voip-info.org/tiki- • DEB packages for index.php?page=Asterisk+DEB Linux : http://voip-info.org/tiki- • Asterisk.pkg install package for http://www.astmasters.net/stuff/Asterisk.pkg.tgz MacOS X : Get Asterisk from sources & compile You can download it from several mirror servers or use cvs to checkout the release version: cd /usr/src export CVSROOT=:pserver:[email protected]:/usr/cvsroot cvs login - the password is anoncvs. cvs co -r v1-0 asterisk libpri zaptel or cvs -d :pserver:[email protected]:/usr/cvsroot checkout -r v1-0 asterisk libpri za Now, you have to compile the sources. cd /usr/src/libpri make && make install cd /usr/src/zaptel make && make install cd /usr/src/asterisk make && make install 5 Chapter 2. Preparing your system for A2Billing Link for Asterisk installation • Asterisk OS Platforms index.php?page=Asterisk+OS+Platforms http://voip-info.org/tiki- • 10-minute guide to index.php?page=Asterisk+quickstart http://voip-info.org/tiki- • Step-by-step Installation index.php?page=Asterisk+Step-by-step+Installation http://voip-info.org/tiki- • Asterisk Download index.php?page=Asterisk+Download http://voip-info.org/tiki- • Asterisk Compile http://voip-info.org/tiki-index.php?page=Asterisk+Compile Asterisk Linux Requirements Required Packages • # Apache • # PHP • # POSTGRESQL or Mysql • # use phpagi 2.14 included (http://phpagi.sourceforge.net) • # need GD library • # jpgraph_lib (included) Verify the server installation Verify that Asterisk is working Are you able to make calls between 2 sip/iax friends registered on your Asterisk pbx? Are you able to make an outgoing call through one of your registrars (e.g. fwd...) from a SIP phone? If you answered no to any of the above questions, you should check your Asterisk configuration, that is unfortunately not covered in this document. If you need information about Asterisk configuration, we will advice your to read the asterisk Handbook (http://www.digium.com/handbook-draft.pdf) Verify Apache/PHP installation APACHE Check if the httpd server is install with "rpm -qa|grep httpd" if you don’t find httpd, it means that you didn’t find it, lol :) To install the Apache server, you can use quickly YUM or APT-GET, or you can find the appropriate packages for your distribution and install it. apt-get install httpd Or yum install httpd Check httpd status if it’s install already ### /etc/init.d/httpd status (On RedHat Linux 9 & Fedora) Normally, you should get something like this 6 Chapter 2. Preparing your system for A2Billing ### httpd (pid 7486 3710 3709 3708 3707 3706 3705 3704 3703 3700) is running... if you see that it’s not running### /etc/init.d/httpd start Starting httpd: [ OK ] To enable apache server permanently to start after reboot, please check chkconfig or something similar if you are running another distro: if you don’t check your apache configuration. PHP check if it’s install #### rpm -qa | grep php you should get something like php-imap-4.3.10-2.4 php-pgsql-4.3.10-2.4 php-4.3.10-2.4 php-mysql-4.3.10-2.4 php-mbstring-4.3.10-2.4 php-mmcache-4.3.10_2.4.6-4.1.fc2 php-pear-4.3.10-2.4 PHP Requirements are : php, php-pgsql or php-mysql, perhaps php-gd (if it’s a recent distro). If one of those are missing you will have to install it, see YUM or apt-get or by getting the appropriate packages. CentOS & Debian will probably request a little change in the php.ini (vi /etc/php.ini) you will have to add the following line where extension are defined. extension=pgsql.so (don’t forget to reload apache after changes) Verify your postgresql installation Check if postgres is install : # rpm -qa | grep postgres you should have something like this # postgresql-server-7.3.2-3 # postgresql-libs-7.3.2-3 # postgresql-7.3.2-3 To install postgresql, if there are well configured, you can use YUM or APT-GET, if not you will have to find the appropriate packages and install it. apt-get install postgresql postgresql-server or for CentOS apt-get install rhdb Check postgresql status (On RedHat): /etc/init.d/postgresql status Or service postgresql status Or with CentOS /etc/init.d/rhdb status If it doesnt run yet, you have to start postgresql (On RedHat): /etc/init.d/postgresql start Or service postgresql start Or with CentOS /etc/init.d/rhdb start Normally, you should get this on RedHat Starting postgresql: [ OK ] To enable postgresql server permanently to start after reboot, please check chkconfig (chkconfig postgresql --level 2345 on) 7 Chapter 2. Preparing your system for A2Billing Verify your Mysql installation Check if Mysql is install : # rpm -qa | grep mysql you should have something like this #mysql-3.23.58-16.FC3.1 #mysql-server-3.23.58-16.FC3.1 #mysql-devel-3.23.58-16.FC3.1 To install mysql, if there are well configured, you can use YUM or APT-GET, if not you will have to find the appropriate packages and install it. apt-get install mysql mysql-server Check mysql status (On RedHat): /etc/init.d/mysql status Or service mysql status If it doesnt run yet, you have to start postgresql (On RedHat): /etc/init.d/postgresql start Or service postgresql start Or with CentOS /etc/init.d/rhdb start Normally, you should get this on RedHat Starting postgresql: [ OK ] To enable postgresql server permanently to start after reboot, please check chkconfig (chkconfig postgresql --level 2345 on) Let’s prepare our postgresql database server for A2Billing Let’s verify that postgresql allows access to all local users to all databases : vi /var/lib/pgsql/data/pg_hba.conf make sure that it ends with local all all trust host all all 127.0.0.1 255.255.255.255 trust host all all your-webserver-ip 255.255.255.255 trust vi /var/lib/pgsql/data/postgresql.conf Make sure you uncomment and set [] tcpip_socket = True port = 5432 Remember the hosts were your postgresql and Apache are must trust each other or at least open this port if there is a firewall between your database and your web server. /etc/init.d/postgresql restart Or service postgresql restart Or with CentOS /etc/init.d/rhdb restart Stopping postgresql service: [ OK ] Starting postgresql service: [ OK ] 8 Chapter 2. Preparing your system for A2Billing Conclusion You should have a fully installed Linux distribution working with Asterisk. The next chapter will deal with obtaining and installation A2Billing. 9 Chapter 2. Preparing your system for A2Billing 10 Chapter 3. Getting & Installing A2Billing This chapter aims to help you to install A2Billing on your system. Getting the tarball (Note: Check http://www.areski.net/a2billing to find the most recent version!!!) cd /usr/src mkdir a2billing cd a2billing wget http://www.areski.net/Open_A2Billing_version_Raccoon.tar.gz Unpack the tarballs tar -xzvf Open_A2Billing_version_Raccoon.tar.gz Create the application’s database - Postgres Create A2Billing system/database user Login as postgres and add database user su - postgres create the postgres user, we use a username ’a2billinguser’ but you can use whatever you want createuser -W a2billinguser You will be asked if the user can create databases, answer yes You will be asked if the user can create other users, answer no Use whatever password you want Create the database and populate it with the sql dump postgresql Create a2billing database createdb -O a2billinguser a2billing (that is an O for Owner) Login to new database to check ownership psql -d a2billing \du List of database users 11 Chapter 3. Getting & Installing A2Billing User name | User ID | Attributes -------------------------------------------------a2billinguser | 100 | create database postgres | 1 | superuser, create database (2 rows) \q (to exit from database) Import data schema into new database psql -d a2billing -f /usr/src/a2billing/a2billing-pgsql-schema.sql -U a2billinguser -W it will ask you for password then input the password you set before this step. This will create all the table with the ’a2billinguser’ as Owner. * Let’s verify database installation psql -d a2billing -U a2billinguser -W a2billing=> SELECT * FROM ui_authen; userid | login | password | groupid | perms | confaddcust | name | direction | zipcod --------+-------+------------+---------+-------+-------------+------+-----------+-----2 | admin | mypassword | 0 | 1023 | | | | | 1 | root | myroot | 0 | 1023 | | | | | (2 rows) If you got the above, congratulations, you have installed correctly the postgresql database (that was the most difficult part). If you didn’t, take a break, drop the database and start over. To resume what we need : • Postgres must be running. • Postgres must trust local connections from the user a2billinguser on the database a2billing using a supported auth method(pg_hba.conf). • Postgres must allow tcpip connections on port 5432 (postgresql.conf, firewall). • The a2billing database must be owned by the application’s user ( in our case, the user a2billinguser). Create the application’s database - Mysql Create A2Billing system/database user Login on mysql database and add a new mysql database user As root mysql mysql 12 Chapter 3. Getting & Installing A2Billing create the mysql user, we use a username ’a2billinguser’ but you can use whatever you want SQL queries to create the new mysql user : GRANT ALL PRIVILEGES ON *.* TO ’a2billinguser2’@’%’ IDENTIFIED BY ’a2billing’ WITH GRAN GRANT ALL PRIVILEGES ON *.* TO ’a2billinguser2’@’localhost’ IDENTIFIED BY ’a2billing’ W GRANT ALL PRIVILEGES ON *.* TO ’a2billinguser2’@’localhost.localdomain’ IDENTIFIED BY ’ \q (to quit) More information about "Adding new user accounts to MySQL" can be found : http://dev.mysql.com/doc/refman/4.1/en/adding-users.html Create the database and populate it with the sql dump - mysql Create a2billing database mysqladmin create mya2billing -u a2billinguser -p (prompt will ask you for password, in our case enter ’a2billing’) Import data schema into new database mysql mya2billing -u a2billinguser -p < /var/www/html/all/Open_A2Billing/a2billing-mysq (it will ask you for password then input the password you set before this step. This will create all the table with the ’a2billinguser’ as Owner.) Let’s verify database installation mysql mya2billing -u a2billinguser -p (prompt will ask you for password, in our case enter ’a2billing’) mysql> SELECT * FROM ui_authen; +--------+-------+------------+---------+-------+-------------+------+-----------+----| userid | login | password | groupid | perms | confaddcust | name | direction | zipc +--------+-------+------------+---------+-------+-------------+------+-----------+----| 2 | admin | mypassword | 0 | 1023 | NULL | NULL | NULL | NULL | 1 | root | myroot | 0 | 1023 | NULL | NULL | NULL | NULL +--------+-------+------------+---------+-------+-------------+------+-----------+----2 rows in set (0.00 sec) If you got the above, congratulations, you have installed correctly the mysql database. If you didn’t, take a break, drop the database and start over. Install the file for the a2billing configuration Place the file a2billing.conf into your /etc/asterisk/ directory mv /usr/src/a2billing/a2billing.conf /etc/asterisk/. 13 Chapter 3. Getting & Installing A2Billing This file contains all the configuration information for the A2Billing platform : Database connection parameters, AGI behaviour, Web interface Custom, etc... First, let’s start by setup the database access. vi /etc/asterisk/a2billing.conf This file contains different section to configure the several part of the application : • section [database] : To configure the database connection • section [webui] : To customize the web user interface • section [recprocess] : configuration for the Reccurring process (cront job) • section [agi-confX] : configuration for the AGI, several configurations can be defined, ie "agi-conf1", "agi-conf2", etc... the groupid parameter will define which configuration to use. Usage : DeadAGI(a2billing.php|%groupid%) by default agiconf1 is used First let’s configure the database connection in the section [database], for this we have to change the username=a2billing,database=a2billing and password="yoursecretpassword" [database] hostname=localhost port=5432 user=a2billinguser password=a2billing dbname=mya2billing dbtype=postgres Description of the parameter • * HOST: This is the Database host name. Example: localhost • * PORT: Database port. Example: 5432 • * USER: Username to access to the database. Example: a2billinguser • * PASS: Database password of the user. Example: password • * DBNAME: Name of the Database. Example: a2billing • * DB_TYPE: Database type. support: postgres (mysql is also supported) Install the file for the currencies table Place the file rates.inc into your /etc/asterisk/ directory mv /usr/src/a2billing/rates.inc /etc/asterisk/. This file contains all the currencies information for the A2Billing platform This file can be automatically updated by a cront process. Please read the future section "Cront -> Currencies table update" to know how to configure your system to update this rates.inc automatically. File sample of rates.inc: $currencies_list[’USD’][1]="US Dollar"; $currencies_list[’USD’][2]="1.0000"; $currencies_list[’EUR’][1]="Euro"; 14 Chapter 3. Getting & Installing A2Billing $currencies_list[’EUR’][2]="1.2025"; $currencies_list[’FRF’][2]="1.2025"; $currencies_list[’GBP’][1]="United Kingdom ... ... ... Install the php web management interface Install management interface Place the directory "A2Billing_UI" into your DocumentRoot directory of your web server. mv -rf /usr/src/a2billing/A2Billing_UI /var/www/html/. For you information you can check the apache DocumentRoot in the httpd.conf file # DocumentRoot: The directory out of which you will serve your # documents. By default, all requests are taken from this directory, but # symbolic links and aliases may be used to point to other locations. DocumentRoot "/var/www/html" Configure & customize the Interface : a2billing.conf To configure the Web interface you will need to make changes in the section [webui] ; configuration for the Web interface [webui] ; Path to store the asterisk configuration files buddyfilepath = /etc/asterisk/ ; Email of the admin (not used yet) email_admin = [email protected] ; Card lenght len_cardnumber = 10 ; Voucher lenght len_voucher = 15 ;amount of MOH class you have created in musiconhold.conf : acc_1, acc_2... acc_10 clas num_musiconhold_class = 10 ;MANAGER CONNECTION PARAMETERS manager_host = localhost manager_username = myasterisk manager_secret = mycode ; Allow to display the help section inside the admin interface (YES - NO) 15 Chapter 3. Getting & Installing A2Billing show_help="YES" ; Parameter of the upload ; PLEASE CHECK ALSO THE VALUE IN YOUR PHP.INI THE LIMIT IF 2MG BY DEFAULT my_max_file_size_import = 512000 my_max_file_size = 512000 ; in bytes ; Not used yet, goal is to upload files and use them directly in the IVR dir_store_audio = /var/lib/asterisk/sounds/a2billing ;Parameter of the upload my_max_file_size_audio=3072000 ; in bytes ; the file type extensions allowed to be uploaded such as "gsm, mp3, wav" (separate by file_ext_allow = gsm, mp3, wav ; the file type extensions allowed to be uploaded for the musiconhold such as "gsm, mp3 file_ext_allow_musiconhold = mp3 ; ENABLE THE CDR VIEWER TO LINK ON THE MONITOR FILES (YES - NO) link_audio_file = "NO" ; PATH TO LINK ON THE RECORDED MONITOR FILES monitor_path = /var/spool/asterisk/monitor // grant access to apache user on read mode for the directory :> chmod 755 /var/spool/ ; FORMAT OF THE RECORDED MONITOR FILE monitor_formatfile = gsm ; Display the icon in the invoice show_icon_invoice = "YES" ; Display the top frame (useful if you want to save space on your little tiny screen ) show_top_frame = "NO" Files / directory right set writing rights /etc/asterisk/ in order to let the web interface write the sip/iax configuration files chmod 777 /etc/asterisk mkdir /var/lib/asterisk/mohmp3/acc_1 mkdir /var/lib/asterisk/mohmp3/acc_2 mkdir /var/lib/asterisk/mohmp3/acc_ etc... until the number you set in the a2billing.conf for the parameter NUM_MUSICONHOLD_CLASS, if 10 you will have to create 10 directory set writing rights for the web interface chmod 777 /var/lib/asterisk/mohmp3/acc_* 16 Chapter 3. Getting & Installing A2Billing the following directory "a2billing" is not used yet... but we will in the near future to configure automaticaly some audio files. mkdir /var/lib/asterisk/sounds/a2billing chmod 777 /var/lib/asterisk/sounds/a2billing SIP/IAX friends include A2Billing is generating is own configuration files for SIP and IAX when you are using the SIP/IAX Friends features. In sip.conf, add the following line at the end #include additional_a2billing_sip.conf In iax.conf, add the following line at the end #include additional_a2billing_sip.conf Configure the manager Edit the manager configuration files, vi /etc/asterisk/manager.conf Ensure that enabled=yes [general] enabled = yes port = 5038 bindaddr = 0.0.0.0 ;displayconnects = yes Add an entry to allow a manager connection [myasterisk] secret = mycode read = system,call,log,verbose,command,agent,user write = system,call,log,verbose,command,agent,user Configure MusicOnHold Edit the MusicOnHold configuration files, vi /etc/asterisk/manager.conf Add the following at the end, we are going here until acc_10, but you must define as many directory that you have create previously ; class definitions For A2Billing acc_1 => mp3:/var/lib/asterisk/mohmp3/acc_1 acc_2 => mp3:/var/lib/asterisk/mohmp3/acc_2 acc_3 => mp3:/var/lib/asterisk/mohmp3/acc_3 acc_4 => mp3:/var/lib/asterisk/mohmp3/acc_4 17 Chapter 3. Getting & Installing A2Billing acc_5 => mp3:/var/lib/asterisk/mohmp3/acc_5 acc_6 => mp3:/var/lib/asterisk/mohmp3/acc_6 acc_7 => mp3:/var/lib/asterisk/mohmp3/acc_7 acc_8 => mp3:/var/lib/asterisk/mohmp3/acc_8 acc_9 => mp3:/var/lib/asterisk/mohmp3/acc_9 acc_10 => mp3:/var/lib/asterisk/mohmp3/acc_10 Give a try! Point your browser to http://hostname/a2billing From this point, you should be able to login to the webpage Try log in with login=root, pass=myroot or login=admin, pass=mypassword Don’t forget to change later your root and admin password. Increase security of the Admin interface with an htaccess The security of the admin interface is really important. If a thrid get connected to your admin interface he will be able to see information about your card/trunk, you can imagine then how he can use this data. The htaccess will increase definitely the security of the web interface, so we will advice you to configure one over the admin/customer interface. We don’t explain here how to do so, but through the links below you will find some good tutorial explaining how to do it. • http://httpd.apache.org/docs/1.3/howto/htaccess.html • http://www.freewebmasterhelp.com/tutorials/htaccess/3 • http://www.php-editors.com/apache_manual/howto/auth.html • http://www.sitedeveloper.ws/tutorials/htaccess.htm Install the customer web interface Install customer web interface Place the directory "A2BCustomer_UI" into your DocumentRoot directory of your web server. mv -rf /usr/src/a2billing/A2BCustomer_UI /var/www/html/. The customer web interface will use the file a2billing.conf to know the database parameter. Refer to the previous section "Install the file for the a2billing configuration" to know how to define those database connection. 18 Chapter 3. Getting & Installing A2Billing Install The AGI components : IVR CallingCard application Install Place the entire content of the directory A2Billing_AGI into your agi-bin directory. cd /usr/src/a2billing/A2Billing_AGI cp a2billing.php /var/lib/asterisk/agi-bin/. cp -rf libs_a2billing /var/lib/asterisk/agi-bin/. Make sure the script is runnable chmod +x /var/lib/asterisk/agi-bin/a2billing.php Install Sounds files cp cp sounds/* /var/lib/asterisk/sounds/. sounds/en/* /var/lib/asterisk/sounds/. *Note you will be asked if you want to overwrite, answer yes For other language: • # install A2Billing Spanish Audio into /var/lib/asterisk/sounds/es/ • # install A2Billing French Audio into /var/lib/asterisk/sounds/fr/ Don’t forget to get the appropriate asterisk audio files to play the balance, time to call, other... To get the international asterisk audio files, you can find those available through the link: http://voip-info.org/tiki-index.php?page=Asterisk+sound+files+international Configure & customize the AGI : a2billing.conf To configure database access for the AGI we will still refer to the previous point "Install the file for the a2billing configuration" that describe the [database] section. section [agi-confX] : configuration for the AGI, several configurations can be defined, ie "agi-conf1", "agi-conf2", etc... the groupid parameter will define which configuration to use. Usage : DeadAGI(a2billing.php|%groupid%) by default agi-conf1 is used Let’s have a look over the parameter : ; the debug level ; 0=none, 1=low, 2=normal, 3=all debug=2 ; Active the logging of the application ; logging is optimized to write all the logs at once :D logger_enable=YES ; File to log log_file=/tmp/a2billing.log 19 Chapter 3. Getting & Installing A2Billing ; if YES Use Set(LANGUAGE()=fr) instead, for me it didnt work from AGI ; ### if (SETLANGUAGE_DEPRECATE==YES) $myres = $agi->agi_exec("EXEC Set(’LANGUAGE()=$la setlanguage_deprecate=YES ; play the goodbye message when the user finish say_goodbye=NO ; enable the menu to choose the language ; press 1 for English, pulsa 2 para el español, Pressez 3 pour Français play_menulanguage=NO ; force the use of a language, if you dont want to use it leave the option empty ; Values : ES, EN, FR, etc... (according to the audio you have install) force_language=EN ; Introduction prompt : to specify an additional prompt to play at the beginning of the ; parlezplus-intro_013centimes intro_prompt= ; lenght of the cardnumber (amount of digits) len_cardnumber=10 ; Voucher lenght len_voucher = 15 ; this is the minimum amount of credit to use the application min_credit_2call=0 ; if YES it will catch the DNID and try to dial it out directly without asking for the ; value : YES, NO use_dnid=NO ; list the dnid on which you want to avoid the use of the previous option "use_dnid" no_auth_dnid=2400,2300 ;number of time the user can dial different number number_try=3 ; Play the balance to the user after the authentication (values : yes - no) say_balance_after_auth=NO ; Play the balance to the user after the call (values : yes - no) say_balance_after_call=NO ; Play the time the user can call (values : yes - no) say_timetocall=YES ; enable the callerid authentication ; if this option is active the CC system will check the CID of caller cid_enable=YES ; if the cid doesnt exist you can then ask a cardnumber to the calling party in order t cid_askpincode_ifnot_callerid=YES ; if the callerID, this option will allow the system to add it automatically and create cid_auto_create_card=NO ; If cid_auto_create_card has been set to YES, the following option will define with wh ; ; billing type of the new card ; ( value : POSTPAY or PREPAY) 20 Chapter 3. Getting & Installing A2Billing cid_auto_create_card_typepaid=POSTPAY ; amount of credit of the new card cid_auto_create_card_credit=0 ; if postpay define here the credit limit for the card cid_auto_create_card_credit_limit=1000 ; the tariffgroup to use for the new card (this is the ID that you can find on the admi cid_auto_create_card_tariffgroup=6 ; enable the option to call sip/iax friend for free (values : YES - NO) sip_iax_friends=NO ; if SIP_IAX_FRIENDS is active, you define a prefix for the dialed phonenumber to call ; values : number sip_iax_pstn_direct_call_prefix=9 ; this will enable a prompt to enter your destination number_try ; if number start by sip_iax_pstn_direct_call_prefix we do directly a sip iax call, if sip_iax_pstn_direct_call=NO ; More information about the Dial : http://voip-info.org/wiki-Asterisk+cmd+dial ; 30 : The timeout parameter is optional. If not specifed, the Dial command will wait ; H: Allow the caller to hang up by dialing * ; r: Generate a ringing tone for the calling party ; m: Provide Music on Hold to the calling party until the called channel answers. ; L(x[:y][:z]): Limit the call to ’x’ ms, warning when ’y’ ms are left, repeated every ; %timeout% tag is replaced by the calculated timeout according the credit & desti dialcommand_param="|30|HL(%timeout%:61000:30000)" ; by default (3600000 = 1HOUR MAX CALL) dialcommand_param_sipiax_friend="|30|HL(3600000:61000:30000)" ; Define the order to make the outbound call ; YES -> SIP/dialedphonenumber@gateway_ip - NO SIP/gateway_ip/dialedphonenumber ; Both should work exactly the same but i experimented one case when gateway was suppor ; So in case of troubles, try it out switchdialcommand=NO ; enable to monitor the call (to record all the conversation) ; value : YES - NO record_call=NO ; format of the recorded monitor file monitor_formatfile=gsm ; the debug shell (ONLY FOR THE DEVELOPERS) ; 0=no, 1=yes debugshell=0 21 Chapter 3. Getting & Installing A2Billing Configure extensions to run A2Billing into Asterisk Edit extension.conf (/etc/asterisk/extension.conf) Add the following link to the appropriate context, below I will create the context "callingcard" [callingcard] ; CallingCard application exten => _X.,1,Answer exten => _X.,2,Wait,2 exten => _X.,3,DeadAGI,a2billing.php exten => _X.,4,Wait,2 exten => _X.,5,Hangup If you use AMP, process as bellow (Can anybody confirm the following, this info is from the wiki and I dont use AMP to check it by myself) Edit extension_custom.conf (/etc/asterisk/extension_custom.conf) and then add the following under the from-internal-custom context. ; CallingCard application exten => _X.,1,Answer exten => _X.,2,Wait,2 exten => _X.,3,DeadAGI,a2billing.php exten => _X.,4,Wait,2 exten => _X.,5,Hangup You can replace above the _X. by a number if you want to set the application over a specific extension. Reload Asterisk to apply the changes > Run asterisk -r CLI>reload CLI>exit Try to make a call then into your pbx and you should hear "please enter your pin number...". This should end up with the agi-php installation ! 22 Chapter 4. Specific information for Installation according to the distribution This chapter aims to give additional installation information specific to some distribution RedHat Files Locations differences Commands Syntax differences Fedora Debian Ubuntu CentOS Mandriva Suse Dos 5.0 Windows 3.11 Xbox 23 Chapter 4. Specific information for Installation according to the distribution 24 Chapter 5. User Guideline This chapter aims to help using the software. We will try to describe interactions between entities and the different features available through the web interface. Entities interaction in the callingcard platform Figure 5-1. Entities interaction The graph above illustrates how the main entities interact together. • 1. Call is initiated on the Asterisk PBX platform • 2. Authentication is perform through various ways : Cardnumber, CallerID, SIP/IAX Friends with Accountcode 25 Chapter 5. User Guideline • 3. The 3D cube’s purpose is to make this graph a little bit more appealing. • 4. Cards have different properties but the main is the tariffgroup to which it is linked. The TariffGroup will determine how the billing will be processed. • 5. TariffGroup can have 1 or + ratecard. Ratecard contains all the couple (destination, tariff), it will be fed with all the destination you would like to provide a termination. • 6. The main rule for the TariffGroup is how it will decide which rates if there is different ratecard. LCR/LCD properties can be defined and then the rate engine would be able to determine which termination would be the most appropriate. Create customer/card Card are the main element of the CC software, as they might contain all the info about the customers (name, email, phone, ..) we can said somehow that the card represent simply the customer of your system. Card properties Let’s try to make an non-exhausting list of the card properties. 26 • cardnumber : this is the pin number of the card :D • cardalias : this is an alias of the card, it should be number and this will be use by the user to connect as username into the customer web interface. It will be also use to call sip/iax friends. • webui pass : password of the user to connect on the customer web UI. • credit : this is the amount of money left on this card. it can be negative in PostPay use. • language : the preferred language of the card holder • tariffgroup : TariffGroup to apply on this card • activated : determine if this card is active or no. • simultaneous access : Define if more that one call can be accept at the same time on this card • currency: the currency that will use to play the balance and provide billing information to the customers • runservice : set if the recurring service would be apply over this card • card type : define the billing method (Prepaid or Postpaid) to apply on this card. • credit limit : when postpaid method is selected. A credit limit need to be specify. • first use date : Date when the first call has been make on this card • enable expire : Define how you want to enable the expire of the card (date, amount of days since first use, amount of days since creation). • expiration date: Define the date for the expiration, it works only if "enable expire" is set to "date expire" • expiration days : Define the numbers of days for the expiration if if "enable expire" is set to "amount of days since first use" or "amount of days since creation" • the followings are information about the card holder : last name, first name, email, adresse, city, state/province, country, zip/postal code, phonenumber, faxnumber • inuse : when a caller is calling on a card, the system set an increment flag to know if this card is currently used or not. If the system stop in abnormally way, it can Chapter 5. User Guideline happen that some customer wont be able to use their cardnumber again. In that case, it can be useful to reset the flag to 0. • callerid : this option specify the CallerID list attached to this card, several callerId can be specify. CallerID Authentication The CallerID Authentication is well-know in the callingcard business. This allow to a third part to use your service without having to authenticate each time. Most of common integration would follow the next schema : • 1) link one or more callerID to the Card • 2) enable the callerId authentication in the AGI application. edit the a2billing.conf, "cid_enable=YES" • 3) if the callerID is not recognized by the system, we can still proceed to the cardnumber authentication but for this we need to set the appropriate option : "cid_askpincode_ifnot_callerid=YES" (see a2billing.conf) we have also to possibility to create a card each time a new callerID is found. if you want to realize this we would advice you to look at the following option in a2billing.conf : cid_auto_create_card ; cid_auto_create_card_typepaid ; cid_auto_create_card_credit ; cid_auto_create_card_credit_limit ; cid_auto_create_card_tariffgroup Billing Engine Introduction Figure 5-2. Entities interaction 27 Chapter 5. User Guideline Talk here about General notion of the rate-engine : Ratecard, LCR, LCD, etc... a bit also about your life and your first girl-experience... TariffGroup bla bla bla about tariffgroup Ratecard bla bla bla about Ratecard... SORRY, dont have much time now... Rate bla bla bla about rate... SORRY, dont have much time now... Trunk Haaaa there is so much to say about trunk... but not today :D Import Ratecard nothing here also... well it would be nice if you can help :D (some screenshot and explanation would be great here) SIP/IAX Friends With this callingcard platform we can also define Asterisk user (SIP/IAX Friends), in other words we can pre-configure a SIP client, an ATA phone or even a gateways. We will not go in details with all the parameters that define a SIP/IAX friends, we will refer a well-documented pages of the WIKI : • SIP configuration : • IAX configuration : As you probably discover, when you browse the card you have 2 particulars button at your disposal : SIP & IAX. When you click on one of them, you will see that an instance in SIP/IAX Friends has been created and 2 red buttons will appears asking you to generate the configuration files. If your system as been well configured you should have an include of the a2billing sip/iax files into your sip/iax.conf files, this will allow us to generate after each changes the specific a2billing sip/iax files and reload asterisk at your convenience to add/update or remove some Asterisk friend/user. Standard process should be: 28 • 1# Create Card • 2# Create a SIP/IAX Friend • 3# Adapte SIP/IAX configuration according to your user • 4# Reload Asterisk (it can be perform from the web interface) Chapter 5. User Guideline • 5# Provide information to your user Make card recharge & notify payment Reporting tools cdr report calls compare monthly traffic daily load Invoice Edit/Add administrator (& define ACL) Customer web interface 29 Chapter 5. User Guideline 30 Chapter 6. Contribution This chapter aims to give information for those that would appreciate to make any kind of contribution. Code contribution We have discovered during the last month of the creation of the v1 A2billing that couples of developers have bring several effort to customize or enhance AreskiCC to their convenience. What a desolation that we cannot all share and take profit of your effort... I will strongly invite you to share you work and your experience even if you think that this is really specific, most of the time we can find some way to make it generic. This will be at your advantage as you will have your work already added for the future release. Development Donation Who don’t want some $$$ to cover his long hard-working nights? Definitely not me :D If you like this project and you want to support it to ensure him a good follow-up and future enhancements, we will definitely appreciate donation. Author paypal account : info [alt] areski [dot] net Audio files & Translations What an important point! If you think you can provide any translation/audio files in other languages or simply in a better quality and you are willing to share them with the Asterisk community, I invite you to contact me : areski [alt] gmail [dot] com Bounty If you need some enhancement or some specific news features, we can certainly create a bounty to complete your needs and by the way push forward the implementation those features. Feedback & success story We will try also to create a section "success story" on the website. So please if you use the soft, please send us your feedback and tell us about your integration/deployment of the soft. 31 Chapter 6. Contribution 32 Chapter 7. Conclusion Conclusion Little note about the project: it has been started in July 2004, it was a personal project with at the beginning the only goal to make something useful for the Asterisk Community. The goals - I had at the starting point - have changed quickly during the cycle of the development, due to the request and better understanding of the needs of an Asterisk Billing System. Goal we hope to complete in short terms (within the next months): • Resellers support • Paypal API addition • Internationalization • More languages support • Easy-install module Within long terms perspective: • Asterisk C module • PL/SQL function for mysql 4.x (increase performance for both DBM) • and much more... We still have lot lot to do, the todolist doesn’t stop to grow... and I really hope that soon we will be able WITH YOUR HELP to provide one of the best billing solution ever :D 33 Chapter 7. Conclusion 34 Chapter 8. FAQ (Frequent Asked Question) This chapter aims to provide help to the user by rending publish the question of the others. FAQ installation • #Question 1 : Answer : • #Question 2 : Answer : FAQ Utilization • #Question 1 : Answer : • #Question 2 : Answer : 35 Chapter 8. FAQ (Frequent Asked Question) 36