Cacti ISP Billing Documentation

Version 1.0.13
Author: Tony Roman Copyright 2012 Cacti Group

Copyright 2010 Cacti Group

1 of 42

Contents
1. Preface 2. Features 3. Operations i. General ii. Output iii. Data Collection iv. RRA Definitions 4. Installation 5. Up ra!in ". Confi uration i. Default # Glo$al ii. Custo%ers an! Grap&s iii. 'illin (i%e Fra%e )Interval* iv. Rate v. +%ail vi. Currenc, vii.'ran!in +%ail Output viii. +-portin to C./ )Co%%a .eparate! /alues* File i-. (&res&ol! (rac0in -. Usin t&e $uil! Co%%an! -i. +-a%ple Confi uration -ii.(rac0 File 1. (estin 2. C./ File For%ats i. +%ail C./ File ii. +-port C./ File 3. Co%%an! 4ine Reference

Copyright 2010 Cacti Group

2 of 42

Revision 5istor,
2006-11-11 Document creation 2006-12-20 Minor changes for grammar an synta! 200"-02-1" #p ates for $ersion 1%0%1& inc'u ing e!ten e emai' support 200"-02-2( #p ate for $ersion 1%0%2& inc'u ing a itiona' sections on #pgra ing& RRA Definitions& Data Co''ection an Testing% 200"-0)-0) #p ate for $ersion 1%0%* an information on supporte Cacti $ersions% 200"-0"-16 #p ate for $ersion 1%0%( 200"-0+-2( #p ate for $ersion 1%0%) an Cacti 0%,%" 200"-12-10 #p ate for $ersion 1%0%6 200,-01-21 #p ate for $ersion 1%0%" 200,-02-0* #p ate for $ersion 1%0%, 200,-11-2* #p ate for $ersion 1%0%+& information a-out: .eatures& Rates& Trac/ing .i'e& etc% 200+-0*-0, #p ate for $ersion 1%0%10& Thresho' trac/ing a e 2010-0,-2" #p ate for $ersion 1%0%11 2011-0)-0, #p ate for $ersion 1%0%12& c'arification on 0an 1i th 2ummation Thresho' s 2012-0)-*0 #p ate for $ersion 1%0%1* an Cacti 0%,%,

Copyright 2010 Cacti Group

3 of 42

Preface
Section 1
If you are reading this, you have already taken the first steps of using Cacti or thinking a out using Cacti to graph your and your custo!ers" and#idth usage. $he I%& illing script is a si!ple to use co!!and line php script that e!ails periodic reports of custo!ers" and#idth usage and calculated o#ed a!ounts. $his docu!ent assu!es you have Cacti up and running and graphing and#idth usage. It is also assu!ed that you have at least a asic understanding of Cacti and ho# to vie# the graphs. $he syste! supports !ultiple types of illing intervals' (early, )onthly, *i+!onthly, ,eekly and -aily. .ll these are configura le to allo# for !a/i!u! fle/i ility. *illing rates are also very fle/i le. 0egular illing rates, fi/ed or co!!itted1overage illing rates can e applied glo ally, to individual custo!ers or to a single graph. )ini!u! Cacti version 0.2.3h is re4uired for the I%& *illing %cript. $his re4uire!ent is present ecause the 56th &ercentile functions #here updated e/tensively in this version of Cacti. $he I%& illing script is dependent on Cacti, so version re4uire!ents of Cacti apply to the I%& illing script. If you have any 4uestions a out the operation of the script, have a ug to report or #ould like to re4uest a feature, please contact $ony 0o!an at ro!an7disorder.co!.

Copyright 2010 Cacti Group

4 of 42

Features
Section 2
$he Cacti I%& *illing %cript is a co!prehensive addon for Cacti that allo#s for daily, #eekly, !onthly or i+!onthly per custo!er illing of Cacti generated graphs for 8th &ercentile and *and#idth %u!!ation. )ultiple or single graphs can e associated #ith a custo!er to allo# for !ultiple interface illing for a single custo!er. %tandard, Co!!itted19verage and :i/ed illing rates are supported per custo!er. ;!ail output can e generated per custo!er. ;!ail output is <$)= #ith graph i!ages and an attached C%V file containing the sa!e data that the e!ail contains. .ll these options are configura le. ;/ported C%V data can e create per custo!er and post+processed y a user defined script to any for!at for i!porting into a illing syste!. ;/a!ple scripts are supplied for creation of ta deli!ited files, %>= insert state!ents, ?)= output, etc. 9nly 8th &ercentile and *and#idth %u!!ation co!!ent lines on Cacti graphs are considered a illa le ite!. %o, the value that a custo!er #ill see on the graph #ill e that is used to calculate illa le totals. Inter+ illing period notifications of e/ceeded co!!itted rate, configura le per custo!er.

Copyright 2010 Cacti Group

6 of 42

Operations
Section 3 General .u$ .ection i
$he I%& illing script is to e run everyday on the server #hich Cacti is installed. %i!ply use cron or #indo#s scheduler to schedule the e/ecution of the script. $he I%& illing script re4uires a configuration and a track file @auto generatedA. $he configuration file is #here the custo!ers" infor!ation is defined. $he track file is #here the last ti!e illing #as perfor!ed for the configured custo!ers is saved. )ultiple configuration files can e used for different groups of custo!ers, all that needs to e done is schedule each configuration separately to e run daily. )ultiple configurations can use the sa!e track file, ut it is suggested that separate track files are used per configuration file, as duplicate custo!er descriptions et#een configuration files can collide in the track file. 6&at !oes t&e I.P $illin script use fro% Cacti to !eter%ine 7&at is $illa$le8 (&e I.P $illin script onl, loo0s at rap&s 7it& rap&s ite%s t,pes of co%%ents t&at contain rap& varia$les t&at !efine! 'an!7i!t& .u%%ation an! 9t& Percentile values. 3!amp'e 1 8th &ercentile Graph

