From 36ae05cde20829c62ea16f897866c9cf45f5353f Mon Sep 17 00:00:00 2001 From: DanB Date: Fri, 15 Aug 2014 14:25:54 +0200 Subject: [PATCH] FreeSWITCH Tutorial refactoring --- docs/tut_cgrates_installs.rst | 47 +++++++++++ docs/tut_cgrates_usage.rst | 152 ++++++++++++++++++++++++++++++++++ docs/tut_freeswitch.rst | 2 + docs/tut_freeswitch_csv.rst | 4 +- pkg/debian/rules | 8 +- 5 files changed, 207 insertions(+), 6 deletions(-) create mode 100644 docs/tut_cgrates_installs.rst create mode 100644 docs/tut_cgrates_usage.rst diff --git a/docs/tut_cgrates_installs.rst b/docs/tut_cgrates_installs.rst new file mode 100644 index 000000000..8eb8a8fd3 --- /dev/null +++ b/docs/tut_cgrates_installs.rst @@ -0,0 +1,47 @@ +**CGRateS** Installation +======================== + +As operating system we have choosen Debian Wheezy, since all the software components we use provide packaging for it. + +Prerequisites +------------- + +Some components of **CGRateS** (whether enabled or not is up to the administrator) depend on external software like: + +- Git_ used by **CGRateS** History Server as archiver. +- Redis_ to serve as Rating and Accounting DB for **CGRateS**. +- MySQL_ to serve as StorDB for **CGRateS**. + +We will install them in one shot using the command bellow. + +:: + + apt-get install git redis-server mysql-server + +*Note*: For simplicity sake we have used as MySQL_ root password when asked: *CGRateS.org*. + + +Installation +------------ + +Installation steps are provided within **CGRateS** `install documentation `_. + +To get **CGRateS** installed execute the following commands over ssh console: + +:: + + cd /etc/apt/sources.list.d/ + wget -O - http://apt.itsyscom.com/conf/cgrates.gpg.key | apt-key add - + wget http://apt.itsyscom.com/conf/cgrates.apt.list + apt-get update + apt-get install cgrates + +As described in post-install section, we will need to set up the MySQL_ database (using *CGRateS.org* as our root password): + +:: + + cd /usr/share/cgrates/storage/mysql/ + ./setup_cgr_db.sh root CGRateS.org localhost + + +At this point we have **CGRateS** installed but not yet configured. To facilitate the understanding and speed up the process, **CGRateS** comes already with the configurations used in these tutorials, available in the */usr/share/cgrates/tutorials* folder, so we will load them custom on each tutorial case. diff --git a/docs/tut_cgrates_usage.rst b/docs/tut_cgrates_usage.rst new file mode 100644 index 000000000..255de23fd --- /dev/null +++ b/docs/tut_cgrates_usage.rst @@ -0,0 +1,152 @@ +**CGRateS** Usage +================= + +Loading **CGRateS** Tariff Plans +-------------------------------- + +Before proceeding to this step, you should have **CGRateS** installed and started with custom configuration, depending on the tutorial you have followed. + +For our tutorial we load again prepared data out of shared folder, containing following rules: + +- Create the necessary timings (always, asap, peak, offpeak). +- Configure 3 destinations (1002, 1003 and 10 used as catch all rule). +- As rating we configure the following: + + - Rate id: *RT_10CNT* with connect fee of 20cents, 10cents per minute for the first 60s in 60s increments followed by 5cents per minute in 1s increments. + - Rate id: *RT_20CNT* with connect fee of 40cents, 20cents per minute for the first 60s in 60s increments, followed by 10 cents per minute charged in 1s increments. + - Rate id: *RT_40CNT* with connect fee of 80cents, 40cents per minute for the first 60s in 60s increments, follwed by 20cents per minute charged in 10s increments. + - Will charge by default *RT_40CNT* for all FreeSWITCH_ destinations during peak times (Monday-Friday 08:00-19:00) and *RT_10CNT* during offpeatimes (rest). + - Account 1001 will receive a special *deal* for 1002 and 1003 destinations during peak times with *RT_20CNT*, otherwise having default rating. + +- Create 5 accounts (equivalent of FreeSWITCH default test users - 1001, 1002, 1003, 1004, 1007). +- Create 1 account alias (1006 - alias of account 1002). +- Create 1 rating profile alias (1006 - alias of rating profile 1001). +- 1002, 1003, 1004 will receive 10units of *\*monetary* balance. +- 1001 will receive 5 units of general *\*monetary* and 5 units of shared balance in the shared group "SHARED_A". +- 1007 will receive 0 units of shared balance in the shared group "SHARED_A". +- Define the shared balance "SHARED_A" with debit policy *\*highest*. +- For each balance created, attach 3 triggers to control the balance: log on balance=2, log on balance=20, log on 5 mins talked towards 10xx destination. + +:: + + cgr-loader -verbose -path=/usr/share/cgrates/tariffplans/tutorial + +To verify that all actions successfully performed, we use following *cgr-console* commands: + +- Make sure our rates were loaded successfully and they are already in cache: + + :: + + cgr-console cache_stats + cgr-console 'cache_age 1002' + cgr-console 'cache_age RP_RETAIL1' + cgr-console 'cache_age *out:cgrates.org:call:*any' + cgr-console 'cache_age LOG_WARNING' + +- Make sure all our balances were topped-up: + + :: + + cgr-console 'account Tenant="cgrates.org" Account="1001"' + cgr-console 'account Tenant="cgrates.org" Account="1002"' + cgr-console 'account Tenant="cgrates.org" Account="1003"' + cgr-console 'account Tenant="cgrates.org" Account="1004"' + cgr-console 'account Tenant="cgrates.org" Account="1005"' + +- Query call costs so we can see our calls will have expected costs (final cost will result as sum of *ConnectFee* and *Cost* fields): + + :: + + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:00:20Z"' + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:01:25Z"' + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1003" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:00:20Z"' + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1003" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:01:25Z"' + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1004" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:00:20Z"' + cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1004" TimeStart="2014-08-04T13:00:00Z" TimeEnd="2014-08-04T13:01:25Z"' + + +Test calls +---------- + + +1001 -> 1002 +~~~~~~~~~~~~ + +Since the user 1001 is marked as *prepaid* inside FreeSWITCH_ directory configuration, calling between 1001 and 1002 should generate pre-auth and prepaid debits which can be checked with *get_account* command integrated within *cgr-console* tool. Charging will be done based on time of day as described above. + +*Note*: An important particularity to note here is the ability of **CGRateS** SessionManager to refund units booked in advance (eg: if debit occurs every 10s and rate increments are set to 1s, the SessionManager will be smart enough to refund pre-booked credits for calls stoped in the middle of debit interval). + +Check that 1001 balance is properly debitted, during the call, and moreover considering that general balance has priority over the shared one debits for this call should take place at first out of general balance. + +:: + + cgr-console 'account Tenant="cgrates.org" Account="1001"' + + +1002 -> 1001 +~~~~~~~~~~~~ + +The user 1002 is marked as *postpaid* inside FreeSWITCH_ hence his calls will be debited at the end of the call instead of during a call and his balance will be able to go on negative without influencing his new calls (no pre-auth). + +To check that we had debits we use again console command, this time not during the call but at the end of it: + +:: + + cgr-console 'account Tenant="cgrates.org" Account="1002"' + + +1003 -> 1001 +~~~~~~~~~~~~ + +The user 1003 is marked as *pseudoprepaid* inside FreeSWITCH_ hence his calls will be considered same as prepaid (no call setups possible on negative balance due to pre-auth mechanism) but not handled automatically by session manager. His call costs will be calculated directly out of CDRs and balance updated by the time when mediation process occurs. This is sometimes a good compromise of prepaid running without influencing performance (there are no recurrent call debits during a call). + +To check that there are no debits during or by the end of the call, but when the CDR reaches the CDRS component(which is close to real-time in case of *http-json* CDRs): + +:: + + cgr-console 'account Tenant="cgrates.org" Account="1003"' + + +1004 -> 1001 +~~~~~~~~~~~~ + +The user 1004 is marked as *rated* inside FreeSWITCH_ hence his calls not interact in any way with accounting subsystem. The only action perfomed by **CGRateS** related to his calls wil be rating/mediation of his CDRs. + + +1006 -> 1002 +~~~~~~~~~~~~ + +Since the user 1006 is marked as *prepaid* inside FreeSWITCH_ directory configuration, calling between 1006 and 1002 should generate pre-auth and prepaid debits which can be checked with *get_account* command integrated within *cgr-console* tool. One thing to note here is that 1006 is not defined as an account inside CGR Accounting Subsystem but as an alias of another account, hence *get_account* ran on 1006 will return "not found" and the debits can be monitored on the real account which is 1001. + +Check that 1001 balance is properly debitted, during the call, and moreover considering that general balance has priority over the shared one debits for this call should take place at first out of general balance. + +:: + + cgr-console 'account Tenant="cgrates.org" Account="1006"' + cgr-console 'account Tenant="cgrates.org" Account="1001"' + + +1007 -> 1002 +~~~~~~~~~~~~ + +Since the user 1007 is marked as *prepaid* inside FreeSWITCH_ directory configuration, calling between 1007 and 1002 should generate pre-auth and prepaid debits which can be checked with *get_account* command integrated within *cgr-console* tool. Since 1007 has no units left into his accounts but he has one balance marked as shared, debits for this call should take place in accounts which are a part of the same shared balance as the one of *1007/SHARED_A*, which in our scenario corresponds to the one of the account 1001. + +Check that call can proceed even if 1007 has no units left into his own balances, and that the costs attached to the call towards 1002 are debited from the balance marked as shared within account 1001. + +:: + + cgr-console 'account Tenant="cgrates.org" Account="1007"' + cgr-console 'account Tenant="cgrates.org" Account="1001"' + + +Fraud detection +~~~~~~~~~~~~~~~ + +Since we have configured some action triggers (more than 20 units of balance topped-up or less than 2 and more than 5 units spent on *FS_USERS* we should be notified over syslog when things like unexpected events happen (eg: fraud with more than 20 units topped-up). To verify this mechanism simply add some random units into one account's balance: + +:: + + cgr-console 'balance_set Tenant="cgrates.org" Account="1003" Direction="*out" Value=23' + tail -f /var/log/syslog -n 20 + +*Note*: The actions are only executed once, in order to be repetive they need to be recurrent or reset via a manual or automated process. \ No newline at end of file diff --git a/docs/tut_freeswitch.rst b/docs/tut_freeswitch.rst index 0db4078a5..184f1f0ba 100644 --- a/docs/tut_freeswitch.rst +++ b/docs/tut_freeswitch.rst @@ -8,8 +8,10 @@ In these tutorials we exemplify few cases of integration between FreeSWITCH_ and :maxdepth: 2 tut_freeswitch_installs + tut_cgrates_installs tut_freeswitch_csv tut_freeswitch_json + tut_cgrates_usage .. _FreeSWITCH: http://www.freeswitch.org/ diff --git a/docs/tut_freeswitch_csv.rst b/docs/tut_freeswitch_csv.rst index 3bc8a545a..18441e7bd 100644 --- a/docs/tut_freeswitch_csv.rst +++ b/docs/tut_freeswitch_csv.rst @@ -1,5 +1,5 @@ -Case 1: FreeSWITCH_ generating *.csv* CDRs -========================================== +FreeSWITCH_ generating *.csv* CDRs +================================== Scenario -------- diff --git a/pkg/debian/rules b/pkg/debian/rules index 4270b8889..716004c41 100755 --- a/pkg/debian/rules +++ b/pkg/debian/rules @@ -29,10 +29,10 @@ binary-arch: clean cp $(SRCDIR)/data/conf/cgrates.cfg $(PKGDIR)/etc/cgrates/ mkdir -p $(PKGDIR)/usr/share/cgrates cp -r $(SRCDIR)/data/* $(PKGDIR)/usr/share/cgrates/ - mkdir -p $(PKGDIR)/var/log/cgrates/cdr/cdrc/in - mkdir -p $(PKGDIR)/var/log/cgrates/cdr/cdrc/out - mkdir -p $(PKGDIR)/var/log/cgrates/cdr/cdre/csv - mkdir -p $(PKGDIR)/var/log/cgrates/cdr/cdre/fwv + mkdir -p $(PKGDIR)/var/log/cgrates/cdrc/in + mkdir -p $(PKGDIR)/var/log/cgrates/cdrc/out + mkdir -p $(PKGDIR)/var/log/cgrates/cdre/csv + mkdir -p $(PKGDIR)/var/log/cgrates/cdre/fwv mkdir -p $(PKGDIR)/var/log/cgrates/history dh_strip dh_compress