April2009

a2billing1.4
InstallationGuide
Version1.0

INSTALLATIONGUIDE1.0

AlbertoEscuderoPascualaep@it46.se
LouiseBerthilsonlouise@it46.se
(cc)CreativeCommonsShareAlikeNonCommercialAttribution3

ThisguidefocusesontheinstallationofabillingsystemfortheAsteriskopensourcePBX.
Thedocumentcoverstheinstallationofa2billing.A2billingisanopensource
implementationofatelecommunicationbillingandaddedvalueservicesplatform.1
A2billingisaLAMP(LinuxApacheMysql(Postgresql)PHP)applicationthatinterfaces
withAsteriskusingboththeAMIandAGIinterfaces.
Thisdocumenthasbeentestedafterusinga2billingtrunkwithDebianetch,Debianetch
andhalf,Ubuntu8.04andUbuntu8.10.(27thMarch2009)

1 http://www.asterisk2billing.org

1(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

TableofContents
PART1.SoftwareRequirements...........................................................................................2
Importantnoteaboutdistributions...................................................................................2
LinuxRequirementsanda2billing......................................................................................3
Notgettinglost,whatistheinstallationabout?...............................................................3
Howallfitstogether?.........................................................................................................4
PART2.Installationofa2billing............................................................................................5
STEP1.GetA2Billingsourcecode...................................................................................6
STEP2.PreparetheDatabase..........................................................................................6
STEP3.Edita2billingconfigurationfile...........................................................................7
STEP4.Fixpermissions,filesandfolders.......................................................................8
1.SIPandIAX..............................................................................................................8
2.Soundfiles..................................................................................................................8
3.ConfigureAsteriskManager......................................................................................8
STEP5.InstallTheAGIcomponents..............................................................................9
STEP6.InstallwebbasedGraphicalinterfaces...............................................................9
STEP7.Createdialplan..................................................................................................10
STEP8.Configurerecurringservices..............................................................................11
STEP9.Callbackdaemon(onlyforCallbacks)...........................................................12
PART3.DefaultpasswordsandURL..................................................................................12

PART1. SOFTWAREREQUIREMENTS
IMPORTANTNOTEABOUTDISTRIBUTIONS
Thisdocumentationassumesthatyouareusinga.debbasedLinuxdistrothathasused
thefolder/usr/share/asteriskduringasteriskpackaging.
Otherdistributionsusethealternatefolder/var/lib/asterisk.Thatisthecaseifyou
compilefromsourcethepathbydefaultis/var/lib/asterisk.
Thebasicassumptionsofthisdocumentationisthatyouarenotcompilinganyofthe
softwarepackagesforsource.
Otherassumptionsare:

yourapache2defaultrootfolderis/var/www
yourasterisksoundsareunder/usr/share/asterisk/sounds
yourasteriskAGIfolderisexpectedunder/usr/share/asterisk/agibin
2(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

yourapache2runsaswwwdata(uid)
youasteriskrunsasasterisk(uid)
thoseusingsubversiontocheckoutthecode,arerecommendedtousesymboliclinks
insteadofcopyingthefilestotherightdirectories

LINUXREQUIREMENTSANDA2BILLING
a2billing1.4includesthefollowingthirdpartysoftware:

phpagi2.14Copyright2003,2004,2005MatthewAshamandDavidEder
smarty2.6.22Copyright20012005NewDigitalGroup,Inc
jgraph1.27Copyright2001,2002,2003,2004JohanPerssonAditusConsulting
adodb4.991Copyright(c)2000,2001,2002,2003,2004JohnLim
html2pdfCopyright(C)20042005RenatoCoelho
famfamfam.comIconsfromMarkJames
phpconfig(C)2003DavePackhamandRobBirkinshaw

NOTGETTINGLOST,WHATISTHEINSTALLATION
ABOUT?
Inanutshellinstallinga2billingrequiresninesteps:
1.
2.
3.
4.
5.
6.
7.
8.
9.

Downloadandunpacksourcecode
Setupthedatabase
Edita2billing.conffile.Settingupthedatabaseparameters
Fixpermissionsandfolders
Installingthewebbasedgraphicaluserinterfaces(CustomerandAdmin)
PlacetheAGIfiles
Prepareyourdialplan
Addyourcronjobs
Configureyourcallbackdaemon(onlyforcallback)

Tohelpyoutounderstandwhatwearedoingconsiderthat:
1. Themotherofallcomponentsofa2billingisanAGIfile(a2billing.php)thatis
calledfromasteriskdialplan.(SeeStep:6,7)
2. TheoverallgoaloftheinstallationistomakesurethattheAGIfilethatisplaced
intheasteriskagibinfolderandinvokedfromthedialplancan(1)accessamysql
databaseand(2)connecttoAsteriskmanagertoplaceandreceivecallrelated
commandsandinformation.(SeeStep:2,3,4)
3(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

3. A2billingismanagedviathreedifferentuserinterfaces(admin,agentandcustomer)
thatneedstorunviatheapache2webbrowserwiththerightownerandpermissions
(SeeStep:5)
4. Thereareothercomponentsascronjobs,callbackdaemon,etcthatareneededfor
advanceaddedvalueservices(SeeStep:8,9)

HOWALLFITSTOGETHER?
A2billingisacomplexsoftwarebutthemainideacanbesummarizedasfollows:
WhenacallcomesintoAsterisk,itfallsintoacontext(apartofthedialplan)thatwill
executea2billing.phpPHPfileinoneofitsoperationalmodes.ThePHPfileistheAGI
(AsteriskGatewayInterface)softwarethatisresponsibleofretrievinginformationofthe
callfromtheAMI(AsteriskManagerInterface)andinteractwiththeMysqldatabase.All
actionsrelatedtothecall(routing,playingaIVR,etc)areexecutedtalkingtoAsteriskvia
theAMI.
a2billing.php(theAGIcodeinthedialplan)usesaPHPclassknownasphpagitotalk
withtheAMIandadodbtoconnectwiththemysqldatabase.Toseparatefunctionality
frompresentationa2billing1.4isusingsmarty.

4(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

PrerequiredPackages
A2billingrequiresthepackagesofaLAMP(PHP5)installation.
Toinstallthenecessarypackages,runthefollowingcommands:
#aptgetinstalllibapache2modphp5php5php5common
#aptgetinstallphp5cliphp5mysqlmysqlserverapache2php5gd
#aptgetinstallopensshserver

Version1.4requiresMcryptforPHP5
#aptgetinstallphp5mcrypt

Asteriskisofcoursealsoneeded.
#aptgetinstallasterisk

PART2. INSTALLATIONOFA2BILLING
Inanutshellinstallinga2billingrequiressevensteps:
1. Downloadandunpacksourcecode
2. Setupthedatabase
3. Edita2billing.conffile.Settingupthedatabaseparameters
4. Fixpermissionsandfolders
5. PlacetheAGIfiles
6. Installingthewebbasedgraphicaluserinterfaces(Customer,AgentandAdmin)
7. Prepareyourdialplan
8. Addyourcronjobs
9. Configureyourcallbackdaemon(onlyforcallback)

5(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP1. GETA2BILLINGSOURCECODE
Downloadthesourcecode(wget)andunpackit(tar).2
#cd/usr/local/src/
#wgethttp://www.asterisk2billing.org/downloads/A2Billing_1.4.0.tar.gz
#tarzxvfA2Billing_1.3.4.tar.gz

Wewillnowcreateasymboliclinktothenewdirectory

#lns/usr/local/src/a2billing_1.4.0/usr/local/src/a2billing

Makesureyouhaveallthecodeunder/usr/local/src/a2billing

STEP2. PREPARETHEDATABASE
WewillnowcreateaMySQLdatabase(mya2billing)forthebillingsoftware.Thefile
a2billingMYSQLcreatedbuser.sqlincludesascriptthatcreatesthedatabasewiththe
correctaccesscontrolusersandpermissions.
#cd/usr/local/src/a2billing
#mysqlurootp<DataBase/mysql/Mysql5.x/a2billingMYSQLcreatedb
user.sql

Aftercreatingthedatabasestructure,wewillcreateasetoftablesandinsertsomeinitial
basicdatathatA2Billingneedstowork.
#mysqlurootpmya2billing<DataBase/mysql/Mysql5.x/a2billing
schemaMYSQL.5.Xv1.4.0.sql

Checkpoint1:Checkthatthedatabase(my2billing)andthat(89?)tableshavebeen
created.
#mysqlurootpmya2billing
mysql>showtables
mysql>exit

2 IfyouareadeveloperconsiderusingtheSVNversion
svncousernameguestpasswordguesthttp://svn.a2billing.net/svn/asterisk2billing/trunk

6(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP3. EDITA2BILLINGCONFIGURATIONFILE
WeneedtoedittheA2Billingconfigurationfile(a2billing.conffile).Thefilecontainsall
theconfigurationinformationfortheAsterisk2Billingtoconnecttothedatabase.
First,weneedtocopythedefaultconfigurationfilefromthesourcecode(/usr/local/src)
toAsterisk(/etc).Noticethatinpreviousversionsthea2billing.confwasunder
/etc/asterisk
#cp/usr/local/src/a2billing/a2billing.conf/etc/

Openthefilewithyourfavoritetexteditor(viisusedinthisexample).Ifyouarenewto
Linux,werecommendyoutousethetexteditorGedit3.
#vi/etc/asterisk/a2billing.conf

Theonlyparametersthatyouneedtochangehereisthedatabaseconnectioninformation,
anexamplefollows:
[database]
hostname=localhost
port=3306
user=a2billinguser
password=a2billing
dbname=mya2billing
;dbtype=postgres
dbtype=mysql

3 Geditisagraphicaltexteditorandcannotberunfromaconsole.Inthatcase,werecommendvi.

7(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP4. FIXPERMISSIONS,FILESANDFOLDERS
Inthisstep,wewilltweakthefilepermissionsofAsterisktofittheA2Billingsoftware.We
willalsocreateanumberofadditionalfilesandfoldersthatA2Billingneeds,whichdoes
notcomewiththedefaultinstallation.

1. SIPandIAX
Firstwewillsetafewfilepermissions(chmod,chown)andcreate(touch)theSIPand
IAXconfigurationfilesforAsterisk.
chmod777/etc/asterisk
touch/etc/asterisk/additional_a2billing_iax.conf
touch/etc/asterisk/additional_a2billing_sip.conf
echo\#includeadditional_a2billing_sip.conf>>/etc/asterisk/sip.conf
echo\#includeadditional_a2billing_iax.conf>>/etc/asterisk/iax.conf
chownRfwwwdata/etc/asterisk/additional_a2billing_iax.conf
chownRfwwwdata/etc/asterisk/additional_a2billing_sip.conf

2. Soundfiles
Weneedtocopy(cp)afewfilesfromA2BillingpackagetoAsterisksoundsfolder.Usethe
installationscriptasfollows:
/usr/local/src/a2billing/addons/install_a2b_sounds_deb.sh
chownRasterisk:asterisk/usr/share/asterisk/sounds/

3. ConfigureAsteriskManager
ConfiguretheAsteriskManagerbyeditingthemanager.conffile.
#vi/etc/asterisk/manager.conf
[general]
enabled=yes
port=5038
bindaddr=0.0.0.0
[myasterisk]
secret=mycode
read=system,call,log,verbose,command,agent,user
write=system,call,log,verbose,command,agent,user

8(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP5. INSTALLTHEAGICOMPONENTS
PlacetheentirecontentofthedirectoryAGIintoyouragibindirectory.
mkdir/usr/share/asterisk/agibin
cd/usr/local/src/a2billing/AGI
cpa2billing.php/usr/share/asterisk/agibin/
cpRflib/usr/share/asterisk/agibin/
Makesurethescriptisexecutable
chmod+x/usr/share/asterisk/agibin/a2billing.php

STEP6. INSTALLWEBBASEDGRAPHICALINTERFACES
Inthisstep,wewillinstallthethreegraphicalinterfacesofA2Billing,theAdministration
(admin),Agent(agent)andtheCustomerinterface(customer).
Placethedirectoriesadmin,customer,agentandcommonintoyourwebserverdocument
root.
mkdir/var/www/a2billing
cprf/usr/local/src/a2billing/admin/var/www/a2billing
cprf/usr/local/src/a2billing/agent/var/www/a2billing
cprf/usr/local/src/a2billing/customer/var/www/a2billing
cprf/usr/local/src/a2billing/common/var/www/a2billing

chmod755/var/www/a2billing/admin/templates_c
chmod755/var/www/a2billing/customer/templates_c
chmod755/var/www/a2billing/agent/templates_c
chownRfwwwdata:wwwdata/var/www/a2billing/admin/templates_c
chownRfwwwdata:wwwdata/var/www/a2billing/customer/templates_c
chownRfwwwdata:wwwdata/var/www/a2billing/agent/templates_c

Restartyourwebserver(Apache).
/etc/init.d/apache2restart

Checkpoint2:Directabrowsertotheadministrativewebinterface(http://<ip
addr>/a2billing/admin)andlogin(checkforalldefaultpasswordsattheendofthis
document).

9(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP7. CREATEDIALPLAN
Theextensions.confistheAsteriskdialplan.Callsthatinteractwiththebillingsoftware
needtobehandledinsideofoneormanya2billingrelatedcontexts.
Thecallsthatreachthecontextareprocessedusingthea2billing.phpAGIscript.The
a2billing.phpscriptcanbeinvokedinmanydifferentmodes(standard,did,voucher,
callback,etc).Intheexample,wecreatetwodifferentcontexts,thefirstcontext[a2billing]
handlesallthecallsfromourVoIPclients.Whenacallarrives,anyextensionnumber_X.
(2digitsormore)reachesthescripta2billing.php
Thesecondcontext[did],willbeusedtorouteincomingcallsbacktotheusers.Callsto
theclients(DID)arehandledinsideofthe[did]context.Thescripta2billing.phpindid
modeisresponsibleofroutingthecallbacktooneofourusers.4
Editextension.conf(/etc/asterisk)andaddthefollowingtwoextensions.
[a2billing]
;CallingCardapplication
exten=>_X.,1,Answer
exten=>_X.,2,Wait,2
exten=>_X.,3,DeadAGI,a2billing.php
exten=>_X.,4,Wait,2
exten=>_X.,5,Hangup
[did]
;CallingCardapplication
exten=>_X.,1,DeadAGI(a2billing.php|1|did)

4 DeadAGIisavariantofAGIthatyouusewhenthechannelishungup.

10(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP8. CONFIGURERECURRINGSERVICES
Recurringservicesarehandledviathe/etc/crontab
Youcanaddthefollowingcronjobstoyour/etc/crontaborcreateafilewiththejobsin
/var/spool/cron/a2billing
#updatethecurrencytable
06***php/usr/local/src/a2billing/Cronjobs/currencies_update_yahoo.php
#managethemonthlyservicessubscription
061**php
/usr/local/src/a2billing/Cronjobs/a2billing_subscription_fee.php
#TocheckaccountofeachUsersandsendanemailifthebalanceis
lessthantheuserhavechoice.
0****php/usr/local/src/a2billing/Cronjobs/a2billing_notify_account.php
#Tocheckalltheaccountsandsendannotificationemailifthe
balanceislessthanthefirstargument.
0*/6**php/usr/local/src/a2billing/Cronjobs/a2billing_check_account.php
#thisscriptwillbrowsealltheDIDthatarereserveandcheckifthe
customerneedtopayforit
#billthemorwarnthemperemailtoknowiftheywanttopayin
ordertokeeptheirDIDs
02***php/usr/local/src/a2billing/Cronjobs/a2billing_bill_diduse.php
#Thisscriptwilltakecareoftherecurringservice.
012***php/usr/local/src/a2billing/Cronjobs/a2billing_batch_process.php
#Togenerateinvoicesandforeachuser.
06***php/usr/local/src/a2billing/Cronjobs/a2billing_invoice_cront.php
#toproceedtheautodialer
*/5****php
/usr/local/src/a2billing/Cronjobs/a2billing_batch_autodialer.php
#managealarms
0****php/usr/local/src/a2billing/Cronjobs/a2billing_alarm.php

11(12)

April2009
a2billing1.4
InstallationGuide
Version1.0

STEP9. CALLBACKDAEMON(ONLYFORCALLBACKS)
Thecallbackdaemonisresponsibleofreadingfromthedatabasethepoolofcallsstored
forcallbackandtriggerthosecallsperiodically.ThedaemoniswritteninPython.Install
thepythonsetuptoolsanduseeasy_installtoinstallthecallback_daemon
aptgetinstallpythonsetuptoolspythonmysqldbpythonpsycopg2
pythonsqlalchemy
cd/usr/local/src/a2billing/CallBack
easy_installcallbackdaemonpy/dist/callback_daemon1.0.prod_r1527
py2.5.egg

Installtheinit.dstartupscript
cd/usr/local/src/a2billing/CallBack/callbackdaemonpy/callback_daemon/
cpa2bcallbackdaemon.debian/etc/init.d/a2bcallbackdaemon
chmod+x/etc/init.d/a2bcallbackdaemon

Makesurethedaemonstarts

updaterc.da2bcallbackdaemondefaults4060

Ifyouneedtoremovethedaemoninthefuturerun

updaterc.dfa2bcallbackdaemonremove

PART3. DEFAULTPASSWORDSANDURL
Type

Username

Password

AdminUI

root

changepassword

Manager

myasterisk

mycode

MySQLdatabase

a2billinguser

a2billing

Database

mya2billing

Note!Thefirstcharacterinallusernamesandpasswordsisasmallletter(notcapital).

12(12)