$he resulting illa le value #ould e B56th &ercentile @0.02 ! it inCoutAD.

Copyright 2010 Cacti Group

3 of 42

3!amp'e 2 *and#idth %u!!ation Graph

$he resulting illa le value #ould e B$otal 9ut' 123.62 )*D and B$otal In' E.22 G*D. Billing Intervals $here are 4 availa le illing intervals' Dai'y: *illing occurs daily or every nth nu! er of days defined fro! !idnight to !idnight. 4ee/'y: *illing occurs #eekly or every nth #eeks on %aturday night at !idnight to %aturday night at !idnight. Month'y: *illing occurs !onthly on the defined day, 1 to last day of !onth, every 1 or nth !onths on !idnight of the defined day. 0i-month'y: *illing occurs !onthly on the 16th and last day of the !onth. 8ote' .ll illing intervals are processed on the day after the ending day of the interval. :or e/a!ple, !onthly for 9cto er #ould e fro! 10+1 00'00'00 to 10+31 23'65'65, ut #ouldnFt e processed until the illing script is run on 11+1.

Copyright 2010 Cacti Group

E of 42

Output .u$ .ection ii

$he I%& *illing script supports !ultiple output types #ithin the e!ailed reports. <$)= and te/t for!atted !essages are ena led y default, ut are can e ena led or disa led per defined e!ail address. 3!amp'e * 5TM6 emai' -i''ing report

Copyright 2010 Cacti Group

2 of 42

3!amp'e ( Te!t on'y -i''ing report

;!ails y default include an attached C%V file that !i!e type is set to open #ith ;/cel or 9pen 9ffice %preadsheet. ;!ails default to <$)= for!at, per e!ail address para!eters allo# for te/t only e!ails and re!oval of the C%V attach!ent.

Copyright 2010 Cacti Group

5 of 42

Data Collection .u$ .ection iii

-ata collection see!s to e a su Gect that co!es up a lot in conGunction #ith the I%& *illing script. $he I%& *illing script uses the graph definitions defined in Cacti. <o#ever the data is collected, the I%& *illing script has no concept of this, it relies on Cacti to perfor! this action. 3!amp'e ) Data Co''ection Re'ationship

It is often asked #hat data the I%& *illing script #ill use fro! the 00-$ool files. $he ans#er is si!ple, it #ill let 00-$ool figure it out. 8o#, #hat does 00-$ool do, it atte!pts to use the highest resolution data set that contains data for the selected ti!e fra!e. $his is #hy it is very i!portant, for illing purposes, that you retain si/ !onths to a year of high resolution data. . great e/a!ple #ould e to retain one year of 6 )inute .verage @-ailyA infor!ation. &lease refer the the ne/t section for infor!ation on defining and updating your 00. definitions in Cacti to retain the reco!!ended higher resolution data.

Copyright 2010 Cacti Group

10 of 42

RRA Definitions .u$ .ection iv

)ost people either donFt understand or donFt realiHe that Cacti uses 00-$ool to store the infor!ation it gathers fro! devices. $he )y%>= data ase is si!ply the place that Cacti stores the configuration infor!ation on #hat it #ill poll, #here it #ill store it and ho# to present the stored data. 00-$ool files are #here the statistical data is stored. $he eauty of 00-$ool files is that once they are created they do not gro# or shrink in siHe, this is the nature of a 0ound 0o in -ata ase. :or !ore infor!ation a out 00-$ool, please visit the 00-$ool #e site at' http'11###.rrdtool.org *ecause you are using the Cacti I%& *illing script, #e can only assu!e that you are using Cacti for illing purposes. $his eing said, itFs very i!portant that your 00-$ool files retain at least three ti!es the !a/i!u! illing interval of high resolution data @6 )inute .verage y -efault in CactiA. ;/a!ples' 1. If you had a !a/i!u! illing interval of every 3 !onths, you #ould #ant to retain at least nine !onths of high resolution data. 2. If you have a !a/i!u! illing interval of !onthly, you #ould #ant to retain at least three !onths of high resolution data. <igh resolution data is considered to e #hich ever is your lo#est consolidation function defined in CactiFs 00. settings the default eing B-aily @6 )inute .verageAD. 3!amp'e 6 Cacti RRA 7Roun Ro-in Archi$es8

Copyright 2010 Cacti Group

11 of 42

3!amp'e " Dai'y 7) Minute A$erage8 one year high reso'ution ata

$he a ove e/a!ples have een altered to retain one year of -aily @6 )inute .verageA high resolution data. 6AR9I9G: Defining large high resolution RRA efinitions can egra e s!stem performance an use a consi era"le amount of is# space$ One traffic interface %ith the efault t%o a! high resolution retention %ill result in a &'( si)e RRD*ool file+ "ut the same file %ith one !ear of high resolution retention %ill result in a &, file$ ,ultiple that change "! all the RRD*ool file that Cacti uses an it can "e a consi era"le amount of is# space$ P-P e.ecution time an memor! ma.imums settings %ill have to "e increase to accommo ate the time an resources nee e to process such ata sets$

Copyright 2010 Cacti Group

12 of 42

Dail! /' ,inute Average0 RRA Retention length 2 -ays @Cacti -efaultA 3 )onths 3 )onths 5 )onths 1 (ear

Ro%s 300 23,220 62,630 E2,240 106,120

1p ating !our e.isting RRD*ool files 9ne thing Cacti #ill not do for you is alter 00-$ool files that have already een created. (ou have to Brrdtool resiHeD the files to have the correct nu! er of defined ro#s. &lease refer to the rrdtool docu!entation on instructions for doing this. $here is a very helpful post on the Cacti foru!s on ho# to do this and a script to assist in doing so. http'11foru!s.cacti.net1vie#topic.phpItJ11426

Copyright 2010 Cacti Group

13 of 42

