uppal/cgrates
1
0
Fork 1
mirror of https://github.com/cgrates/cgrates.git synced 2026-02-11 18:16:24 +05:00
Code Issues Packages Projects Releases Wiki Activity

update installation docs + cleanup

Browse Source
This commit is contained in:
ionutboangiu
2025-05-08 21:41:09 +03:00
committed by Dan Christian Bogos
parent 6a2654e6d8
commit 2e883b2489
38 changed files with 80 additions and 1870 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/admins.rst Normal file
View File

@@ -0,0 +1,5 @@
AdminS
======
TBD

10
docs/advanced.rst
View File

@@ -1,10 +0,0 @@
Advanced Topics
===============
.. toctree::
:maxdepth: 2
apicalls
ratinglogic

7
docs/apicalls.rst
View File

@@ -1,7 +0,0 @@
API Calls
=========
API calls are documented in the following GoDoc_
.. _GoDoc : https://pkg.go.dev/github.com/cgrates/cgrates/apier@master

5
docs/apiers.rst
View File

@@ -1,5 +0,0 @@
APIerS
======
TBD

251
docs/cdre.rst
View File

@@ -1,251 +0,0 @@
.. _AMQP: https://www.amqp.org/
.. _SQS: https://aws.amazon.com/de/sqs/
.. _S3: https://aws.amazon.com/de/s3/
.. _Kafka: https://kafka.apache.org/
.. _CDRe:
CDRe
====
**CDRe** is an extension of :ref:`CDRs`, responsible for exporting the *CDR* events processed by :ref:`CDRs`. It is accessed via `CGRateS RPC APIs <https://godoc.org/github.com/cgrates/cgrates/apier/>`_ and configured within *cdre* section inside :ref:`JSON configuration <configuration>`.
Export types
------------
There are two types of exports with common configuration but different data sources:
Online exports
^^^^^^^^^^^^^^
Are real-time exports, triggered by the CDR event processed by :ref:`CDRs`, and take these events as data source.
The *online exports* are enabled via *online_cdr_exports* :ref:`JSON configuration <configuration>` option within *cdrs*.
You can control the templates which are to be executed via the filters which are applied for each export template individually.
Offline exports
^^^^^^^^^^^^^^^
Are exports which are triggered via `CGRateS RPC APIs <https://godoc.org/github.com/cgrates/cgrates/apier/>`_ and they have as data source the CDRs stored within *StorDB*.
Parameters
----------
CDRe
^^^^
**CDRe** it is configured within **cdre** section from :ref:`JSON configuration <configuration>`.
One **export profile** includes the following parameters:
export_format
Specify the type of export which will run. Possible values are:
**\*fileCSV**
Exports into a comma separated file format.
**\*fileFWV**
Exports into a fixed width file format.
**\*httpPost**
Will post the CDR to a HTTP server. The export content will be a HTTP form encoded representation of the `internal CDR object <https://godoc.org/github.com/cgrates/cgrates/engine#CDR>`_.
**\*http_json_cdr**
Will post the CDR to a HTTP server. The export content will be a JSON serialized representation of the `internal CDR object <https://godoc.org/github.com/cgrates/cgrates/engine#CDR>`_.
**\*httpJSONMap**
Will post the CDR to a HTTP server. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template.
**\*amqp_json_cdr**
Will post the CDR to an AMQP_ queue. The export content will be a JSON serialized representation of the `internal CDR object <https://godoc.org/github.com/cgrates/cgrates/engine#CDR>`_. Uses AMQP_ protocol version 0.9.1.
**\*amqpJSONMap**
Will post the CDR to an AMQP_ queue. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template. Uses AMQP_ protocol version 1.0.
**\*amqpv1JSONMap**
Will post the CDR to an AMQP_ queue. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template. Uses AMQP_ protocol version 1.0.
**\*sqsJSONMap**
Will post the CDR to an `Amazon SQS queue <SQS>`_. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template.
**\*s3JSONMap**
Will post the CDR to `Amazon S3 storage <S3>`_. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template.
**\*kafkaJSONMap**
Will post the CDR to an `Apache Kafka <Kafka>`_. The export content will be a JSON serialized hmap with fields defined within the *fields* section of the template.
export_path
Specify the export path. It has special format depending of the export type.
**\*fileCSV**, **\*fileFWV**
Standard unix-like filesystem path.
**\*httpPost**, **\*http_json_cdr**, **\*httpJSONMap**
Full HTTP URL
**\*amqpJSONMap**, **\*amqpv1JSONMap**
AMQP URL with extra parameters.
Sample: *amqp://guest:guest@localhost:5672/?queue_id=cgrates_cdrs&exchange=exchangename&exchange_type=fanout&routing_key=cgr_cdrs*
**\*sqsJSONMap**
SQS URL with extra parameters.
Sample: *http://sqs.eu-west-2.amazonaws.com/?aws_region=eu-west-2&aws_key=testkey&aws_secret=testsecret&queue_id=cgrates-cdrs*
**\*s3JSONMap**
S3 URL with extra parameters.
Sample: *http://s3.us-east-2.amazonaws.com/?aws_region=eu-west-2&aws_key=testkey&aws_secret=testsecret&queue_id=cgrates-cdrs*
**\*kafkaJSONMap**
Kafka URL with extra parameters.
Sample: *localhost:9092?topic=cgrates_cdrs*
filters
List of filters to pass for the export profile to execute. For the dynamic content (prefixed with *~*) following special variables are available:
**\*req**
The *CDR* event itself.
**\*ec**
The *EventCost* object with subpaths for all of it's nested objects.
tenant
Tenant owning the template. It will be used mostly to match inside :ref:`FilterS`.
synchronous
Block further exports until this one finishes. In case of *false* the control will be given to the next export template as soon as this one was started.
attempts
Number of attempts before giving up on the export and writing the failed request to file. The failed request will be written to *failed_posts_dir* defined in *general* section.
field_separator
Field separator to be used in some export types (ie. *\*fileCSV*).
attributes_context
The context used when sending the CDR event to :ref:`AttributeS` for modifications. If empty, there will be no event sent to :ref:`AttributeS`.
fields
List of fields for the exported event. Not affecting templates like *\*http_json_cdr* or *\*amqp_json_cdr* with fixed content.
One **field template** will contain the following parameters:
path
Path for the exported content. Possible prefixes here are:
*\*exp*
Reference to the exported record.
*\*hdr*
Reference to the header content. Available in case of **\*fileCSV** and **\*fileFWV** export types.
*\*trl*
Reference to the trailer content. Available in case of **\*fileCSV** and **\*fileFWV** export types.
type
The field type will give out the logic for generating the value. Values used depend on the type of prefix used in path.
For *\*exp*, following field types are implemented:
**\*variable**
Writes out the variable value, overwriting previous one set.
**\*composed**
Writes out the variable value, postpending to previous value set
**\*filler**
Fills the values with a fixed lentgh string.
**\*constant**
Writes out a constant
**\*datetime**
Parses the value as datetime and reformats based on the *layout* attribute.
**\*combimed**
Writes out a combined mediation considering events with the same *CGRID*.
**\*masked_destination**
Masks the destination using *\** as suffix. Matches the destination field against the list defined via *mask_destinationd_id* field.
**\*httpPost**
Uses a HTTP server as datasource for the value exported.
For *\*hdr* and *\*trl*, following field types are possible:
**\*filler**
Fills the values with a string.
**\*constant**
Writes out a constant
**\*handler**
Will obtain the content via a handler. This works in tandem with the attribute *handler_id*.
value
The exported value. Works in tandem with *type* attribute. Possible prefixes for dynamic values:
**\*req**
Data is taken from the current request coming from the *CDRs* component.
mandatory
Makes sure that the field cannot have empty value (errors otherwise).
tag
Used for debug purposes in logs.
width
Used to control the formatting, enforcing the final value to a specific number of characters.
strip
Used when the value is higher than *width* allows it, specifying the strip strategy. Possible values are:
**\*right**
Strip the suffix.
**\*xright**
Strip the suffix, postpending one *x* character to mark the stripping.
**\*left**
Strip the prefix.
**\*xleft**
Strip the prefix, prepending one *x* character to mark the stripping.
padding
Used to control the formatting. Applied when the data is smaller than the *width*. Possible values are:
**\*right**
Suffix with spaces.
**\*left**
Prefix with spaces.
**\*zeroleft**
Prefix with *0* chars.
mask_destinationd_id
The destinations profile where we match the *masked_destinations*.
hander_id
The identifier of the handler to be executed in case of *\*handler* *type*.

