mirror of
https://github.com/cgrates/cgrates.git
synced 2026-02-11 10:06:24 +05:00
Revise tutorial documentation
This commit is contained in:
ionutboangiu
committed by
Dan Christian Bogos
Dan Christian Bogos
parent
4f24be272c
commit
18c4fbcb8b
@@ -27,7 +27,8 @@ import sys, os
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = [
|
||||
'sphinx.ext.todo',
|
||||
'sphinx_copybutton'
|
||||
'sphinx_copybutton',
|
||||
'sphinx_tabs.tabs'
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
@@ -51,7 +52,7 @@ copyright = u'2012-2023, ITsysCOM GmbH'
|
||||
# built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = '0.11.0'
|
||||
version = '0.11'
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = '0.11.0~dev'
|
||||
|
||||
@@ -94,7 +95,7 @@ pygments_style = 'sphinx'
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
html_theme = 'default'
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Theme options are theme-specific and customize the look and feel of a theme
|
||||
# further. For a list of options available for each theme, see the
|
||||
|
||||
@@ -17,7 +17,7 @@ Welcome to `CGRateS`_'s documentation!
|
||||
configuration
|
||||
administration
|
||||
advanced
|
||||
tutorials
|
||||
tutorial
|
||||
troubleshooting
|
||||
miscellaneous
|
||||
|
||||
|
||||
@@ -36,7 +36,7 @@ You can add the CGRateS repository to your system's sources list as follows:
|
||||
sudo mv apt.cgrates.org.asc /etc/apt/trusted.gpg.d/
|
||||
|
||||
# Add the repository to the apt sources list
|
||||
echo "deb http://apt.cgrates.org/debian/ v0.10 main" | sudo tee /etc/apt/sources.list.d/cgrates.list
|
||||
echo "deb http://apt.cgrates.org/debian/ nightly main" | sudo tee /etc/apt/sources.list.d/cgrates.list
|
||||
|
||||
# Update the system repository and install CGRateS
|
||||
sudo apt-get update -y
|
||||
@@ -46,7 +46,7 @@ Alternatively, you can manually install a specific .deb package as follows:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wget http://pkg.cgrates.org/deb/v0.10/cgrates_current_amd64.deb
|
||||
wget http://pkg.cgrates.org/deb/nightly/cgrates_current_amd64.deb
|
||||
sudo dpkg -i ./cgrates_current_amd64.deb
|
||||
|
||||
.. note::
|
||||
@@ -63,7 +63,7 @@ For .rpm distros, we are using copr to manage the CGRateS packages:
|
||||
|
||||
# sudo yum install -y dnf-plugins-core on RHEL 8 or CentOS Stream
|
||||
sudo dnf install -y dnf-plugins-core
|
||||
sudo dnf copr -y enable cgrates/v0.10
|
||||
sudo dnf copr -y enable cgrates/master
|
||||
sudo dnf install -y cgrates
|
||||
|
||||
- For older distributions:
|
||||
@@ -71,7 +71,7 @@ For .rpm distros, we are using copr to manage the CGRateS packages:
|
||||
.. code-block:: bash
|
||||
|
||||
sudo yum install -y yum-plugin-copr
|
||||
sudo yum copr -y enable cgrates/v0.10
|
||||
sudo yum copr -y enable cgrates/master
|
||||
sudo yum install -y cgrates
|
||||
|
||||
To install a specific version of the package, run:
|
||||
@@ -81,7 +81,7 @@ To install a specific version of the package, run:
|
||||
sudo dnf install -y cgrates-<version>.x86_64
|
||||
|
||||
.. note::
|
||||
The entire archive of CGRateS rpm packages is available at https://copr.fedorainfracloud.org/coprs/cgrates/v0.10/packages/.
|
||||
The entire archive of CGRateS rpm packages is available at https://copr.fedorainfracloud.org/coprs/cgrates/master/packages/.
|
||||
|
||||
Installing from Source
|
||||
----------------------
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
sphinx_rtd_theme==1.2.0
|
||||
sphinx==6.2.1
|
||||
sphinx_copybutton==0.5.2
|
||||
sphinx_copybutton==0.5.2
|
||||
sphinx_tabs==3.4.1
|
||||
@@ -16,6 +16,7 @@ docutils==0.18.1
|
||||
# via
|
||||
# sphinx
|
||||
# sphinx-rtd-theme
|
||||
# sphinx-tabs
|
||||
idna==3.4
|
||||
# via requests
|
||||
imagesize==1.4.1
|
||||
@@ -29,7 +30,9 @@ markupsafe==2.1.2
|
||||
packaging==23.1
|
||||
# via sphinx
|
||||
pygments==2.15.1
|
||||
# via sphinx
|
||||
# via
|
||||
# sphinx
|
||||
# sphinx-tabs
|
||||
requests==2.30.0
|
||||
# via sphinx
|
||||
snowballstemmer==2.2.0
|
||||
@@ -39,11 +42,14 @@ sphinx==6.2.1
|
||||
# -r requirements.in
|
||||
# sphinx-copybutton
|
||||
# sphinx-rtd-theme
|
||||
# sphinx-tabs
|
||||
# sphinxcontrib-jquery
|
||||
sphinx-copybutton==0.5.2
|
||||
# via -r requirements.in
|
||||
sphinx-rtd-theme==1.2.0
|
||||
# via -r requirements.in
|
||||
sphinx-tabs==3.4.1
|
||||
# via -r requirements.in
|
||||
sphinxcontrib-applehelp==1.0.4
|
||||
# via sphinx
|
||||
sphinxcontrib-devhelp==1.0.2
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
Asterisk_ Integration Tutorials
|
||||
===============================
|
||||
|
||||
In these tutorials we exemplify a few cases of integration between Asterisk_ and CGRateS_. We start with common steps, installation and postinstall processes, then we dive into particular configurations, depending on the case we run.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tut_asterisk_installs
|
||||
tut_jitsi_installs
|
||||
tut_asterisk_ari
|
||||
tut_cgrates_usage
|
||||
|
||||
.. _Asterisk: http://www.asterisk.org/
|
||||
.. _CGRateS: http://www.cgrates.org/
|
||||
|
||||
@@ -1,62 +0,0 @@
|
||||
Asterisk_ interaction via *ARI*
|
||||
===========================================
|
||||
|
||||
Scenario
|
||||
--------
|
||||
|
||||
- Asterisk out of *basic-pbx* configuration samples.
|
||||
|
||||
- Considering the following users: 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1007-rated.
|
||||
|
||||
- **CGRateS** with following components:
|
||||
|
||||
- CGR-SM started as translator between Asterisk_ and **CGR-RALs** for both authorization events (prepaid/pseudoprepaid) as well as postpaid ones.
|
||||
- CGR-CDRS component processing raw CDRs from CGR-SM component and storing them inside CGR StorDB.
|
||||
- CGR-CDRE exporting rated CDRs from CGR StorDB (export path: */tmp*).
|
||||
- CGR-History component keeping the archive of the rates modifications (path browsable with git client at */tmp/cgr_history*).
|
||||
|
||||
|
||||
Starting Asterisk_ with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/asterisk_ari/asterisk/etc/init.d/asterisk start
|
||||
|
||||
|
||||
To verify that Asterisk_ is running we run the console command:
|
||||
|
||||
::
|
||||
|
||||
asterisk -r -s /tmp/cgr_asterisk_ari/asterisk/run/asterisk.ctl
|
||||
|
||||
ari show status
|
||||
|
||||
|
||||
Starting **CGRateS** with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/asterisk_ari/cgrates/etc/init.d/cgrates start
|
||||
|
||||
Make sure that cgrates is running
|
||||
|
||||
::
|
||||
|
||||
cgr-console status
|
||||
|
||||
|
||||
CDR processing
|
||||
--------------
|
||||
|
||||
At the end of each call Asterisk_ will generate an CDR event and due to automatic handler registration built in **CGRateS-SM** component, this will be directed towards the port configured inside *cgrates.json*. This event will reach inside **CGRateS** through the *SM* component (close to real-time). Once in-there it will be instantly rated and be ready for export.
|
||||
|
||||
|
||||
**CGRateS** Usage
|
||||
-----------------
|
||||
|
||||
Since it is common to most of the tutorials, the example for **CGRateS** usage is provided in a separate page `here <http://cgrates.readthedocs.org/en/latest/tut_cgrates_usage.html>`_
|
||||
|
||||
|
||||
.. _Asterisk: http://www.asterisk.org/
|
||||
@@ -1,64 +0,0 @@
|
||||
Software installation
|
||||
=====================
|
||||
|
||||
We have chosen Debian 11 (Bullseye) as the operating system.
|
||||
|
||||
CGRateS
|
||||
-------
|
||||
|
||||
*CGRateS* can be installed using the instructions found :ref:`here<installation>`.
|
||||
|
||||
Asterisk
|
||||
--------
|
||||
|
||||
To install Asterisk, follow these steps:
|
||||
|
||||
1. Install the necessary dependencies:
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install build-essential libasound2-dev autoconf openssl libssl-dev libxml2-dev libncurses5-dev uuid-dev sqlite3 libsqlite3-dev pkg-config libedit-dev libjansson-dev
|
||||
|
||||
2. Download Asterisk:
|
||||
|
||||
Replace `<ASTERISK_VERSION>` with the desired version, e.g., `20-current`.
|
||||
|
||||
::
|
||||
|
||||
wget https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-<ASTERISK_VERSION>.tar.gz -P /tmp
|
||||
|
||||
3. Extract the downloaded archive:
|
||||
|
||||
::
|
||||
|
||||
sudo tar -xzvf /tmp/asterisk-<ASTERISK_VERSION>.tar.gz -C /usr/src
|
||||
|
||||
4. Change the working directory to the extracted Asterisk source:
|
||||
|
||||
Replace `<ASTERISK_MAJOR_VERSION>` with the major version number of the downloaded Asterisk version, e.g., `20`.
|
||||
|
||||
::
|
||||
|
||||
cd /usr/src/asterisk-<ASTERISK_MAJOR_VERSION>*/
|
||||
|
||||
5. Compile and install Asterisk:
|
||||
|
||||
::
|
||||
|
||||
sudo ./configure --with-jansson-bundled
|
||||
sudo make menuselect.makeopts
|
||||
sudo make
|
||||
sudo make install
|
||||
sudo make samples
|
||||
sudo make config
|
||||
sudo ldconfig
|
||||
|
||||
6. Create the Asterisk system user:
|
||||
|
||||
::
|
||||
|
||||
sudo adduser --quiet --system --group --disabled-password --shell /bin/false --gecos "Asterisk" asterisk
|
||||
|
||||
After the installation is complete, we will proceed to load the configuration based on the specific tutorial case provided in the subsequent section.
|
||||
|
||||
.. _Asterisk: http://www.asterisk.org/
|
||||
@@ -1,110 +0,0 @@
|
||||
**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.
|
||||
- Rate id: *RT_1CNT* having no connect fee and a rate of 1 cent per minute, chargeable in 1 minute increments.
|
||||
- Rate id: *RT_1CNT_PER_SEC* having no connect fee and a rate of 1 cent per second, chargeable in 1 second increments.
|
||||
|
||||
- Accounting part will have following configured:
|
||||
|
||||
- Create 3 accounts: 1001, 1002, 1003.
|
||||
- 1001, 1002 will receive 10units of **\*monetary** balance.
|
||||
|
||||
|
||||
::
|
||||
|
||||
cgr-loader -verbose -path=/usr/share/cgrates/tariffplans/tutorial
|
||||
|
||||
To verify that all actions successfully performed, we use following *cgr-console* commands:
|
||||
|
||||
- Make sure all our balances were topped-up:
|
||||
|
||||
::
|
||||
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1001"]'
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1002"]'
|
||||
|
||||
- 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" AnswerTime="2014-08-04T13:00:00Z" Usage="20s"'
|
||||
cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" AnswerTime="2014-08-04T13:00:00Z" Usage="1m25s"'
|
||||
cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1003" AnswerTime="2014-08-04T13:00:00Z" Usage="20s"'
|
||||
|
||||
|
||||
Test calls
|
||||
----------
|
||||
|
||||
|
||||
1001 -> 1002
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Since the user 1001 is marked as *prepaid* inside the telecom switch, 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 in the tariff plan definition 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 stopped in the middle of debit interval).
|
||||
|
||||
Check that 1001 balance is properly deducted, 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 'accounts Tenant="cgrates.org" AccountIds=["1001"]'
|
||||
|
||||
|
||||
1002 -> 1001
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The user 1002 is marked as *postpaid* inside the telecom switch 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 'accounts Tenant="cgrates.org" AccountIds=["1002"]'
|
||||
|
||||
|
||||
1001 -> 1003
|
||||
~~~~~~~~~~~~
|
||||
The user 1001 call user 1003 and after 12 seconds the call will be disconnected.
|
||||
|
||||
CDR Exporting
|
||||
-------------
|
||||
|
||||
Once the CDRs are mediated, they are available to be exported. One can use available RPC APIs for that or directly call exports from console:
|
||||
|
||||
::
|
||||
|
||||
cgr-console 'cdrs_export CdrFormat="csv" ExportPath="/tmp"'
|
||||
|
||||
|
||||
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). Most important is the monitor for 100 units topped-up which will also trigger an account disable together with killing it's calls if prepaid debits are used.
|
||||
|
||||
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
|
||||
|
||||
cgr-console 'balance_set Tenant="cgrates.org" Account="1001" Direction="*out" Value=101'
|
||||
tail -f /var/log/syslog -n 20
|
||||
|
||||
On the CDRs side we will be able to integrate CdrStats monitors as part of our Fraud Detection system (eg: the increase of average cost for 1001 and 1002 accounts will signal us abnormalities, hence we will be notified via syslog).
|
||||
@@ -1,16 +0,0 @@
|
||||
FreeSWITCH Integration Tutorials
|
||||
================================
|
||||
|
||||
In these tutorials we exemplify a few cases of integration between FreeSWITCH_ and **CGRateS**. We start with common steps, installation and postinstall processes, then we dive into particular configurations.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tut_freeswitch_installs
|
||||
tut_jitsi_installs
|
||||
tut_freeswitch_json
|
||||
tut_cgrates_usage
|
||||
|
||||
.. _FreeSWITCH: https://freeswitch.com//
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
Software Installation
|
||||
=====================
|
||||
|
||||
We recommend using Debian 11 (Bullseye) as the operating system because all the software components we use provide packaging for it.
|
||||
|
||||
CGRateS
|
||||
-------
|
||||
|
||||
You can install **CGRateS** by following the instructions provided in the :ref:`installation<installation>` section.
|
||||
|
||||
FreeSWITCH
|
||||
----------
|
||||
|
||||
For detailed information on installing FreeSWITCH on Debian, please refer to its official `installation wiki <https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/Linux/Debian_67240088/>`_.
|
||||
|
||||
Before installing FreeSWITCH, you need to authenticate by creating a SignalWire Personal Access Token. To generate your personal token, follow the instructions in the `SignalWire official wiki on creating a personal token <https://developer.signalwire.com/freeswitch/freeswitch-explained/installation/howto-create-a-signalwire-personal-access-token_67240087/>`_.
|
||||
|
||||
To install FreeSWITCH and configure it, we have chosen the simplest method using *vanilla* packages.
|
||||
|
||||
Install FreeSWITCH by running the following commands:
|
||||
|
||||
::
|
||||
|
||||
TOKEN=YOURSIGNALWIRETOKEN # Insert your SignalWire Personal Access Token here
|
||||
apt-get update && apt-get install -y gnupg2 wget lsb-release
|
||||
wget --http-user=signalwire --http-password=$TOKEN -O /usr/share/keyrings/signalwire-freeswitch-repo.gpg https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg
|
||||
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" > /etc/apt/auth.conf
|
||||
chmod 600 /etc/apt/auth.conf
|
||||
echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" > /etc/apt/sources.list.d/freeswitch.list
|
||||
echo "deb-src [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" >> /etc/apt/sources.list.d/freeswitch.list
|
||||
|
||||
# If /etc/freeswitch does not exist, the standard vanilla configuration is deployed
|
||||
apt-get update && apt-get install -y freeswitch-meta-all
|
||||
|
||||
After the installation is complete, we will proceed to load the configuration based on the specific tutorial case provided in the subsequent section.
|
||||
|
||||
.. _FreeSWITCH: https://freeswitch.com//
|
||||
@@ -1,66 +0,0 @@
|
||||
FreeSWITCH_ generating *http-json* CDRs
|
||||
=======================================
|
||||
|
||||
Scenario
|
||||
--------
|
||||
|
||||
- FreeSWITCH with *vanilla* configuration adding *mod_json_cdr* for CDR generation.
|
||||
|
||||
- Modified following users (with configs in *etc/freeswitch/directory/default*): 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1006-prepaid, 1007-rated.
|
||||
- Have added inside default dialplan CGR own extensions just before routing towards users (*etc/freeswitch/dialplan/default.xml*).
|
||||
- FreeSWITCH configured to generate default *http-json* CDRs.
|
||||
|
||||
- **CGRateS** with following components:
|
||||
|
||||
- CGR-SM started as prepaid controller, with debits taking place at 5s intervals.
|
||||
- CGR-CDRS component receiving raw CDRs from FreeSWITCH, storing them and attaching costs inside CGR StorDB.
|
||||
- CGR-CDRE exporting processed CDRs from CGR StorDB (export path: */tmp*).
|
||||
- CGR-History component keeping the archive of the rates modifications (path browsable with git client at */tmp/cgr_history*).
|
||||
|
||||
|
||||
Starting FreeSWITCH_ with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/fs_evsock/freeswitch/etc/init.d/freeswitch start
|
||||
|
||||
To verify that FreeSWITCH_ is running we run the console command:
|
||||
|
||||
::
|
||||
|
||||
fs_cli -x status
|
||||
|
||||
|
||||
Starting **CGRateS** with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/fs_evsock/cgrates/etc/init.d/cgrates start
|
||||
|
||||
Check that cgrates is running
|
||||
|
||||
::
|
||||
|
||||
cgr-console status
|
||||
|
||||
|
||||
CDR processing
|
||||
--------------
|
||||
|
||||
At the end of each call FreeSWITCH_ will issue a http post with the CDR. This will reach inside **CGRateS** through the *CDRS* component (close to real-time). Once in-there it will be instantly rated and it is ready to be exported:
|
||||
|
||||
::
|
||||
|
||||
cgr-console 'cdrs_export CdrFormat="csv" ExportPath="/tmp"'
|
||||
|
||||
|
||||
**CGRateS** Usage
|
||||
-----------------
|
||||
|
||||
Since it is common to most of the tutorials, the example for **CGRateS** usage is provided in a separate page `here <http://cgrates.readthedocs.org/en/latest/tut_cgrates_usage.html>`_
|
||||
|
||||
|
||||
.. _FreeSWITCH: https://freeswitch.com//
|
||||
.. _Jitsi: https://jitsi.org/
|
||||
@@ -1,6 +0,0 @@
|
||||
SIP UA - Jitsi_
|
||||
---------------
|
||||
|
||||
On our ubuntu desktop host, we have installed Jitsi_ to be used as SIP UA, out of stable provided packages on `Jitsi download <https://jitsi.org/downloads/>`_ and had Jitsi_ configured with 4 accounts: 1001/CGRateS.org, 1002/CGRateS.org, 1003/CGRateS.org and 1004/CGRateS.org.
|
||||
|
||||
.. _Jitsi: https://jitsi.org/
|
||||
@@ -1,17 +0,0 @@
|
||||
Kamailio_ Integration Tutorials
|
||||
===============================
|
||||
|
||||
In these tutorials we exemplify a few cases of integration between Kamailio_ and CGRateS_. We start with common steps, installation and postinstall processes, then we dive into particular configurations, depending on the case we run.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tut_kamailio_installs
|
||||
tut_jitsi_installs
|
||||
tut_kamailio_evapi
|
||||
tut_cgrates_usage
|
||||
|
||||
.. _Kamailio: https://www.kamailio.org/w/
|
||||
.. _CGRateS: http://www.cgrates.org/
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
Kamailio_ interaction via *evapi* module
|
||||
=========================================
|
||||
|
||||
Scenario
|
||||
--------
|
||||
|
||||
- Kamailio default configuration modified for **CGRateS** interaction. For script maintainability and simplicity we have separated CGRateS specific routes in *kamailio-cgrates.cfg* file which is included in main *kamailio.cfg* via include directive.
|
||||
|
||||
- Considering the following users (with configs hardcoded in the *kamailio.cfg* configuration script and loaded in htable): 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1005-rated, 1006-prepaid, 1007-prepaid.
|
||||
|
||||
- **CGRateS** with following components:
|
||||
|
||||
- CGR-SM started as translator between Kamailio_ and CGR-Rater for both authorization events as well as accounting ones.
|
||||
- CGR-CDRS component processing raw CDRs from CGR-SM component and storing them inside CGR StorDB.
|
||||
- CGR-CDRE exporting rated CDRs from CGR StorDB (export path: */tmp*).
|
||||
- CGR-History component keeping the archive of the rates modifications (path browsable with git client at */tmp/cgr_history*).
|
||||
|
||||
|
||||
Starting Kamailio_ with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/kamevapi/kamailio/etc/init.d/kamailio start
|
||||
|
||||
To verify that Kamailio_ is running we run the console command:
|
||||
|
||||
::
|
||||
|
||||
kamctl moni
|
||||
|
||||
|
||||
Starting **CGRateS** with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/kamevapi/cgrates/etc/init.d/cgrates start
|
||||
|
||||
Make sure that cgrates is running
|
||||
|
||||
::
|
||||
|
||||
cgr-console status
|
||||
|
||||
|
||||
CDR processing
|
||||
--------------
|
||||
|
||||
At the end of each call Kamailio_ will generate an CDR event via *evapi* and this will be directed towards the port configured inside *cgrates.json*. This event will reach inside **CGRateS** through the *SM* component (close to real-time). Once in-there it will be instantly rated and be ready for export.
|
||||
|
||||
|
||||
**CGRateS** Usage
|
||||
-----------------
|
||||
|
||||
Since it is common to most of the tutorials, the example for **CGRateS** usage is provided in a separate page `here <http://cgrates.readthedocs.org/en/latest/tut_cgrates_usage.html>`_
|
||||
|
||||
|
||||
.. _Kamailio: https://www.kamailio.org/w/
|
||||
@@ -1,25 +0,0 @@
|
||||
Software installation
|
||||
=====================
|
||||
|
||||
We have chosen Debian 11 (Bullseye) as the operating system, since all the software components we use provide packaging for it.
|
||||
|
||||
CGRateS
|
||||
-------
|
||||
|
||||
CGRateS can be installed by following the instructions in this :ref:`installation guide<installation>`.
|
||||
|
||||
Kamailio
|
||||
--------
|
||||
|
||||
Kamailio can be installed using the commands below, as documented in the `Kamailio Debian Installation Guide <https://kamailio.org/docs/tutorials/devel/kamailio-install-guide-deb/>`_.
|
||||
|
||||
::
|
||||
|
||||
wget -O- http://deb.kamailio.org/kamailiodebkey.gpg | sudo apt-key add -
|
||||
echo "deb http://deb.kamailio.org/kamailio56 bullseye main" > /etc/apt/sources.list.d/kamailio.list
|
||||
apt-get update
|
||||
apt-get install kamailio kamailio-extra-modules kamailio-json-modules
|
||||
|
||||
After the installation is complete, we will proceed to load the configuration based on the specific tutorial case provided in the subsequent section.
|
||||
|
||||
.. _Kamailio: https://www.kamailio.org/w/
|
||||
@@ -1,17 +0,0 @@
|
||||
OpenSIPS_ Integration Tutorials
|
||||
===============================
|
||||
|
||||
In these tutorials we exemplify a few cases of integration between OpenSIPS_ and CGRateS_. We start with common steps, installation and postinstall processes, then we dive into particular configurations, depending on the case we run.
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tut_opensips_installs
|
||||
tut_jitsi_installs
|
||||
tut_opensips_event
|
||||
tut_cgrates_usage
|
||||
|
||||
.. _OpenSIPS: https://www.opensips.org/
|
||||
.. _CGRateS: http://www.cgrates.org/
|
||||
|
||||
@@ -1,60 +0,0 @@
|
||||
OpenSIPS_ interaction via *event_datagram*
|
||||
===========================================
|
||||
|
||||
Scenario
|
||||
--------
|
||||
|
||||
- OpenSIPS out of *residential* configuration generated.
|
||||
|
||||
- Considering the following users (with configs hardcoded in the *opensips.cfg* configuration script): 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1007-rated.
|
||||
- For simplicity we configure no authentication (WARNING: Not for production usage).
|
||||
|
||||
- **CGRateS** with following components:
|
||||
|
||||
- CGR-SM started as translator between OpenSIPS_ and **cgr-rater** for both authorization events (pseudoprepaid) as well as CDR ones.
|
||||
- CGR-CDRS component processing raw CDRs from CGR-SM component and storing them inside CGR StorDB.
|
||||
- CGR-CDRE exporting rated CDRs from CGR StorDB (export path: */tmp*).
|
||||
- CGR-History component keeping the archive of the rates modifications (path browsable with git client at */tmp/cgr_history*).
|
||||
|
||||
|
||||
Starting OpenSIPS_ with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/osips_native/opensips/etc/init.d/opensips start
|
||||
|
||||
To verify that OpenSIPS_ is running we run the console command:
|
||||
|
||||
::
|
||||
|
||||
opensipsctl moni
|
||||
|
||||
|
||||
Starting **CGRateS** with custom configuration
|
||||
----------------------------------------------
|
||||
|
||||
::
|
||||
|
||||
/usr/share/cgrates/tutorials/osips_native/cgrates/etc/init.d/cgrates start
|
||||
|
||||
Make sure that cgrates is running
|
||||
|
||||
::
|
||||
|
||||
cgr-console status
|
||||
|
||||
|
||||
CDR processing
|
||||
--------------
|
||||
|
||||
At the end of each call OpenSIPS_ will generate an CDR event and due to automatic handler registration built in **CGRateS-SM** component, this will be directed towards the port configured inside *cgrates.json*. This event will reach inside **CGRateS** through the *SM* component (close to real-time). Once in-there it will be instantly rated and be ready for export.
|
||||
|
||||
|
||||
**CGRateS** Usage
|
||||
-----------------
|
||||
|
||||
Since it is common to most of the tutorials, the example for **CGRateS** usage is provided in a separate page `here <http://cgrates.readthedocs.org/en/latest/tut_cgrates_usage.html>`_
|
||||
|
||||
|
||||
.. _OpenSIPS: https://www.opensips.org/
|
||||
@@ -1,25 +0,0 @@
|
||||
Software installation
|
||||
=====================
|
||||
|
||||
We have chosen Debian Jessie as operating system, since all the software components we use provide packaging for it.
|
||||
|
||||
CGRateS
|
||||
--------
|
||||
|
||||
**CGRateS** can be installed using the instructions found :ref:`here<installation>`.
|
||||
|
||||
|
||||
OpenSIPS_
|
||||
---------
|
||||
|
||||
We got OpenSIPS_ installed via following commands:
|
||||
::
|
||||
|
||||
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 049AD65B
|
||||
echo "deb http://apt.opensips.org jessie 2.4-nightly" >/etc/apt/sources.list.d/opensips.list
|
||||
apt-get update
|
||||
apt-get install opensips opensips-cgrates-module
|
||||
|
||||
After the installation is complete, we will proceed to load the configuration based on the specific tutorial case provided in the subsequent section.
|
||||
|
||||
.. _OpenSIPS: https://www.opensips.org/
|
||||
411
docs/tutorial.rst
Normal file
411
docs/tutorial.rst
Normal file
@@ -0,0 +1,411 @@
|
||||
Tutorial
|
||||
========
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
:depth: 3
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This tutorial provides detailed instructions for setting up a SIP Server and managing communication between the server and the CGRateS instance.
|
||||
|
||||
.. note::
|
||||
|
||||
The development and testing of the instructions in this tutorial has been done on a Debian 11 (Bullseye) virtual machine.
|
||||
|
||||
|
||||
Scenario Overview
|
||||
-----------------
|
||||
|
||||
The tutorial comprises the following steps:
|
||||
|
||||
1. **SIP Server Setup**:
|
||||
Select and install a SIP Server. The tutorial supports the following options:
|
||||
|
||||
- FreeSWITCH_
|
||||
- Asterisk_
|
||||
- Kamailio_
|
||||
- OpenSIPS_
|
||||
|
||||
2. **CGRateS Initialization**:
|
||||
Launch a CGRateS instance with the corresponding agent configured. In this context, an "agent" refers to a component within CGRateS that manages communication between CGRateS and the SIP Servers.
|
||||
|
||||
3. **Account Configuration**:
|
||||
Establish user accounts for different request types.
|
||||
|
||||
4. **Balance Addition**:
|
||||
Allocate suitable balances to the user accounts.
|
||||
|
||||
5. **Call Simulation**:
|
||||
Use Zoiper_ (or any other SIP UA of your choice) to register the user accounts and simulate calls between the configured accounts, and then verify the balance updates post-calls.
|
||||
|
||||
6. **Fraud Detection Setup**:
|
||||
Implement a fraud detection mechanism to secure and maintain the integrity of the service.
|
||||
|
||||
As we progress through the tutorial, each step will be elaborated in detail. Let's embark on this journey with the SIP Server Setup.
|
||||
|
||||
|
||||
|
||||
Software Installation
|
||||
---------------------
|
||||
|
||||
*CGRateS* already has a section within this documentation regarding installation. It can be found :ref:`here<installation>`.
|
||||
|
||||
Regarding the SIP Servers, click on the tab corresponding to the choice you made and follow the steps in order to set up:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: FreeSWITCH
|
||||
|
||||
For detailed information on installing FreeSWITCH_ on Debian, please refer to its official `installation wiki <https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/Linux/Debian_67240088/>`_.
|
||||
|
||||
Before installing FreeSWITCH_, you need to authenticate by creating a SignalWire Personal Access Token. To generate your personal token, follow the instructions in the `SignalWire official wiki on creating a personal token <https://developer.signalwire.com/freeswitch/freeswitch-explained/installation/howto-create-a-signalwire-personal-access-token_67240087/>`_.
|
||||
|
||||
To install FreeSWITCH_ and configure it, we have chosen the simplest method using *vanilla* packages.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
TOKEN=YOURSIGNALWIRETOKEN # Insert your SignalWire Personal Access Token here
|
||||
apt-get update && apt-get install -y gnupg2 wget lsb-release
|
||||
wget --http-user=signalwire --http-password=$TOKEN -O /usr/share/keyrings/signalwire-freeswitch-repo.gpg https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg
|
||||
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" > /etc/apt/auth.conf
|
||||
chmod 600 /etc/apt/auth.conf
|
||||
echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" > /etc/apt/sources.list.d/freeswitch.list
|
||||
echo "deb-src [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] https://freeswitch.signalwire.com/repo/deb/debian-release/ `lsb_release -sc` main" >> /etc/apt/sources.list.d/freeswitch.list
|
||||
|
||||
# If /etc/freeswitch does not exist, the standard vanilla configuration is deployed
|
||||
apt-get update && apt-get install -y freeswitch-meta-all
|
||||
|
||||
.. group-tab:: Asterisk
|
||||
|
||||
To install Asterisk_, follow these steps:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Install the necessary dependencies
|
||||
sudo apt-get install -y build-essential libasound2-dev autoconf \
|
||||
openssl libssl-dev libxml2-dev \
|
||||
libncurses5-dev uuid-dev sqlite3 \
|
||||
libsqlite3-dev pkg-config libedit-dev \
|
||||
libjansson-dev
|
||||
|
||||
# Download Asterisk
|
||||
wget https://downloads.asterisk.org/pub/telephony/asterisk/asterisk-20-current.tar.gz -P /tmp
|
||||
|
||||
# Extract the downloaded archive
|
||||
sudo tar -xzvf /tmp/asterisk-20-current.tar.gz -C /usr/src
|
||||
|
||||
# Change the working directory to the extracted Asterisk source
|
||||
cd /usr/src/asterisk-20*/
|
||||
|
||||
# Compile and install Asterisk
|
||||
sudo ./configure --with-jansson-bundled
|
||||
sudo make menuselect.makeopts
|
||||
sudo make
|
||||
sudo make install
|
||||
sudo make samples
|
||||
sudo make config
|
||||
sudo ldconfig
|
||||
|
||||
# Create the Asterisk system user
|
||||
sudo adduser --quiet --system --group --disabled-password --shell /bin/false --gecos "Asterisk" asterisk
|
||||
|
||||
.. group-tab:: Kamailio
|
||||
|
||||
Kamailio_ can be installed using the commands below, as documented in the `Kamailio Debian Installation Guide <https://kamailio.org/docs/tutorials/devel/kamailio-install-guide-deb/>`_.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wget -O- http://deb.kamailio.org/kamailiodebkey.gpg | sudo apt-key add -
|
||||
echo "deb http://deb.kamailio.org/kamailio56 bullseye main" > /etc/apt/sources.list.d/kamailio.list
|
||||
apt-get update
|
||||
apt-get install kamailio kamailio-extra-modules kamailio-json-modules
|
||||
|
||||
.. group-tab:: OpenSIPS
|
||||
|
||||
We got OpenSIPS_ installed via following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 049AD65B
|
||||
echo "deb https://apt.opensips.org buster 3.3-releases" >/etc/apt/sources.list.d/opensips.list
|
||||
echo "deb https://apt.opensips.org buster cli-nightly" >/etc/apt/sources.list.d/opensips-cli.list
|
||||
apt-get update
|
||||
sudo apt-get install opensips opensips-mysql-module opensips-cgrates-module opensips-cli
|
||||
|
||||
Configuration and initialization
|
||||
--------------------------------
|
||||
|
||||
This section will be dedicated to configuring both the chosen SIP Server, as well as CGRateS and then get them running.
|
||||
|
||||
Regarding the SIP Servers, we have prepared custom configurations in advance, as well as an init scripts that can be used to start the services using said configurations. It can also be used to stop/restart/check on the status of the services. Another way to do that would be to copy the configuration in the default folder, where the Server will be searching for the configuration before starting, with it usually being /etc/<software name>.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: FreeSWITCH
|
||||
|
||||
|
||||
The FreeSWITCH_ setup consists of:
|
||||
|
||||
- *vanilla* configuration + "mod_json_cdr" for CDR generation;
|
||||
- configurations for the following users (found in *etc/freeswitch/directory/default*): 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1006-prepaid, 1007-rated;
|
||||
- addition of CGRateS' own extensions befoure routing towards users in the dialplan (found in *etc/freeswitch/dialplan/default.xml*).
|
||||
|
||||
|
||||
To start FreeSWITCH_ with the prepared custom configuration, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/fs_evsock/freeswitch/etc/init.d/freeswitch start
|
||||
|
||||
To verify that FreeSWITCH_ is running, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
fs_cli -x status
|
||||
|
||||
|
||||
.. group-tab:: Asterisk
|
||||
|
||||
|
||||
The Asterisk_ setup consists of:
|
||||
|
||||
- *basic-pbx* configuration sample;
|
||||
- configurations for the following users: 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, 1004-rated, 1007-rated.
|
||||
|
||||
|
||||
To start Asterisk_ with the prepared custom configuration, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/asterisk_ari/asterisk/etc/init.d/asterisk start
|
||||
|
||||
|
||||
To verify that Asterisk_ is running, run the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
asterisk -r -s /tmp/cgr_asterisk_ari/asterisk/run/asterisk.ctl
|
||||
ari show status
|
||||
|
||||
.. group-tab:: Kamailio
|
||||
|
||||
The Kamailio_ setup consists of:
|
||||
|
||||
- default configuration with small modifications to add **CGRateS** interaction;
|
||||
- for script maintainability and simplicity, we have separated **CGRateS** specific routes in *kamailio-cgrates.cfg* file which is included in main *kamailio.cfg* via include directive;
|
||||
- configurations for the following users: 1001-prepaid, 1002-postpaid, 1003-pseudoprepaid, stored using the CGRateS AttributeS subsystem.
|
||||
|
||||
|
||||
To start Kamailio_ with the prepared custom configuration, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/kamevapi/kamailio/etc/init.d/kamailio start
|
||||
|
||||
To verify that Kamailio_ is running, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
kamctl moni
|
||||
|
||||
.. group-tab:: OpenSIPS
|
||||
|
||||
The OpenSIPS_ setup consists of:
|
||||
- *residential* configuration;
|
||||
- user accounts configuration not needed since it's enough for them to only be defined within CGRateS;
|
||||
- for simplicity, no authentication was configured (WARNING: Not suitable for production).
|
||||
- creating database for the DRouting module, using the following command:
|
||||
.. code-block:: bash
|
||||
|
||||
opensips-cli -x database create
|
||||
|
||||
|
||||
To start OpenSIPS_ with the prepared custom configuration, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/osips_native/opensips/etc/init.d/opensips start
|
||||
|
||||
To verify that OpenSIPS_ is running, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
opensipsctl moni
|
||||
|
||||
|
||||
|
||||
**CGRateS** will be configured with the following subsystems enabled:
|
||||
|
||||
- **SessionS**: started as gateway between the SIP Server and rest of CGRateS subsystems;
|
||||
- **ChargerS**: used to decide the number of billing runs for customer/supplier charging;
|
||||
- **AttributeS**: used to populate extra data to requests (ie: prepaid/postpaid, passwords, paypal account, LCR profile);
|
||||
- **RALs**: used to calculate costs as well as account bundle management;
|
||||
- **SupplierS**: selection of suppliers for each session (in case of OpenSIPS_, it will work in tandem with their DRouting module);
|
||||
- **StatS**: computing statistics in real-time regarding sessions and their charging;
|
||||
- **ThresholdS**: monitoring and reacting to events coming from above subsystems;
|
||||
- **CDRe**: exporting rated CDRs from CGR StorDB (export path: */tmp*).
|
||||
|
||||
Just as with the SIP Servers, we have also prepared configurations and init scripts for CGRateS. And just as well, you can manage the CGRateS service using systemctl if you prefer. You can even start it using the cgr-engine binary, like so:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-engine -config_path=<path_to_config> -logger=*stdout
|
||||
|
||||
.. note::
|
||||
The logger flag from the command above is optional, it's usually more convenient for us to check for logs in the terminal that cgrates was started in rather than checking the syslog.
|
||||
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: FreeSWITCH
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/fs_evsock/cgrates/etc/init.d/cgrates start
|
||||
|
||||
.. group-tab:: Asterisk
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/asterisk_ari/cgrates/etc/init.d/cgrates start
|
||||
|
||||
.. group-tab:: Kamailio
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/kamevapi/cgrates/etc/init.d/cgrates start
|
||||
|
||||
.. group-tab:: OpenSIPS
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
/usr/share/cgrates/tutorials/osips_native/cgrates/etc/init.d/cgrates start
|
||||
|
||||
.. note::
|
||||
If you have chosen OpenSIPS_, CGRateS has to be started first since the dependency is reversed.
|
||||
|
||||
|
||||
Loading **CGRateS** Tariff Plans
|
||||
--------------------------------
|
||||
|
||||
Now that we have **CGRateS** installed and started with one of the custom configurations, we can load the prepared data out of the shared folder, containing the 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.
|
||||
- Rate id: *RT_1CNT* having no connect fee and a rate of 1 cent per minute, chargeable in 1 minute increments.
|
||||
- Rate id: *RT_1CNT_PER_SEC* having no connect fee and a rate of 1 cent per second, chargeable in 1 second increments.
|
||||
|
||||
- Accounting part will have following configured:
|
||||
|
||||
- Create 3 accounts: 1001, 1002, 1003.
|
||||
- 1001, 1002 will receive 10units of **\*monetary** balance.
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-loader -verbose -path=/usr/share/cgrates/tariffplans/tutorial
|
||||
|
||||
To verify that all actions successfully performed, we use following *cgr-console* commands:
|
||||
|
||||
- Make sure all our balances were topped-up:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1001"]'
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1002"]'
|
||||
|
||||
- Query call costs so we can see our calls will have expected costs (final cost will result as sum of *ConnectFee* and *Cost* fields):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" AnswerTime="2014-08-04T13:00:00Z" Usage="20s"'
|
||||
cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1002" AnswerTime="2014-08-04T13:00:00Z" Usage="1m25s"'
|
||||
cgr-console 'cost Category="call" Tenant="cgrates.org" Subject="1001" Destination="1003" AnswerTime="2014-08-04T13:00:00Z" Usage="20s"'
|
||||
|
||||
|
||||
Test calls
|
||||
----------
|
||||
|
||||
|
||||
1001 -> 1002
|
||||
~~~~~~~~~~~~
|
||||
|
||||
Since the user 1001 is marked as *prepaid* inside the telecom switch, 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 in the tariff plan definition 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 deducted, 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.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1001"]'
|
||||
|
||||
|
||||
1002 -> 1001
|
||||
~~~~~~~~~~~~
|
||||
|
||||
The user 1002 is marked as *postpaid* inside the telecom switch 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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'accounts Tenant="cgrates.org" AccountIds=["1002"]'
|
||||
|
||||
|
||||
1001 -> 1003
|
||||
~~~~~~~~~~~~
|
||||
The user 1001 call user 1003 and after 12 seconds the call will be disconnected.
|
||||
|
||||
CDR Processing
|
||||
--------------
|
||||
|
||||
- The SIP Server generates a CDR event at the end of each call (i.e., FreeSWITCH_ via HTTP Post and Kamailio_ via evapi)
|
||||
- The event is directed towards the port configured inside cgrates.json due to the automatic handler registration built into the SessionS subsystem.
|
||||
- The event reaches CGRateS through the SessionS subsystem in close to real-time.
|
||||
- Once inside CGRateS, the event is instantly rated and ready for export.
|
||||
|
||||
|
||||
CDR Exporting
|
||||
-------------
|
||||
|
||||
Once the CDRs are mediated, they are available to be exported. One can use available RPC APIs for that or directly call exports from console:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'cdrs_export ExportArgs={"ExportFormat":"*file_csv", "ExportPath":"/tmp"}'
|
||||
|
||||
|
||||
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, e.g.: fraud with more than 20 units topped-up). Most important is the monitor for 100 units topped-up which will also trigger an account disable together with killing it's calls if prepaid debits are used.
|
||||
|
||||
To verify this mechanism simply add some random units into one account's balance:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cgr-console 'balance_set Tenant="cgrates.org" Account="1003" Value=23 BalanceType="*monetary" Balance={"ID":"MonetaryBalance"}'
|
||||
tail -f /var/log/syslog -n 20
|
||||
|
||||
cgr-console 'balance_set Tenant="cgrates.org" Account="1001" Value=101 BalanceType="*monetary" Balance={"ID":"MonetaryBalance"}'
|
||||
tail -f /var/log/syslog -n 20
|
||||
|
||||
On the CDRs side we will be able to integrate CdrStats monitors as part of our Fraud Detection system (eg: the increase of average cost for 1001 and 1002 accounts will signal us abnormalities, hence we will be notified via syslog).
|
||||
|
||||
|
||||
.. _Zoiper: https://www.zoiper.com/
|
||||
.. _Asterisk: http://www.asterisk.org/
|
||||
.. _FreeSWITCH: https://freeswitch.com/
|
||||
.. _Kamailio: https://www.kamailio.org/w/
|
||||
.. _OpenSIPS: https://opensips.org/
|
||||
.. _CGRateS: http://www.cgrates.org/
|
||||
@@ -1,10 +0,0 @@
|
||||
Tutorials
|
||||
=========
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
tut_asterisk
|
||||
tut_freeswitch
|
||||
tut_kamailio
|
||||
tut_opensips
|
||||
Reference in New Issue
Block a user