Installation
Section 2
1. Knpacking the progra! $he file is supplied in a tar.gH for!at. Kse the follo#ing co!!and to e/tract' gunHip +c ispL illingM.tar.gH N tar +/vf + If you are on ,indo#s, you can use your favorite archiving progra! that supports tar.gH. ,inHip is a great e/a!ple of an archive progra! that #ill e/tract these files. 2. 9nce the ispL illing directory is e/tracted, it needs to e !oved to the directory that Cacti is installed. ;/a!ple co!!and' !v ispL illing 1var1###1htdocs1cacti1

3. $o ensure you donFt get any pesky &<& errors a out sessions, itFs i!portant to add the ispL illing.php to the OnoLhttpLheaderLfiles array in the include1config.php @0.2.3G+A or include1 glo al.php @0.2.ECA file for Cacti. If you are running #indo#s, this change !ay not e needed. 1M :iles that do not need http header infor!ation + Co!!and line scripts M1 OnoLhttpLheaderLfiles J array@ Ppoller.phpP, Pc!d.phpP, P4ueryLhostLcpu.phpP, P4ueryLhostLpartitions.phpP, Ps4l.phpP, PssLhostLcpu.phpP, PssLhostLdisk.phpP, PssLs4l.phpP, PispL illing.phpP AQ 4. *efore you can add the scheduled Go s for the illing script a configuration file has to e generated. $he ispL illing script has a uilt in function to uilt a configuration off of your already created graphs in Cacti. .s !entioned earlier, it #ill only uses graphs that contain co!!ent fields #ith graph varia les defined for 8th &ercentile and *and#idth %u!!ation. $he uild process also !akes so!e assu!ptions, like a ill rate of O0 and !onthly illing interval processed on the last day of the !onth. :or !ore infor!ation on ho# to configure these ite!s and usage of the uild co!!and, please refer to Chapter 4 on Configuration. Copyright 2010 Cacti Group 14 of 42

Kse the follo#ing co!!and to uild an e/a!ple./!l configuration file' php ispL illing.php + uild 3!amp'e , R 9utput of uild co!!and

Ksing the list function can generate a !ore reada le su!!ary for!at. Kse the follo#ing co!!and line to e/ecute the co!!and' php ispL illing.php +list $he resulting output #ill aid you in deter!ining #hich graphs to configure for #hat custo!ers. 3!amp'e + R 9utput of list co!!and

Copyright 2010 Cacti Group

16 of 42

9nce you have uilt your configuration file, you can check to see if it is #hat you #ant y using the info co!!and line option to revie# the configuration. $he info co!!and line option is very useful, it #ill allo# you to get infor!ation a out configured custo!ers in each configuration file you have. $o use the info function, use the follo#ing co!!and line' php ispL illing.php +configJcusto!er./!l trackJtrack./!l +info

3!amp'e 10 R 9utput of info co!!and

Copyright 2010 Cacti Group

13 of 42

6. %cheduling the ispL illing script' Kni/ uses cron for this purpose, this script can e run as any user, ut should not e run as root. $he only consideration to understand is the user running the script !ust have read access to the rrd files in the Cacti installation. Kse the follo#ing line in your glo al cronta to schedule the ispL illing script. 0e!e! er to input the full path to php and use the correct user account.

01MMM

cactiuser php 1var1###1htdocs1cacti1ispL illing1ispL illing.php S +configJ1var1###1htdocs1cacti1ispL illing1config1custo!ers./!l S +trackJ1var1###1htdocs1cacti1ispL illing1config1track./!l

It is i!portant to note that you need to replace the paths #ith the correct paths for your syste!.

Copyright 2010 Cacti Group

1E of 42

1pgra ing
Section '
*ecause you !ight already have a previous version of the I%& *illing %cript, upgrading !ust e covered. Kpgrading is easyT 1. )ove your current I%& *illing directory to a ackup location.
!v 1var1###1ht!l1cacti1ispL illing 1var1###1ht!l1cacti1ispL illing. ackup

2. ;/tract and !ove or copy the ne# I%& *illing directory to your Cacti installation.
!v 1t!p1ispL illing 1var1###1ht!l1cacti1ispL illing

3. Copy your configuration files fro! the ackup to the ne# installation.
cp +p 1var1###1ht!l1cacti1ispL illing. ackup1config1M 1var1###1ht!l1cacti1ispL illing1config

4. &erfor! a test run to confir! that everything is good. 3ote4 . ove are Gust e/a!ple paths. &lease use the proper paths for your syste!.

Copyright 2010 Cacti Group

12 of 42

Configuration
Section 5
$he configuration file for the I%& illing script is a specifically for!atted ?)= file. In the follo#ing sections, the for!at and para!eters of the configuration sections #ill e revie#ed and e/plained. $he configuration file !ust egin #ith the follo#ing'
UI/!l versionJF1.0F encodingJFK$:+2F standaloneJFyesFIV UcactiL illerV

and end #ith the follo#ing'

U1cactiL illerV

3ote4 BK$:+2D encoding should e used on anything other than ,indo#s. 9n ,indo#s, use BI%9+ 2265+1D encoding. 9nce you have your configuration ready, you should al#ays check it. Kse the follo#ing co!!and line option to check the configuration for errors'
php ispL illing.php +check +configJcusto!er./!l +trackJtrack./!l

Copyright 2010 Cacti Group

15 of 42

Default # Glo$al .u$ .ection i