22
docs/cgr-engine.rst
View File

@@ -12,8 +12,10 @@ Able to read the configuration from either a local directory of *.json* files w
::
$ cgr-engine -help
Usage of cgr-engine:
$ cgr-engine -help
Usage of cgr-engine:
-check_config
Verify the config without starting the engine
-config_path string
Configuration directory path (default "/etc/cgrates/")
-cpuprof_dir string
@@ -21,7 +23,7 @@ Able to read the configuration from either a local directory of *.json* files w
-log_level int
Log level (0=emergency to 7=debug) (default -1)
-logger string
Logger type <*syslog|*stdout>
Logger type <*syslog|*stdout|*kafkaLog>
-memprof_dir string
Directory for memory profiles
-memprof_interval duration
@@ -34,15 +36,13 @@ Able to read the configuration from either a local directory of *.json* files w
Node ID of the engine
-pid string
Path to write the PID file
-preload string
-preload value
Loader IDs used to load data before engine starts
-print_config
Print configuration object in JSON format
-scheduled_shutdown duration
Shutdown the engine after the specified duration
-set_versions
Overwrite database versions (equivalent to cgr-migrator -exec=*set_versions)
-singlecpu
Overwrite database versions
-single_cpu
Run on a single CPU core
-version
Print application version and exit
@@ -66,7 +66,7 @@ The components from the diagram can be found documented in the links bellow:
agents
sessions
rals
rates
cdrs
ees
attributes
@@ -77,9 +77,7 @@ The components from the diagram can be found documented in the links bellow:
trends
thresholds
filters
dispatchers
schedulers
apiers
admins
loaders
caches
guardian

6
docs/conf.py
View File

@@ -46,16 +46,16 @@ master_doc = 'index'
# General information about the project.
project = u'CGRateS'
copyright = u'2012-2023, ITsysCOM GmbH'
copyright = u'2012-2025, ITsysCOM GmbH'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.11'
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '0.11.0~dev'
release = '1.0~dev'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.

207
docs/dispatchers.rst
View File

@@ -1,207 +0,0 @@
.. _dispatchers:
DispatcherS
===========
**DispatcherS** is the **CGRateS** component that handles request routing and load balancing. When enabled, it manages all requests to other CGRateS subsystems by wrapping their methods with additional features like :ref:`authorization <dispatcher-authorization>`, request routing, load balancing, broadcasting, and loop prevention.
Processing Logic
----------------
.. _dispatcher-authorization:
Authorization
~~~~~~~~~~~~~
Optional step when :ref:`AttributeS <attributes>` connections are configured:
- Looks for ``*apiKey`` in APIOpts (returns mandatory missing error if not present)
- Sends key to AttributeS, which adds it as "APIKey" to the Event
- AttributeS processes the event and adds allowed methods to APIMethods (e.g., "method1&method2&method3")
- Checks if the requested method is in the allowed list
- Continues only after successful authorization
Dispatch
~~~~~~~~
The dispatcher processes requests through these steps:
* Check for bypass conditions:
* Presence of ``*dispatchers: false`` in APIOpts
* Request source is another dispatcher and ``prevent_loops`` is enabled
* Check cached routes:
* Search for ``*routeID`` in APIOpts
* If found, use cached dispatch data (tenant, profile ID, host ID)
* Fall back to full dispatch on network errors or timeouts
* Run full dispatch sequence:
* Get matching dispatcher profiles
* Try each profile until dispatch succeeds
.. _dispatcher-types:
Dispatcher Types and Strategies
-------------------------------
Load Dispatchers
~~~~~~~~~~~~~~~~
Used for ratio-based request distribution. Hosts are sorted in three steps:
1. Initial sorting by weight
2. Secondary sorting by load ratio (current active requests/configured ratio), where lower ratios have priority
3. Final sorting based on the specified strategy:
* ``*random``: Randomizes host selection
* ``*round_robin``: Sequential host selection with weight consideration
* ``*weight``: Skips final sorting, maintains weight and load-based ordering
Configuration through:
- ``*defaultRatio`` in StrategyParams
- Direct ratio specification in Host configuration
Simple Dispatchers
~~~~~~~~~~~~~~~~~~
Standard request distribution where hosts are sorted first by weight, followed by the chosen strategy (*random, *round_robin, *weight).
Broadcast Dispatchers
~~~~~~~~~~~~~~~~~~~~~
Handles scenarios requiring multi-host distribution. Supports three broadcast strategies:
* ``*broadcast``: Sends to all hosts, uses first response
* ``*broadcast_sync``: Sends to all hosts, waits for all responses
* ``*broadcast_async``: Sends to all hosts without waiting (fire-and-forget)
Parameters
----------
Configure the dispatcher in the **dispatchers** section of the :ref:`JSON configuration <configuration>`:
enabled
Enables/disables the DispatcherS component. Values: <true|false>
indexed_selects
Enables profile matching exclusively on indexes for improved performance
string_indexed_fields
Fields used for string-based index querying
prefix_indexed_fields
Fields used for prefix-based index querying
suffix_indexed_fields
Fields used for suffix-based index querying
nested_fields
Controls indexed filter matching depth. Values: <true|false>
- true: checks all levels
- false: checks only first level
attributes_conns
Connections to :ref:`AttributeS <attributes>` for API authorization
- Empty: disables authorization
- "*internal": uses internal connection
- Custom connection ID
any_subsystem
Enables matching of *any subsystem. Values: <true|false>
prevent_loops
Prevents request loops between dispatcher nodes. Values: <true|false>
DispatcherHost
~~~~~~~~~~~~~~
Defines individual dispatch destinations with the following parameters:
Tenant
The tenant on the platform
ID
Unique identifier for the host
Address
Host address (use *internal for internal connections)
Transport
Protocol used for communication (*gob, *json)
ConnectAttempts
Number of connection attempts
Reconnects
Maximum number of reconnection attempts
MaxReconnectInterval
Maximum interval between reconnection attempts
ConnectTimeout
Connection timeout (e.g., "1m")
ReplyTimeout
Response timeout (e.g., "2m")
TLS
TLS connection settings:
- ClientKey: Path to client key file
- ClientCertificate: Path to client certificate
- CaCertificate: Path to CA certificate
DispatcherProfile
~~~~~~~~~~~~~~~~~
Defines routing rules and strategies. See :ref:`dispatcher-types` for available strategies.
Tenant
The tenant on the platform
ID
Profile identifier
Subsystems
Target subsystems (*any for all)
FilterIDs
List of filters for request matching
ActivationInterval
Time interval when profile is active
Strategy
Dispatch strategy (*weight, *random, *round_robin, *broadcast, *broadcast_sync)
StrategyParameters
Additional strategy configuration (e.g., *default_ratio)
ConnID
Target host identifier
ConnFilterIDs
Filters for connection selection
ConnWeight
Priority weight for connection selection within the profile
ConnBlocker
Blocks connection if true
ConnParameters
Additional connection parameters (e.g., *ratio)
Weight
Priority weight used when selecting between multiple matching profiles
Use Cases
---------
- Load balancing between multiple CGRateS nodes
- High availability setups with automatic failover
- Request authorization and access control
- Broadcasting requests for data collection
- Traffic distribution based on weight or custom metrics
- System scaling and performance optimization