-efault 1 Glo al section is re4uired. Values that are not defined per custo!er or per graph then use the values defined in this section of the configuration file. ;/a!ple of defaults 1 glo als section'
Uglo alV UdefaultsV Ue!ailV illing7isp.co!U1e!ailV Urate unitJP) PV0.06U1rateV U illingLti!efra!eV UtypeV!onthlyU1typeV UdayVlastU1dayV UeveryV1U1everyV UstartLdateV2003+10+01U1startLdateV U1 illingLti!efra!eV UcurrencyV UpreVOU1preV UpostV K%-U1postV UprecisionV2U1precisionV U1currencyV Ufile processJDyesDVe/port.csvU1fileV U1defaultsV Ue!ailV UreturnLaddressV illing7isp.co!U1returnLaddressV Usu GectV*and#idth *illingU1su GectV UtitleV*and#idth *illingU1titleV UcsvLfileLna!eV illingU1csvLfileLna!eV U1e!ailV Ue/portLfileLprocessorVscripts1postLprocess.plU1e/portLfileLprocessorV UthresholdV Uena ledVnoU1ena ledV UnotificationVnoU1notificationV Usu GectV8otification ;!ail %u GectU1su GectV UtitleV;!ail .ddress $itleU1titleV U1thresholdV U1glo alV

Valid para!eters for glo al section e!ail settings are covered later in this section. Valid para!eters for the rate and illingLti!efra!e sections are covered later in this section. Valid para!eters for currency section are covered later in this section. Valid para!eters for e/portLfileLprocessor and file are covered later in this section. Valid para!eters for threshold are covered later in this section. .n e!ail address !ust e defined in the default section, e!ail address should also e defined per custo!er. .ny custo!er that does not have an e!ail defined #ill use the defined default e!ail. 0efer Copyright 2010 Cacti Group 20 of 42

to the e!ail section for optional para!eters.

Copyright 2010 Cacti Group

21 of 42

Custo%ers an! Grap&s .u$ .ection ii

.t least one custo!er section is re4uired for a #orking configuration.

Custo!er :ields' ?)= :ield Ucusto!ersV Ucusto!erV UdescriptionVU1descriptionV

-escription Custo!ers container opening tag Custo!er container opening tag $his is the custo!er description, this value can not e duplicated et#een custo!ers. $his value #ill appear on the illing reports as the custo!ers description. 9ptional field R 0efer to the C%V e/port section for para!eters and values. 9ptional field R 9nly used y C%V e/port for potentially identifying custo!er in e/ternal syste!. 9ptional field R 0efer to rates section for para!eters and values. 9ptional field R 0efer to illingLti!efra!e section for para!eters and values. 9ptional field R ;!ail address to e!ail the resulting report to. )ultiple entries are supported. $o disa le e!ailing use the string value of B8K==D. 9ptional field R 0efer to currency section for para!eters and values. Graphs container tag, re4uired. .t least one graph section !ust e defined, !ultiple are allo#ed. 9ptional field R 0efer to rates section for para!eters and values. 9ptional field R 9nly used y C%V e/port for potentially identifying custo!ersF graph in e/ternal syste!. Graph id R $his value can e gotten fro! the Cacti #e interface y vie#ing the graph in 4uestion and e/a!ining the K0= for the varia le called BlocalLgraphLidD. 9ptional field R -efine the e/act graph ite! on the graph to process illing. If no graphLite!s are defined, any !atching co!!ent fields #ill e used fro! the defined graph. Graph container closing tag 22 of 42

UfileVU1fileV Ue/ternalLidVU1e/ternalLidV UrateVU1rateV U illingLti!efra!eV U1 illingLti!efra!eV Ue!ailVU1e!ailV

UcurrencyVU1currencyV UgraphsV UgraphV UrateVU1rateV Ue/ternalLidVU1e/ternalLidV UidVU1idV

UgraphLite!VU1graphLite!V

U1graphV Copyright 2010 Cacti Group

?)= :ield U1graphsV U1custo!erV U1custo!ersV

-escription Graphs container closing tag Custo!er container closing tag Custo!ers container closing tag

3ote4 .ltering the custo!er description after you have processed illing #ill re4uire the sa!e !odification to the track file description. ;/a!ple Custo!er ?)='
Ucusto!ersV Ucusto!erV UdescriptionV:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inA R 1U1descriptionV Ue!ailV illing7isp.co!U1e!ailV Ue!ailVcusto!er7isp.co!U1e!ailV Urate unitJP) PV1.00U1rateV U illingLti!efra!eV UtypeV!onthlyU1typeV UdayV22U1dayV UeveryV1U1everyV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV UgraphsV UgraphV UidV14U1idVUT++ Graph $itle' P:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inAP ++V UgraphLite!LidV605U1graphLite!LidVUT++ Co!!ent' P$otal 9ut' Nsu!'auto'current'2'autoNP++V UgraphLite!LidV610U1graphLite!LidVUT++ Co!!ent' P$otal In' Nsu!'auto'current'2'autoNP++V Urate unitJP) P typeJPco!!ittedPV0.60U1rateV Urate unitJP) P typeJPoverageP thresholdJP1000000000PV2.00U1rateV U1graphV UgraphV UidV13U1idVUT++ Graph $itle' P:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inAP ++V U1graphV U1graphsV U1custo!erV U1custo!ersV

In the e/a!ple a ove, the custo!er is defined #ith co!!itted1overage rate on the graph #ith an id of 14 and the graph #ith the id of 13 #ill use the custo!er defined rate.

Copyright 2010 Cacti Group

23 of 42

'illin (i%e Fra%e )Interval* .u$ .ection iii

*illing ti!e fra!e can e defined glo ally or per custo!er. If not supplied at a custo!er level, then the glo al default is used. Custo!er :ields' ?)= :ield U illingLti!efra!eV UtypeVU1typeV

-escription *illing ti!e fra!e container opening tag. -efined illing ti!e fra!e type' daily, #eekly, !onthly or i+!onthly. daily R illing occurs daily or every nth days as defined y the every field. #eekly R illing occurs #eekly or every nth #eeks as defined y the every field. !ontly R illing occurs !onthly on the defined day, 1 to last day of the !onth, every nth !onths as defined y every. i+!onthly R illing occurs t#ice !onthly on the 16 th and last day of the !onth.

UdayVU1dayV