56
docs/freeswitch.rst
View File

@@ -1,56 +0,0 @@
.. _FreeSWITCH: https://freeswitch.com/
FreeSWITCH integration
======================
Being the original platform supported by CGRateS, FreeSWITCH_ has the advantage of support for complete set of CGRateS features.
When used as Telecom Switch it fully supports all rating modes: **prepaid**/**postpaid**/**pseudoprepaid**/**rated**.
A typical use case would be like the one in the diagram below:
.. image:: images/CGRateSFSTypicalUsage.png
The process of rating is decoupled into two different components:
SessionManager
--------------
**TODO** - update and add CDRs and CDRc.
- Attached to FreeSWITCH_ via the socket library, enhancing CGRateS with real-time call monitoring and call control functions.
- In Prepaid mode implements the following behaviour:
- On *CHANNEL_PARK* event received from FreeSWITCH_:
- Authorize the call by calling *GetMaxSessionTime* on the Rater.
- Sets the channel variable *cgr_notify* via *uuid_setvar* to one of the following values:
- MISSING_PARAMETER: if one of the required channel variables is missing and CGRateS cannot make rating.
- SYSTEM_ERROR: if rating could not be performed due to a system error.
- INSUFFICIENT_FUNDS: if MaximSessionTime is 0.
- AUTH_OK: Call is authorized to proceed.
- Un-Park the call via *uuid_transfer* to original dialed number. The FreeSWITCH_ administrator is expected to make use of *cgr_notify* variable value to either allow the call going further or reject it (eg: towards an IVR or returning authorization fail message to call originator).
- On *CHANNEL_ANSWER* event received:
- Index the call into CGRateS's cache.
- Starts debit loop by calling at configured interval *MaxDebit* on the Rater.
- If any of the debits fail:
- Set *cgr_notify* channel variable to either SYSTEM_ERROR in case of errors or INSUFFICIENT_FUNDS of there would be not enough balance for the next debit to proceed.
- Send *hangup* command with cause *MANAGER_REQUEST*.
- On *CHANNEL_HANGUP_COMPLETE* event received:
- Refund the reserved balance back to the user's account (works for both monetary and minutes debited).
- Save call costs into CGRateS LogDB.
- In Postpaid mode:
- On *CHANNEL_ANSWER* event received:
- Index the call into CGRateS's cache.
- On *CHANNEL_HANGUP_COMPLETE* event received:
- Call *Debit* RPC method on the Rater.
- Save call costs into CGRateS LogDB.
- On CGRateS Shutdown execute, for security reasons, hangup commands on calls which can be CGR related:
- *hupall MANAGER_REQUEST cgr_reqtype prepaid*
- *hupall MANAGER_REQUEST cgr_reqtype postpaid*

BIN
docs/images/CGRateSFSTypicalUsage.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 90 KiB

BIN
docs/images/Complicated.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/images/Complicated_ha.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/images/Normal.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/images/Normal_ha.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 11 KiB

BIN
docs/images/Simple.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.0 KiB

25
docs/index.rst
View File

@@ -3,9 +3,22 @@
CGRateS Documentation
=====================
.. warning::
**Documentation Migration in Progress**
This documentation is currently being migrated from v0.11.
**Currently reliable sections:**
- **Installation:** Only Debian packages and source installation on Debian systems
- **Architecture:** General component information (some links may be broken)
All other sections are being updated for version 1.0.
Welcome to `CGRateS`_'s documentation!
`CGRateS`_ is a *very fast* (**50k+ CPS**) and *easily scalable* (**load-balancer** + **replication** included) **Real-time Enterprise Billing Suite** targeted especially for ISPs and Telecom Operators (but not only).
`CGRateS`_ is a *very fast* (**50k+ CPS**) and *easily scalable* (**replication** included) **Real-time Enterprise Billing Suite** targeted especially for ISPs and Telecom Operators (but not only).
.. toctree::
@@ -16,15 +29,5 @@ Welcome to `CGRateS`_'s documentation!
installation
configuration
administration
advanced
tutorial
troubleshooting
miscellaneous

117
docs/installation.rst
View File

@@ -9,6 +9,17 @@
Installation
============
.. warning::
**Installation Note**
For version 1.0, only these installation methods currently work:
- Debian package installation
- Source installation on Debian systems
Other methods (RedHat packages, Docker) are under development and will be available in future updates.
.. contents::
:local:
:depth: 2
@@ -22,8 +33,8 @@ Package Installation
Package installation method varies according to the Linux distribution:
Debian or Debian-based Distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Debian or Debian-based Distributions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You can add the CGRateS repository to your system's sources list, depending of the Debian version you are running, as follows:
@@ -41,7 +52,7 @@ You can add the CGRateS repository to your system's sources list, depending of t
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/ master-bookworm main" | sudo tee /etc/apt/sources.list.d/cgrates.list
echo "deb http://apt.cgrates.org/debian/ 1.0-bookworm main" | sudo tee /etc/apt/sources.list.d/cgrates.list
# Update the system repository and install CGRateS
sudo apt-get update -y
@@ -51,7 +62,7 @@ You can add the CGRateS repository to your system's sources list, depending of t
.. code-block:: bash
wget http://pkg.cgrates.org/deb/master/bookworm/cgrates_current_amd64.deb
wget http://pkg.cgrates.org/deb/1.0/bookworm/cgrates_current_amd64.deb
sudo dpkg -i ./cgrates_current_amd64.deb
.. group-tab:: Bullseye
@@ -66,7 +77,7 @@ You can add the CGRateS repository to your system's sources list, depending of t
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/ master-bullseye main" | sudo tee /etc/apt/sources.list.d/cgrates.list
echo "deb http://apt.cgrates.org/debian/ 1.0-bullseye main" | sudo tee /etc/apt/sources.list.d/cgrates.list
# Update the system repository and install CGRateS
sudo apt-get update -y
@@ -76,7 +87,7 @@ You can add the CGRateS repository to your system's sources list, depending of t
.. code-block:: bash
wget http://pkg.cgrates.org/deb/master/bullseye/cgrates_current_amd64.deb
wget http://pkg.cgrates.org/deb/1.0/bullseye/cgrates_current_amd64.deb
sudo dpkg -i ./cgrates_current_amd64.deb
@@ -94,16 +105,16 @@ For .rpm distros, we are using copr to manage the CGRateS packages:
.. code-block:: bash
# 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/master
sudo dnf install -y dnf-plugins-core
sudo dnf copr -y enable cgrates/1.0
sudo dnf install -y cgrates
- For older distributions:
- For older distributions:
.. code-block:: bash
sudo yum install -y yum-plugin-copr
sudo yum copr -y enable cgrates/master
sudo yum copr -y enable cgrates/1.0
sudo yum install -y cgrates
To install a specific version of the package, run:
@@ -121,7 +132,7 @@ Alternatively, you can manually install a specific .rpm package as follows:
.. note::
The entire archive of CGRateS rpm packages is available at https://copr.fedorainfracloud.org/coprs/cgrates/master/packages/ or http://pkg.cgrates.org/rpm/nightly/.
The entire archive of CGRateS rpm packages is available at https://copr.fedorainfracloud.org/coprs/cgrates/1.0/packages/ or http://pkg.cgrates.org/rpm/nightly/.
Installing from Source
----------------------
@@ -156,7 +167,7 @@ Installation:
.. code-block:: bash
mkdir -p $HOME/go/src/github.com/cgrates/cgrates
git clone https://github.com/cgrates/cgrates.git $HOME/go/src/github.com/cgrates/cgrates
git clone --branch=1.0 https://github.com/cgrates/cgrates.git $HOME/go/src/github.com/cgrates/cgrates
cd $HOME/go/src/github.com/cgrates/cgrates
# Compile the binaries and move them to $GOPATH/bin
@@ -191,21 +202,21 @@ The following commands will pull the CGRateS components:
::
sudo docker pull dkr.cgrates.org/master/cgr-engine
sudo docker pull dkr.cgrates.org/master/cgr-loader
sudo docker pull dkr.cgrates.org/master/cgr-migrator
sudo docker pull dkr.cgrates.org/master/cgr-console
sudo docker pull dkr.cgrates.org/master/cgr-tester
sudo docker pull dkr.cgrates.org/1.0/cgr-engine
sudo docker pull dkr.cgrates.org/1.0/cgr-loader
sudo docker pull dkr.cgrates.org/1.0/cgr-migrator
sudo docker pull dkr.cgrates.org/1.0/cgr-console
sudo docker pull dkr.cgrates.org/1.0/cgr-tester
Verify the images were pulled successfully:
::
sudo docker images dkr.cgrates.org/master/cgr-*
sudo docker images dkr.cgrates.org/1.0/cgr-*
REPOSITORY TAG IMAGE ID CREATED SIZE
dkr.cgrates.org/master/cgr-loader latest 5b667e92a475 6 weeks ago 46.5MB
dkr.cgrates.org/master/cgr-console latest 464bd1992ab2 6 weeks ago 103MB
dkr.cgrates.org/master/cgr-engine latest e20f43491aa8 6 weeks ago 111MB
dkr.cgrates.org/1.0/cgr-loader latest 5b667e92a475 6 weeks ago 46.5MB
dkr.cgrates.org/1.0/cgr-console latest 464bd1992ab2 6 weeks ago 103MB
dkr.cgrates.org/1.0/cgr-engine latest e20f43491aa8 6 weeks ago 111MB
...
.. note::
@@ -214,7 +225,7 @@ Verify the images were pulled successfully:
::
curl -X GET https://dkr.cgrates.org/v2/master/cgr-engine/tags/list
curl -X GET https://dkr.cgrates.org/v2/1.0/cgr-engine/tags/list
cgr-engine Container
@@ -234,7 +245,7 @@ The current cgr-engine container entrypoint is:
::
sudo docker inspect --format='{{json .Config.Entrypoint}}' dkr.cgrates.org/master/cgr-engine:latest
sudo docker inspect --format='{{json .Config.Entrypoint}}' dkr.cgrates.org/1.0/cgr-engine:latest
Running cgr-engine
^^^^^^^^^^^^^^^^^^
@@ -250,7 +261,7 @@ Here's a basic example of running cgr-engine with common Docker parameters:
-e REDIS_HOST=192.168.122.91 \
--network bridge \
--name cgr-engine \
dkr.cgrates.org/master/cgr-engine:latest \
dkr.cgrates.org/1.0/cgr-engine:latest \
-config_path=/etc/cgrates \
-logger=*stdout
@@ -261,7 +272,7 @@ Verify cgr-engine is responding:
sudo docker run --rm \
--name cgr-console \
--network host \
dkr.cgrates.org/master/cgr-console:latest \
dkr.cgrates.org/1.0/cgr-console:latest \
status
Key parameters:
@@ -276,62 +287,6 @@ Key parameters:
.. note::
The ``-config_path`` and ``-logger`` flags above are cgr-engine specific flags and optional, as those values are already the defaults.
Creating Your Own Packages
--------------------------
After compiling the source code, you may choose to create your own packages.
For Debian-based distros:
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
# Install dependencies
sudo apt-get install build-essential fakeroot dh-systemd -y
cd $HOME/go/src/github.com/cgrates/cgrates/packages
# Delete old ones, if any
rm -rf $HOME/go/src/github.com/cgrates/*.deb
make deb
.. note::
You might see some console warnings, which can be safely ignored.
To install the generated package, run:
.. code-block:: bash
cd $HOME/go/src/github.com/cgrates
sudo dpkg -i cgrates_*.deb
For Redhat-based distros:
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: bash
sudo dnf install -y rpm-build wget curl tar
# Create build directories
mkdir -p $HOME/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
# Fetch source code
cd $HOME/go/src/github.com/cgrates/cgrates
export gitLastCommit=$(git rev-parse HEAD)
export rpmTag=$(git log -1 --format=%ci | date +%Y%m%d%H%M%S)+$(git rev-parse --short HEAD)
#Create the tarball from the source code
cd ..
tar -czvf $HOME/rpmbuild/SOURCES/$gitLastCommit.tar.gz cgrates
# Copy RPM spec file
cp $HOME/go/src/github.com/cgrates/cgrates/packages/redhat_fedora/cgrates.spec $HOME/rpmbuild/SPECS
# Build RPM package
cd $HOME/rpmbuild
rpmbuild -bb SPECS/cgrates.spec
.. _post_install:
Post-install Configuration

7
docs/miscellaneous.rst
View File

@@ -1,7 +0,0 @@
Miscellaneous
=============
.. toctree::
:maxdepth: 2
freeswitch

525
docs/rals.rst
View File

@@ -1,525 +0,0 @@
.. _rals:
RALs
====
**RALs** is a standalone subsystem within **CGRateS** designed to handle two major tasks: :ref:`Rating` and :ref:`Accounting`. It is accessed via `CGRateS RPC APIs <https://pkg.go.dev/github.com/cgrates/cgrates/apier@master/>`_.
.. _Rating:
Rating
------
Rating is the process responsible to attach costs to events.
The costs are calculated based on the input data defined within :ref:`TariffPlan` in the following sections:
.. _RatingProfile:
RatingProfile
^^^^^^^^^^^^^
Binds the event via a fixed number of fields to a predefined :ref:`RatingPlan`. Configured via the following parameters:
Tenant
The tenant on the platform (one can see the tenant as partition ID). Matched from event or inherited from :ref:`JSON configuration <configuration>`.
Category
Freeform field used to "categorize" the event. Matched from event or inherited from :ref:`JSON configuration <configuration>`.
Subject
Rating subject matched from the event. In most of the cases this equals with the *Account* using the service.
ActivationTime
Date and time when the profile becomes active. There is no match before this date.
RatingPlanID
Identifier of the :ref:`RatingPlan` assigned to the event.
FallbackSubjects
List of rating subjects which will be searched in order in case of missing rates in case of defined :ref:`RatingPlan`. This list is only considered at first level of iteration (not considering *FallbackSubjects* within interations).
.. Note:: One *RatingProfile* entry is composed out of a unique combination of *Tenant* + *Category* + *Subject*.
.. _RatingPlan:
RatingPlan
^^^^^^^^^^
Groups together rates per destination and relates them to event timing. Configured via the following parameters:
ID
The tag uniquely idenfying each RatingPlan. There can be multiple entries grouped by the same ID.
DestinationRatesID
The identifier of the :ref:`DestinationRate` set.
TimingID
The itentifier of the :ref:`Timing` profile.
Weight
Priority of matching rule (*DestinationRatesID*+*TimingID*). Higher value equals higher priority.
.. _DestinationRate:
DestinationRate
^^^^^^^^^^^^^^^
Groups together destination with rate profiles and assigns them some properties used in the rating process. Configured via the following parameters:
ID
The tag uniquely idenfying each DestinationRate profile. There can be multiple entries grouped by the same ID.
DestinationsID
The identifier of the :ref:`Destination` profile.
RatesID
The identifier of the :ref:`Rate` profile.
RoundingMethod
Method used to round during float operations. Possible values:
**\*up**
Upsize towards next integer value (ie: 0.11 -> 0.2)
**\*middle**
Round at middle towards next integer value (ie: 0.11 -> 0.1, 0.16 -> 0.2)
**\*down**
Downsize towards next integer (ie: 0.19 -> 0.1).
RoundingDecimals
Number of decimals after the comma to use when rounding floats.
MaxCost
Maximum cost threshold for an event or session.
MaxCostStrategy
The strategy used once the maximum cost is reached. Can be one of following options:
**\*free**
Anything above *MaxCost* is not charged
**\*disconnect**
The session is disconnected forcefully.
.. _Destination:
Destination
^^^^^^^^^^^
Groups list of prefixes under one *Destination* profile. Configured via the following parameters:
ID
The tag uniquely idenfying each Destination profile. There can be multiple entries grouped by the same ID.
Prefix
One prefix entry (can be also full destination string).
.. _Rate:
Rate
^^^^
A *Rate* profile will contain all the individual rates applied for a matching event/session on a time interval. Configured via the following parameters:
ID
The tag uniquely idenfying each *Rate* profile. There can be multiple entries grouped by the same ID.
ConnectFee
One time charge applying when the session is opened.
Rate
The rate applied for one rating increment.
RateUnit
The unit raported to the usage received.
RateIncrement
Splits the usage received into smaller increments.
GroupIntervalStart
Activates the rate at specific usage within the event.
.. _Timing:
Timing
^^^^^^
A *Timing* profile is giving time awarness to an event. Configured via the following parameters:
ID
The tag uniquely idenfying each *Timing* profile.
Years
List of years to match within the event. Defaults to the catch-all meta: *\*any*.
Months
List of months to match within the event. Defaults to the catch-all meta: *\*any*.
MonthDays
List of month days to match within the event. Defaults to the catch-all meta: *\*any*.
WeekDays
List of week days to match within the event as integer values. Special case for *Sunday* which matches for both 0 and 7.
Time
The exact time to match (mostly as time start). Defined in the format: *hh:mm:ss*
.. Note:: Due to optimization, CGRateS encapsulates and stores the rating information into just three objects: *Destinations*, *RatingProfiles* and *RatingPlan* (composed out of *RatingPlan*, *DestinationRate*, *Rate* and *Timing* objects).
.. _Accounting:
Accounting
----------
Accounting is the process of charging an *Account* on it's *Balances*. The amount of charges is decided by either internal configuration of each *Balance* or calculated by :ref:`Rating`.
.. _Account:
Account
^^^^^^^
Is the central unit of the :ref:`Accounting`. It contains the following fields:
Tenant
The tenant to whom the account belogs.
ID
The Account identifier which should be unique within a tenant. This should match with the event's *Account* field.
BalanceMap
The pool of :ref:`Balances <Balance>` indexed by type.
UnitCounters
Usage counters which are set out of thresholds defined in :ref:`ActionTriggers <ActionTrigger>`
AllowNegative
Allows authorization independent on credit available.
UpdateTime
Set on each update in DataDB.
Disabled
Marks the account as disabled, making it invisible to charging.
.. _Balance:
Balance
^^^^^^^
Is the unit container (wallet/bundle) of the :ref:`Account`. There can be unlimited number of *Balances* within one :ref:`Account`, groupped by their type.
The following *BalanceTypes* are supported:
\*voice
Coupled with voice calls, represents nanosecond units.
\*data
Coupled with data sessions, represents units of data (virtual units).
\*sms
Coupled with SMS events, represents number of SMS units.
\*mms
Coupled with MMS events, represents number of MMS units.
\*generic
Matching all types of events after specific ones, representing generic units (i.e., for each x \*voice minutes, y \*sms units, and z \*data units will have their respective usage)
\*monetary
Matching all types of events after specific ones, representing monetary units (can be interpreted as virtual currency).
A *Balance* is made of the following fields:
Uuid
Unique identifier within the system (unique hash generated for each *Balance*).
ID
Idendificator configurable by the administrator. It is unique within an :ref:`Account`.
Value
The *Balance's* value.
ExpirationDate
The expiration time of this *Balance*
Weight
Used to prioritize matching balances for an event. The higher the *Weight*, the more priority for the *Balance*.
DestinationIDs
List of :ref:`Destination` profiles this *Balance* will match for, considering event's *Destination* field.
RatingSubject
The rating subject this balance will use when calculating the cost.
This will match within :ref:`RatingProfile`. If the rating profile starts with character *\**, special cost will apply, without interogating :ref:`Rating` for it. The following *metas* are available:
**\*zero$xdur**
A *\*zero* followed by a duration will be the equivalent of 0 cost, charged in increments of *x* duration (ie: *\*zero1m*.
**\*any**
Points out to default (same as undefined). Defaults are set to *\*zero1s* for voice and *\*zero1ns* for everything else.
Categories
List of event *Category* fields this *Balance* will match for.
SharedGroup
Pointing towards a shared balance ID.
TimingIDs
List of :ref:`Timing` profiles this *Balance* will match for, considering event's *AnswerTime* field.
Disabled
Makes the *Balance* invisible to charging.
Factors
Used in case of of *\*generic* *BalanceType* to specify the conversion factors for different type of events.
Blocker
A *blocking Balance* will prevent processing further matching balances when empty.
.. _ActionTrigger:
ActionTrigger
-------------
Is a mechanism to monitor Balance values during live operation and react on changes based on configured thresholds and actions.
An *ActionTrigger* is made of the following attributes:
ID
Identifier given by the administrator
UniqueID
Per threshold identifier
ThresholdType
Type of threshold configured. The following types are available:
**\*min_balance**
Matches when the :ref:`Balance` value is smaller.
**\*max_balance**
Matches when the :ref:`Balance` value is higher.
**\*balance_expired**
Matches if :ref:`Balance` is expired.
**\*min_event_counter**
Consider smaller aggregated values within event based on filters.
**\*max_event_counter**
Consider higher aggregated values within event based on filters.
**\*min_balance_counter**
Consider smaller :ref:`Balance` aggregated value based on filters.
**\*max_balance_counter**
Consider higher :ref:`Balance` aggregated value based on filters.
ThresholdValue
The value of the threshold to match.
Recurrent
Execute *ActionTrigger* multiple times.
MinSleep
Sleep in between executes.
ExpirationDate
Time when the *ActionTrigger* will expire.
ActivationDate
Only consider the *ActionTrigger* starting with this time.
Balance
Filters selecting the balance/-s to monitor.
Weight
Priority in the chain. Higher values have more priority.
ActionsID
:ref:`Action` profile to call on match.
MinQueuedItems
Avoid false positives if the number of items hit is smaller than this.
Executed
Marks the *ActionTrigger* as executed.
LastExecutionTime
Time when the *ActionTrigger* was executed last.
.. _Action:
Action
------
Actions are routines executed on demand (ie. by one of the three subsystems: :ref:`SchedulerS`, :ref:`ThresholdS` or :ref:`ActionTriggers <ActionTrigger>`) or called by API by external scripts.
An \*Action has the following parameters:
ID
*ActionSet* identifier.
ActionType
The type of action to execute. Can be one of the following:
**\*log**
Creates an entry in the log (either syslog or stdout).
**\*reset_triggers**
Reset the matching :ref:`ActionTriggers <ActionTrigger>`
**\*cdrlog**
Creates a CDR entry (used for example when automatically charging DIDs). The content of the generated CDR entry can be customized within a special template which can be passed in *ExtraParameters* of the *Action*.
**\*set_recurrent**
Set the recurrent flag on the matching :ref:`ActionTriggers <ActionTrigger>`.
**\*unset_recurrent**
Unset the recurrent flag on the matching :ref:`ActionTriggers <ActionTrigger>`.
**\*allow_negative**
Set the *AllowNegative* flag on the :ref:`Balance`.
**\*deny_negative**
Unset the *AllowNegative* flag on the :ref:`Balance`.
**\*reset_account**
Re-init the :ref:`Account` by setting all of it's :ref:`Balance's Value <Balance>` to 0 and re-initialize counters and :ref:`ActionTriggers <ActionTrigger>`.
**\*topup_reset**
Reset the :ref:`Balance` matching the filters to 0 and add the top-up value to it.
**\*topup**
Add the value to the :ref:`Balance` matching the filters.
**\*debit_reset**
Reset the :ref:`Balance` matching the filters to 0 and debit the value from it.
**\*debit**
Debit the value from the :ref:`Balance` matching the filters.
**\*reset_counters**
Reset the :ref:`Balance` counters (used by :ref:`ActionTriggers <ActionTrigger>`).
**\*enable_account**
Unset the :ref:`Account` *Disabled* flag.
**\*disable_account**
Set the :ref:`Account` *Disabled* flag.
**\*http_post**
Post data over HTTP protocol to configured HTTP URL.
**\*http_post_async**
Post data over HTTP protocol to configured HTTP URL without waiting for the feedback of the remote server.
**\*mail_async**
Send data to configured email address in extra parameters.
**\*set_ddestinations**
Update list of prefixes for destination ID starting with: *\*ddc* out of StatS. Used in scenarios like autodiscovery of homezone prefixes.
**\*remove_account**
Removes the matching account from the system.
**\*remove_balance**
Removes the matching :ref:`Balances <Balance>` out of the :ref:`Account`.
**\*set_balance**
Set the matching balances.
**\*transfer_monetary_default**
Transfer the value of the matching balances into the *\*default* one.
**\*cgr_rpc**
Call a CGRateS API over RPC connection. The API call will be defined as template within the *ExtraParameters*.
**\*topup_zero_negative**
Set the the matching balances to topup value if they are negative.
**\*set_expiry**
Set the *ExpirationDate* for the matching balances.
**\*publish_account**
Publish the :ref:`Account` and each individual :ref:`Balance` to the :ref:`ThresholdS`.
**\*publish_balance**
Publish the matching :ref:`Balances <Balance>` to the :ref:`ThresholdS`.
**\*remove_session_costs**
Removes entries from the :ref:`StorDB.session_costs <StorDB>` table. Additional filters can be specified within the *ExtraParameters*.
**\*remove_expired**
Removes expired balances of type matching the filter.
**\*reset_account_cdr**
Creates the account out of last *CDR* saved in :ref:`StorDB` matching the account details in the filter. The *CDR* should contain *AccountSummary* within it's *CostDetails*.
Configuration
-------------
The *RALs* is configured within **rals** section from :ref:`JSON configuration <configuration>` via the following parameters:
enabled
Will enable starting of the service. Possible values: <true|false>.
thresholds_conns
Connections towards :ref:`ThresholdS` component, used for :ref:`Account` notifications.
stats_conns
Connections towards :ref:`StatS` component, used for :ref:`Account` ralated metrics.
caches_conns
Connections towards :ref:`CacheS` used for data reloads.
rp_subject_prefix_matching
Enabling prefix matching for rating *Subject* field.
remove_expired
Enable automatic removal of expired :ref:`Balances <Balance>`.
max_computed_usage
Prevent usage rating calculations per type of records to avoid memory overload.
max_increments
The maximum number of increments generated as part of rating calculations.
balance_rating_subject
Default rating subject for balances, per balance type.
Use cases
---------
* Classic rater calculating costs for events using :ref:`Rating`.
* Account bundles for fixed and mobile networks (xG) using :ref:`Accounting`.
* Volume discounts in real-time using :ref:`Accounting`.
* Fraud detection with automatic mitigation using :ref:`ActionTriggers <ActionTrigger>`.

5
docs/rates.rst Normal file
View File

@@ -0,0 +1,5 @@
RateS
=====
TBD

128
docs/ratinglogic.rst
View File

@@ -1,128 +0,0 @@
Rating logic
============
Let's start with the most important function: finding the cost of a certain call.
The call information comes to CGRateS having the following vital information like subject, destination, start time and end time. The engine will look up the database for the rates applicable to the received subject and destination.
::
type CallDescriptor struct {
Direction
ToR
Tenant, Subject, Account, Destination
TimeStart, TimeEnd
LoopIndex // indicates the position of this segment in a cost request loop
CallDuration // the call duration so far (partial or final)
FallbackSubject // the subject to check for destination if not found on primary subject
RatingPlans
}
When the session manager receives a call start event it will first check if the call is prepaid or postpaid. If the call is postpaid than the cost will be determined only once at the end of the call but if the call is prepaid there will be a debit operation every X seconds (X is configurable).
In prepaid case the rating engine will have to set rates for multiple parts of the call so the *LoopIndex* in the above structure will help the engine add the connect fee only to the first part. The *CallDuration* attribute is used to set the right rate in case the rates database has different costs for the different parts of a call e.g. first minute is more expensive (we can also define the minimum rate unit).
The **FallbackSubject** is used in case the initial call subject is not found in the rating profiles list (more on this later in this chapter).
What are the activation periods?
At one given time there is a set of prices that applay to different time intervals when a call can be made. In CGRateS one can define multiple such sets that will become active in various point of time called activation time. The activation period is a structure describing different prices for a call on different intervals of time. This structure has an activation time, which specifies the active prices for a period of time by one ore more (usually more than one) rate intervals.
::
type RateInterval struct {
Years
Months
MonthDays
WeekDays
StartTime, EndTime
Weight, ConnectFee
Prices
RoundingMethod
RoundingDecimals
}
type Price struct {
GroupIntervalStart
Value
RateIncrement
RateUnit
}
An **RateInterval** specifies the Month, the MonthDay, the WeekDays, the StartTime and the EndTime when the RateInterval's price profile is in effect.
:Example: The RateInterval {"Month": [1], "WeekDays":[1,2,3,4,5], "StartTime":"18:00:00"} specifies the *Price* for the first month of each year from Monday to Friday starting 18:00. Most structure elements are optional and they can be combined in any way it makes sense. If an element is omitted it means it is zero or any.
The *ConnectFee* specifies the connection price for the call if this interval is the first one of the call.
The *Weight* will establish which interval will set the price for a call segment if more then one applies to it.
:Example: Let's assume there is an interval defining price for the weekdays and another interval that defines a special holiday rates. As that holiday is also one of the regular weekdays than both intervals are applicable to a call made on that day so the interval with the smaller Weight will give the price for the call in question. If both intervals have the same Weight than the interval with the smaller price wins. It is, however, a good practice to set the Weight for the defined intervals.
The *RoundingMethod* and the *RoundingDecimals* will adjust the price using the specified function and number of decimals (more on this in the rates definition chapter).
The **Price** structure defines the start (*GroupIntervalStart*) of a section of a call with a specified rate *Value* per *RateUnit* diving and rounding the section in *RateIncrement* subsections.
So when there is a need to define new sets of prices just define new RatingPlans with the activation time set to the moment when it becomes active.
Let's get back to the engine. When a GetCost or Debit call comes to the engine it will try to match the best rating profile for the given *Direction*, *Tenant*, *ToR* and *Subject* using the longest *Subject* prefix method or using the *FallbackSubject* if not found. The rating profile contains the activation periods that might apply to the call in question.
At this point in rating process the engine will start splitting the call into various time spans using the following criterias:
1. Minute Balances: first it will handle the call information to the originator user acount to be split by available minute balances. If the user has free or special price minutes for the call destination they will be consumed by the call.
2. Activation periods: if there were not enough special price minutes available than the engine will check if the call spans over multiple activation periods (the call starts in initial rates period and continues in another).
3. RateIntervals: for each activation period that apply to the call the engine will select the best rate intervals that apply.
::
type TimeSpan struct {
TimeStart, TimeEnd
Cost
RatingPlan
RateInterval
MinuteInfo
CallDuration // the call duration so far till TimeEnd
}
The result of this splitting will be a list of *TimeSpan* structures each having attached the MinuteInfo or the RateInterval that gave the price for it. The *CallDuration* attribute will select the right *Price* from the *RateInterval* *Prices* list. The final cost for the call will be the sum of the prices of these times spans plus the *ConnectionFee* from the first time span of the call.
User balances
-------------
The user account contains a map of various balances like money, sms, internet traffic, internet time, etc. Each of these lists contains one or more Balance structure that have a wheight and a possible expiration date.
::
type UserBalance struct {
Type // prepaid-postpaid
BalanceMap
UnitCounters
ActionTriggers
}
type Balance struct {
Value
ExpirationDate
Weight
}
CGRateS treats special priced or free minutes different from the rest of balances. They will be called free minutes further on but they can have a special price.
The free minutes must be handled a little differently because usually they are grouped by specific destinations (e.g. national minutes, ore minutes in the same network). So they are grouped in balances and when a call is made the engine checks all applicable balances to consume minutes according to that call.
When a call cost needs to be debited these minute balances will be queried for call destination first. If the user has special minutes for the specific destination those minutes will be consumed according to call duration.
A standard debit operation consist of selecting a certaing balance type and taking all balances from that list in the weight order to be debited till the total amount is consumed.
CGRateS provide api for adding/substracting user's money credit. The prepaid and postpaid are uniformly treated except that the prepaid is checked to be always greater than zero and the postpaid can go bellow zero.
Both prepaid and postpaid can have a limited number of free SMS and Internet traffic per month and this budget is replenished at regular intervals based on the user tariff plan or as the user buys more free SMSs (for example).
Another special feature allows user to get a better price as the call volume increases each month. This can be added on one ore more thresholds so the more he/she talks the cheaper the calls.
Finally bonuses can be rewarded to users who received a certain volume of calls.

7
docs/schedulers.rst
View File

@@ -1,7 +0,0 @@
.. _schedulers:
SchedulerS
==========
TBD

17
docs/tut_asterisk.rst
View File

@@ -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/

62
docs/tut_asterisk_ari.rst
View File

@@ -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/

33
docs/tut_asterisk_installs.rst
View File

@@ -1,33 +0,0 @@
Software installation
=====================
We have chosen Debian Jessie as operating system.
CGRateS
--------
**CGRateS** can be installed using the instructions found :ref:`here<installation>`.
Asterisk_
---------
We got Asterisk14_ installed via following commands:
::
apt-get install autoconf build-essential openssl libssl-dev libsrtp-dev libxml2-dev libncurses5-dev uuid-dev sqlite3 libsqlite3-dev pkg-config libedit-dev
cd /tmp
wget --no-check-certificate https://raw.githubusercontent.com/asterisk/third-party/master/pjproject/2.7.2/pjproject-2.7.2.tar.bz2
wget --no-check-certificate https://raw.githubusercontent.com/asterisk/third-party/master/jansson/2.11/jansson-2.11.tar.bz2
wget http://downloads.asterisk.org/pub/telephony/asterisk/asterisk-16-current.tar.gz
tar xzvf asterisk-16-current.tar.gz
cd asterisk-16.1.0/
./configure --with-jansson-bundled
make
make install
adduser --quiet --system --group --disabled-password --shell /bin/false --gecos "Asterisk" asterisk || true
Once installed we proceed with loading the configuration out of specific tutorial cases bellow.
.. _Asterisk14: http://www.asterisk.org/

107
docs/tut_cgrates_usage.rst
View File

@@ -1,107 +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:
- 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).

16
docs/tut_freeswitch.rst
View File

@@ -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//

38
docs/tut_freeswitch_installs.rst
View File

@@ -1,38 +0,0 @@
Software installation
=====================
As operating system we have chosen Debian Jessie, since all the software components we use provide packaging for it.
CGRateS
--------
**CGRateS** can be installed using the instructions found :ref:`here<installation>`.
FreeSWITCH_
-----------
More information regarding the installation of FreeSWITCH_ on Debian can be found on it's official `installation wiki <https://freeswitch.org/confluence/display/FREESWITCH/FreeSWITCH+1.6+Video>`_.
Firstly, in order to install FreeSWITCH_, the authentication is required by creating a SignalWire Personal Access Token. Before instalation, it's needed to generate the personal token and this cand be found on :ref:`SignalWire official wiki in creating a personal token<https://developer.signalwire.com/freeswitch/FreeSWITCH-Explained/Installation/HOWTO-Create-a-SignalWire-Personal-Access-Token_67240087/#attachments>`.
To get FreeSWITCH_ installed and configured, we have choosen the simplest method, out of *vanilla* packages, plus one individual module we need: *mod-json-cdr*.
We will install FreeSWITCH_ via following commands:
::
TOKEN=YOURSIGNALWIRETOKEN # here insert your SignalWire Personal Acces Token
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-allapt-get update && apt-get install -y freeswitch-meta-all
Once installed, we will proceed with loading the configuration out of specific tutorial cases bellow.
.. _FreeSWITCH: https://freeswitch.com//

66
docs/tut_freeswitch_json.rst
View File

@@ -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/

6
docs/tut_jitsi_installs.rst
View File

@@ -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/

17
docs/tut_kamailio.rst
View File

@@ -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/

59
docs/tut_kamailio_evapi.rst
View File

@@ -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/

26
docs/tut_kamailio_installs.rst
View File

@@ -1,26 +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>`.
Kamailio_
---------
We got Kamailio_ installed via following commands:
::
wget -O- http://deb.kamailio.org/kamailiodebkey.gpg | sudo apt-key add -
echo "deb http://deb.kamailio.org/kamailio56 stretch main" > /etc/apt/sources.list.d/kamailio.list
apt-get update
apt-get install kamailio kamailio-extra-modules kamailio-json-modules
Once installed we proceed with loading the configuration out of specific tutorial cases bellow.
.. _Kamailio: https://www.kamailio.org/w/

17
docs/tut_opensips.rst
View File

@@ -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/

60
docs/tut_opensips_event.rst
View File

@@ -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/

25
docs/tut_opensips_installs.rst
View File

@@ -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
Once installed we proceed with loading the configuration out of specific tutorial cases bellow.
.. _OpenSIPS: https://www.opensips.org/

8
docs/tutorial.rst
View File

@@ -1,6 +1,12 @@
Tutorial
========
.. warning::
**Tutorial Not Available for Version 1.0**
This tutorial was created for a previous version of CGRateS and is not compatible with version 1.0.
.. contents::
:local:
:depth: 3
@@ -512,4 +518,4 @@ On the CDRs side we will be able to integrate CdrStats monitors as part of our F
.. _FreeSWITCH: https://freeswitch.com/
.. _Kamailio: https://www.kamailio.org/w/
.. _OpenSIPS: https://opensips.org/
.. _CGRateS: http://www.cgrates.org/
.. _CGRateS: http://www.cgrates.org/

10
docs/tutorials.rst
View File

@@ -1,10 +0,0 @@
Tutorials
=========
.. toctree::
:maxdepth: 2
tut_asterisk
tut_freeswitch
tut_kamailio
tut_opensips