Ksed only #hen type of !onthly is defined and denotes the day of the !onth #ith illing reoccurs. Ksing the key#ord FlastF denotes to use the last day of the !onth eing illed. Ksed y daily, #eekly and !onthly types, this denotes every nth days, #eeks or !onths to ill. ;/a!ple, you #ant to ill every 3 !onths, you #ould define every #ith a value of 3.

UeveryVU1everyV

UstartLdateVU1startLdateV 9ptional field to define #hen to start illing a custo!er. $his allo#s for you to pre+configure a custo!er and not get illing reports until needed. U1 illingLti!efra!eV *illing ti!e fra!e container closing tag

Copyright 2010 Cacti Group

24 of 42

;/a!ple *illing $i!e :ra!e ?)= %ections'

U illingLti!efra!eV UtypeVdailyU1typeV UeveryV1U1everyV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV U illingLti!efra!eV UtypeV#eeklyU1typeV UeveryV2U1everyV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV U illingLti!efra!eV UtypeV!onthlyU1typeV UdayV22U1dayV UeveryV1U1everyV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV U illingLti!efra!eV UtypeV i+!onthlyU1typeV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV

Copyright 2010 Cacti Group

26 of 42

Rate .u$ .ection iv

*illing rate section can e defined glo ally, per custo!er or per graph. $here are three types of illing rates 0egular, :i/ed and Co!!itted19verage. Co!!itted19verage rate ite!s !ust e defined together. 0egular, :i/ed and Co!!itted19verage can not e defined on the sa!e glo al, custo!er or graph. If this done, the 0egular rate #ill e applied. 0ate defined para!eters' ?)= :ield -escription type unit threshold $ype of illing rate, undefined @regularA, fi/ed, co!!itted or overage. Co!!itted and overage !ust e defined together. Knits to ill on, W @1000 itsA, ) @1000000 itsA or G @1000000000 itsA. 9nly defined #hen type is overage, this is the nu! er of $its or $,tes, allo#ed efore the overage rate is applied. 9verage rates are only applied to the a!ount over this defined nu! er. (&res&ol!s for 9t& Percentile are e-presse! in $its; $ut t&res&ol!s for 'an!7i!t& .u%%ation are !efine! in $,tes. 9nly defined #hen type is Bco!!ittedD or BundefinedD @0egularA. $his is the !ini!u! a!ount the custo!er #ill e illed. If the calculated rate falls elo# this a!ount, the !ini!u! #ill e the applied. ,hen applied to Bco!!ittedD rate and the rate a!ount is set to B0D, the rate #ill e displayed as fi/ed.

!ini!u!

;/a!ple 0ate 0egular @KndefinedA ?)= %ection'

Urate unitJD) DV0.60U1rateV

;/a!ple 0ate Co!!itted19verage ?)= %ection'

Urate unitJDG D typeJDco!!ittedDV0.26U1rateV Urate unitJDG D typeJDoverageD thresholdJD100000000DV0.60U1rateV

;/a!ple 0ate Co!!itted19verage #ith fi/ed Co!!itted 0ate ?)= %ection'

Urate unitJDG D typeJDco!!ittedD !ini!u!JD100DV0U1rateV Urate unitJDG D typeJDoverageD thresholdJD100000000DV0.60U1rateV

;/a!ple 0ate :i/ed ?)= %ection'

Urate typeJDfi/edDV100.00U1rateV

Copyright 2010 Cacti Group

23 of 42

Copyright 2010 Cacti Group

2E of 42

+%ail .u$ .ection v

;!ail entry can e defined glo ally or per custo!er. $here are t#o options that can e configured per e!ail address' <$)= for!ated report and if the C%V file is attached to the report. )ultiple e!ail entries can e defined, either glo ally or per custo!er. 0eports are e!ailed out in a consolidated fashion ased on the configured options for the e!ail addresses. ;/a!ple, if you have the e!ail address illing7isp.co! configured #ith ht!lJDnoD on all ut one custo!er, all ut that one custo!er #ill result in a te/t only e!ail to illing7isp.co!, ut the one e!ail configured #ith ht!lJDyesD @defaultA #ill generate a separate e!ail to illing7isp.co!. $o disa le e!ailing use the string value of B8K==D. ;!ail defined para!eters' ?)= :ield -escription ht!l csv type ByesD or BnoD, default ByesD, defined if e!ail report are <$)= for!atted #ith i!ages. ByesD or BnoD, default ByesD, defined if e!ail report has C%V attach!ent. BallD, B illingD or BthresholdD + -eter!ines #hat type of e!ails this address #ill get. all' *illing and $hreshold notification e!ails illing' *illing e!ail reports only threshold' $hreshold notification e!ails only ;/a!ple ;!ail ?)= &ara!eters'
Ue!ail ht!lJDyesD csvJDyesDVcusto!er7isp.co!U1e!ailV Ue!ail ht!lJDyesD csvJDyesD typeJDallDVcusto!er7isp.co!U1e!ailV Ue!ail ht!lJDyesD csvJDyesD typeJD illingDVcusto!er7isp.co!U1e!ailV Ue!ail ht!lJDnoD csvJDyesDV illing7isp.co!U1e!ailV Ue!ailVaccounting7isp.co!U1e!ailV Ue!ail typeJDthresholdDVtech7isp.co!U1e!ailV Ue!ailV8K==U1e!ailV

Copyright 2010 Cacti Group

22 of 42

Currenc, .u$ .ection vi

$he currency section of the configuration can e defined glo ally in the defaults section and1or per custo!er. $his allo#s for per custo!er calculations in difference currencies and1or defining default currency to use for all custo!ers. Currency defined section' ?)= :ield -escription UcurrencyV UpreVU1preV UpostVU1postV UprecisionV U1precisionV U1currencyV Currency container opening tag. &re te/t inserted efore a!ounts, default' BOD &ost te/t inserted after a!ounts, default' BD 8u! er of deci!al places to use for a!ount calculations, default' B2D Currency container closing tag.

;/a!ple 0ate 0egular ?)= %ection'

UcurrencyV UpreVOU1preV UpostV K%-U1postV UprecisionV2U1precisionV U1currencyV

Copyright 2010 Cacti Group

25 of 42

'ran!in +%ail Output .u$ .ection vii

*randing is i!portant, even if you donFt plan on e!ailing the reports to your custo!ers, it is i!portant to rand the e!ails. $his is done through so!e glo al configuration para!eters that are defined in the configuration file. $his is only defined in the glo al section of the configuration, not on a custo!er asis. Glo al ;!ail fields' ?)= :ield Uglo alV Ue!ailV UreturnLaddressV U1returnLaddressV Usu GectVU1su GectV UtitleVU1titleV UcsvLfileLna!eV U1csvLfileLna!eV UfooterVU1footerV U1e!ailV U1glo alsV

-escription Glo als opening tag ;!ail opening tag ;!ail address the illing reports appear to e co!ing fro!. ;!ail su Gect ;!ail title, also used as the na!e of the return e!ail address. $his is the na!e of the attached csv file #ithout the B.csvD e/tension. :ooter te/t to add to the end of illing e!ail reports ;!ail closing tag Glo als closing tag

;/a!ple Glo als ;!ail ?)= %ection'

Uglo alV Ue!ailV UreturnLaddressVreturn7isp.co!U1returnLaddressV Usu GectV)y I%& *illingU1su GectV UtitleV)y *illing $itleU1titleV UcsvLfileLna!eV!yLispL illingU1csvLfileLna!eV UfooterV$his is considered your illing invoice.U1footerV U1e!ailV U1glo alV

8ote' -o not add additional BUglo alVU1glo alVD tags, si!ply place the a ove section in the e/isting glo al section of your configuration file.

Copyright 2010 Cacti Group

30 of 42

+-portin to C./ )Co%%a .eparate! /alues* File .u$ .ection viii

$he I%& *illing script supports defining a glo al or a per custo!er e/port file using the BfileD para!eter. $he e/port files can e post processed y an e/ternal script y defining the Be/portLfileLprocessorD in the glo al configuration. $he post processing script !ust e e/ecuta le and accept the path of the e/ported C%V file as the first argu!ent. ;/a!ple post processing scripts are provided in the scripts su directory located #ith the I%& *illing %cript distri ution. $he follo#ing files are provided as e/a!ples'

postLprocess.pl R General e/a!ple post processing script to start #ith, #ritten in perl. postLprocessLta .pl R &ost processor that converts C%V to $.* deli!ited file, #ritten in perl. postLprocessL/!l.pl R &ost processor creates /!l e/port file, #ritten in perl. postLprocessLplatypusLe/a!ple.pl R ;/a!ple post processor creates an i!porta le C%V file for &laytpus *illing %yste!, #ritten in perl. $his script needs to e altered to fit your illing profiles in &laytpus. postLprocessLs4lLe/a!ple.pl R ;/a!ple post processor that creates %>= insert state!ents, #ritten in perl.

Glo al :ile ;/port fields' ?)= :ield Uglo alV UdefaultsV Ufile processJDyesDVU1fileV

-escription Glo als opening tag -efaults opening tag 8a!e of the file to #rite C%V data. &ara!eter BprocessD can e set to BnoD to disa le a particular custo!er or glo ally running the post processing script. -efault value of ByesD is assigned to the BprocessD para!eter if it is not defined. -efaults closing tag &ost processing script that is e/ecuted after the e/port file has een #ritten. $he first para!eter that is provided to the script is the path to the e/ported C%V data file. Glo als closing tag

U1defaultsV Ue/portLfileLprocessorV U1e/portLfileLprocessorV U1glo alsV

Copyright 2010 Cacti Group

31 of 42

;/a!ple Glo als :ile ;/port ?)= &ara!eters'

Uglo alV Ue/portLfileLprocessorVU1e/portLfileLprocessorV UdefaultsV Ufile processJDyesDVe/port.csvU1fileV Ue!ailV8K==U1e!ailV U1defaultsV U1glo alV

8ote' $hese are optional para!eters and should e added to the appropriate sections of your configuration.

Copyright 2010 Cacti Group

32 of 42

(&res&ol! (rac0in .u$ .ection i,ith version 1.0.10 of the I%& *illing %cript there co!es a very co!ple/ feature that allo#s you to infor! you custo!ers at #hat ti!e an overage @e/ceed co!!itted rateA occurred. ,hile so!e !ay think that this is an easy task, and it is for *and#idth %u!!ation, it ho#ever is not for 8th &ercentile. $he follo#ing options #hen ena led #ill allo# for overage notifications to e sent to custo!ers as #ell as reporting to the custo!er at #hat ti!e an overage occurred. ;na ling threshold tracking #ill use !ore !e!ory and processor po#er. It is strongly suggested that you follo# est practices y running the I%& *illing %cript every day. $his #ay, the C&K usage to calculate ti!e fra!e threshold data #ill occur over everyday of the illing period. Glo al $hreshold $racking fields' ?)= :ield Uglo alV UthresholdV Uena ledVU1ena ledV UnotificationVU1notificationV Usu GectVU1su GectV UtitleVU1titleV U1thresholdV U1glo alsV

-escription Glo als opening tag $hreshold opening tag ;na le threshold tracking for notification on illing reports of #hen overage occurred. -efault BnoD, set to ByesD to activate. ;na le threshold notifications e!ails #hen custo!ers e/ceed their co!!itted rate. -efault BnoD, set to ByesD to ena le. %u Gect line to set for notification e!ails. $itle to set the title and na!e of the fro! e!ail for notification e!ails. $hreshold closing tag Glo als closing tag

89$;' *ecause of the nature of 8th &ercentile calculations, a custo!er could e notified !ultiple ti!es a out potentially going over their co!!itted rate, ut in the end they !ay not go over their co!!itted rate. *ecause of that the 8th &ercentile notifications are li!ited to sending out one if an overage is detected, !aking note and not sending out another notification until the 8th percentile value has fallen elo# the threshold and risen a ove it again. . !a/i!u! of 4 notifications per illing period #ill e sent, e4ually spaced over the illing period. 89$;' 8otifications are li!ited to once a day, and are notifications of overages occurring on the prior day.

Copyright 2010 Cacti Group

33 of 42

;/a!ple Glo als $hreshold $racking ?)= &ara!eters'

Uglo alV UthresholdV Uena ledVyesU1ena ledV UnotificationVyesU1notificationV Usu GectV;!ail 8otification %u GectU1su GectV UtitleV;!ail .ddress $itleU1titleV U1thresholdV U1glo alV

8ote' $hese are optional para!eters and should e added to the appropriate sections of your configuration.

Copyright 2010 Cacti Group

34 of 42

Usin t&e $uil! Co%%an! .u$ .ection $he uild co!!and line option allo#s you to uild an ?)= configuration file for your custo!ers. %o!e !odification of the ?)= configuration file #ill e needed after it is created. $he rates, illing intervals and the custo!er descriptions should e revie#ed and edited. $he follo#ing co!!and line options are availa le to the uild co!!and'

9ption uild filter e!ail e!ailLnoLcsv

-escription 0e4uired to uild a configuration file. If file na!e is defined, then the configuration #ill e #ritten to the defined file. Ksed to li!it the uilt configuration file to a list of graph idFs. Graph idFs are co!!a separated string #ith no spaces. If defined, sets the default e!ail address in the uilt configuration file. If defined, set the default e!ail to no send csv attach!ents on illing reports

e!ailLnoLht!l If defined, sets the default e!ail to not send ht!l illing reports

3!amp'e 11 R *uild co!!and line

Copyright 2010 Cacti Group

36 of 42

+-a%ple Confi uration .u$ .ection -i

UI/!l versionJF1.0F encodingJFK$:+2F standaloneJFyesFIV UcactiL illerV Uglo alV UdefaultsV Ue!ailV illing7isp.co!U1e!ailV Urate unitJP) PV0.06U1rateV U illingLti!efra!eV UtypeV!onthlyU1typeV UdayVlastU1dayV UeveryV1U1everyV UstartLdateV2003+10+01U1startLdateV U1 illingLti!efra!eV U1defaultsV U1glo alV Ucusto!ersV Ucusto!erV UdescriptionV:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inA R 1U1descriptionV Ue!ail ht!lJDnoDV illing7isp.co!U1e!ailV Ue!ail csvJDnoDVcusto!er7isp.co!U1e!ailV Urate unitJP) PV1.00U1rateV U illingLti!efra!eV UtypeV i+!onthlyU1typeV UstartLdateV2003+05+21U1startLdateV U1 illingLti!efra!eV UgraphsV UgraphV UidV14U1idVUT++ Graph $itle' P:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inAP ++V UgraphLite!LidV605U1graphLite!LidVUT++ Co!!ent' P$otal 9ut' Nsu!'auto'current'2'autoNP++V UgraphLite!LidV610U1graphLite!LidVUT++ Co!!ent' P$otal In' Nsu!'auto'current'2'autoNP++V Urate unitJP) P typeJPco!!ittedPV0.60U1rateV Urate unitJP) P typeJPoverageP thresholdJP1000000000PV2.00U1rateV U1graphV UgraphV UidV13U1idVUT++ Graph $itle' P:ire#all + $raffic + 152.132.1.1 @&I? :ire#all inAP ++V U1graphV U1graphsV U1custo!erV U1custo!ersV

Copyright 2010 Cacti Group

33 of 42

(rac0 File .u$ .ection -ii

<uestion: ,hat is the track fileI Ans7er: $he track file is a /!l file that contains infor!ation #hen a custo!ers illing report #as last successfully generated. <uestion: -o I need to create a track fileI Ans7er: 8o, the track file #ill e created the first ti!e that so!ething needs to e #ritten to it. <uestion: ,hy does the I%& *illing %cript re4uire the B+trackJD option for the B+infoD co!!andI Ans7er: *ecause if the file e/ists, it #ill sho# the infor!ation stored in the track file in the output of the B+infoD co!!and. <uestion: ,hat is the for!at of the track fileI Ans7er: ,hile not really that i!portant to anyone using the I%& *illing %cript, the for!at is very si!ple ?)= records that contain the custo!er description and ti!esta!p of the last illing cycle end ti!e. If threshold tracking is ena led, this file #ill also contain threshold tracking cache infor!ation.

Copyright 2010 Cacti Group

3E of 42

*esting
Section 6
%o, you have your configuration created for all your custo!er and you are ready to test it. $his section #ill e/plain ho# testing can e perfor!ed and #hat considerations should e kno#n #hen testing. ;/a!ple testing co!!and line'
php ispL illing.php +d +configJconfig1custo!ers./!l +trackJconfig1track./!l +trackLnoL#rite +startLdateJP200E+02+01 00'00'00P +currentLti!eJP200E+03+01 00'00'01P

$he a ove e/a!ple #ould e used to test a !onthly illing custo!er. $he start date #ould e overridden #ith the first day of :e ruary, B200E+02+01 00'00'00D and the current ti!e used y the illing script #ould e overridden #ith first day of )arch, B200E+03+01 00'00'00D. 9ote: I!portant to understand that the current ti!e override is an internal varia le in the illing script. -o not define the last day of :e ruary, ecause in nor!al operation, the illing script needs to #ait till the ti!e fra!e that it is illing for has past. $his !eans that you !ust define a current ti!e one day fro! the last day of the illing interval you are testing. $he B+dD co!!and line para!eter is i!portant to have #hile testing. $his #ill output de ug a out #hat the illing script is doing. -epending on your configuration, this could e a lot of infor!ation.

Copyright 2010 Cacti Group

32 of 42

CS7 File Formats

Section 8 9mail CS7 File Su" Section i
$he follo#ing ta le outlines the fields in the C%V file in the order #hich they appear. :ield Custo!er -escription *illing &eriod %tart *illing &eriod ;nd Graph $itle $ype Interval ;very 0ate $ype 0ate .!ount 0ate Knit *its $otal 9verage 9ccurred -escription -escription of custo!er %tart of illing period ;nd of illing period $itle of Graph $ype of Cacti graph varia le *illing interval *illing interval repeat factor 0ate type &er unit rate a!ount 0ate unit 8u! er of its used in illing calculation Calculated total If threshold tracking is ena led, this #ill have #hen the overage occurred

Copyright 2010 Cacti Group

35 of 42

9.port CS7 File Su" Section ii

$he follo#ing ta le outlines the fields in the C%V file in the order #hich they appear.

:ield Custo!er-escription Custo!er;/ternalId *illing&eriod%tart *illing&eriod;nd GraphId Graph$itle Graph;/ternalId GraphIte!Id $ype Interval ;very 0ate$ype 0ate.!ount 0ateKnit *its $otal 9verage9ccurred

-escription -escription of custo!er ;/ternal id defined for custo!er %tart of illing period ;nd of illing period Cacti graph id $itle of graph ;/ternal id defined for graph Cacti graph ite! id $ype of Cacti graph varia le *illing interval *illing interval repeat factor 0ate type &er unit rate a!ount 0ate unit 8u! er of its used in illing calculation Calculated total If threshold tracking is ena led, this #ill have #hen the overage occurred

Copyright 2010 Cacti Group

40 of 42

Comman :ine Reference

Section &
Cacti ISP Billing Script, Copyright 2006-2008 - The Cacti Group Version: !0!" usage: -con#ig$%#ile& -trac'$%#ile& %-chec'& %-(uil)$%#ile& %-#ilter$%i)&&& %-process& %-list& %-e*ail$%e*ail&& %-e*ail+no+ht*l& %-ht*l+no+cs,& %-start+)ate$%)ate&& %-current+ti*e$%)ate&& %-tech& %-)& %--)e(ug& %-h& %--help& %-,& %--,ersion& -con#ig$%#ile& - Billing con#iguration #ile -trac'$%#ile& - -ate trac'ing #ile -trac'+no+.rite - -o not up)ate the )ate trac'ing #ile -trac'+clear+cache - Clear threshol) trac'ing cache #ro* trac' #ile -chec' - Chec' (illing con#iguration #ile -(uil)$%#ile& - Buil) e/a*ple con#iguration #ile #ro* syste*, supplying #ilena*e is optional, )e#ault e/a*ple!/*l -#ilter$%i)& - 0nly use) (y the (uil) co**an) to li*it con#iguration (uil) to the supplie) graph i)s, co**a )eli*ite) -in#o - -isplay in#or*ation on the (illing con#iguration #ile -list - -isplay list o# graphs an) titles that are (illa(le -e*ail$%e*ail& - 0,erri)e con#iguration e*ail a))resses, all custo*er reports .ill (e e*aile) to the supplie) e*ail -e*ail+no+ht*l - 0nly use) .hen e*ail o,erri)e ena(le), glo(ally set no ht*l e*ails -e*ail+no+cs, - 0nly use) .hen e*ail o,erri)e ena(le), glo(ally set no cs, attach*ents -start+)ate$%)ate& - 1se) to o,erri)e trac' )ate an) start )ate #or testing an) reruns -current+ti*e$%)ate& - 1se) to o,erri)e current ti*e #or testing an) reruns -tech - 2rites out technical support #ile -) --)e(ug - -isplay ,er(ose output )uring e/ecution -, --,ersion - -isplay this help *essage -h --help - -isplay this help *essage

$here are !any co!!and line options, ut only t#o are re4uired for nor!al operations BconfigD and BtrackD. 9utline elo# are detailed e/planations for each displayed co!!and line option. 9ption configJ trackJ trackLnoL#rite check uild -escription &ath to the custo!er configuration ?)= file &ath to the track ?)= file. $his file is used to track the last ti!e a custo!er #as processed. $he description defined for the custo!er is #hat is used for tracking. -isa les updating the tracking file. Checks the configuration file for issues. *uilds a configuration file fro! the graphs configured in Cacti that are considered illa le. 9ptional filena!e can e supplied. Kse the filter option to li!it #hat graphs are created. =ist of graph ids to uild a configuration. $his is only used y the uild co!!and line option. -isplays infor!ation a out the configured custo!ers. 41 of 42

trackLclearLcache Clears threshold tracking cache data fro! track file and e/its.

filter info

Copyright 2010 Cacti Group

9ption list e!ail

-escription -isplays a list of graphs configured in Cacti that are considered illa le. 9verriding e!ail address for processing. ,hen processing custo!ers and this is defined, all configured custo!ers #ill e e!ailed to the defined e!ail. $his para!eter is also used #hen uilding configuration #ith the uild co!!and line option. 9nly used #hen e!ail override is ena led, turns off <$)= for!atted e!ail reports, !aking the! te/t only. 9nly used #hen e!ail override is ena led, turns off the attach!ent of the C%V file to e!ail reports. 9verride the track file and configuration start dates for custo!ers. Ksed for testing configurations. 9verride the current ti!e used y the illing script. Ksed for testing configurations. ,rites out technical support file, used y technical support to get syste! infor!ation -e ug !ode, outputs ver ose infor!ation a out processing -isplays help and version -isplays help and version

e!ailLnoLht!l e!ailLnoLcsv startLdateJ currentLti!eJ tech d or de ug v or version h or help

Copyright 2010 Cacti Group

42 of 42