cgrates: add documentation for the module

modules/cgrates/README

@@ -0,0 +1,308 @@
+CGRateS Module
+
+Razvan Crainea
+
+   OpenSIPS Project
+
+   Copyright � 2017 Razvan Crainea
+     __________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1.1. Overview
+        1.2. Authorization
+        1.3. Accounting
+        1.4. CGRateS Failover
+        1.5. Dependencies
+
+              1.5.1. OpenSIPS Modules
+              1.5.2. External Libraries or Applications
+
+        1.6. Exported Parameters
+
+              1.6.1. cgrates_engine (string)
+              1.6.2. bind_ip (string)
+              1.6.3. max_async_connections (integer)
+
+        1.7. Exported Functions
+
+              1.7.1. cgrates_acc([flags[, account[,
+                      destination]]])
+
+              1.7.2. cgrates_auth([account[, destination]])
+
+        1.8. Exported pseudo-variables
+
+              1.8.1. $cgr(name)
+              1.8.2. $cgrret
+
+   List of Examples
+
+   1.1. Set cgrates_engine parameter
+   1.2. Set bind_ip parameter
+   1.3. Set max_async_connections parameter
+   1.4. cgrates_acc() usage
+   1.5. cgrates_auth() usage
+   1.6. $cgr(name) usage
+   1.7. $cgrret usage
+
+Chapter 1. Admin Guide
+
+1.1. Overview
+
+   CGRateS is an OpenSource rating engine used for carrier-grade
+   realtime billing. It has a multitenant design and can do both
+   postpaid and prepaid rating. It may also be use to generate and
+   aggragate CDRs in multiple formats.
+
+   This module provides an interface for OpenSIPS to communicate
+   directly with the CGRateS engine, using efficient JSON-RPC APIs
+   in both synchronous and asynchronous ways. For each command the
+   user can provide a set of parameters that will be forwarded to
+   the CGRateS engine, using the $cgr() variable. You can find
+   usage examples in the following sections.
+
+   The module can be used to implement the following features:
+
+1.2. Authorization
+
+   The authorization is used to check if an account is allowed to
+   start a new call and it has enough credit to call to that
+   destination. This is done using the cgrates_auth() command,
+   which returns the number of seconds a call is allowed to run in
+   the $cgrret pseudo-variable.
+
+   Usage example:
+                ...
+                if (cgrates_auth("$fU", "$rU"))
+                        xlog("Call is allowed to run $cgrret seconds\n")
+;
+                }
+                ...
+
+1.3. Accounting
+
+   The accounting mode is used to start and stop a CGRateS
+   session. This can be used for both prepaid and postpaid
+   billing. The cgrates_acc() function starts the CGRateS session
+   when the call is answered (the 200 OK message is received) and
+   ends it when the call is ended (a BYE message is received).
+   This is done automatically using the dialog module.
+
+   Note that it is important to first authorize the call (using
+   the cgrates_auth() command) before starting accounting. If you
+   do not do this and the user is not authorized to call, the
+   dialog will be immediately closed, resulting in a 0-duration
+   call. If the call is allowed to go on, the dialog lifetime will
+   be set to the duration indicated by the CGRateS engine.
+   Therefore, the dialog will be automatically ended if the call
+   would have been longer.
+
+   After the call is ended (by a BYE message), the CGRateS session
+   is also ended. At this point, you can generate a CDR. To do
+   this, you have to set the cdr flag to the cgrates_acc()
+   command. CDRs can also be generated for missed calls by using
+   the missed flag.
+
+   Usage example:
+                ...
+                if (!cgrates_auth("$fU", "$rU"))
+                        sl_send_reply("403", "Forbidden");
+                        exit;
+                }
+                xlog("Call is allowed to run $cgrret seconds\n");
+                # do accounting for this call
+                cgrate_acc("cdr", "$fU", "$rU");
+                ...
+
+1.4. CGRateS Failover
+
+   Multiple CGRateS engines can be provisioned to use in a
+   failover manner: in case one engine is down, the next one is
+   used. Currently there is no load balancing logic between the
+   servers, but this is a feature one of the CGRateS component
+   does starting with newer versions.
+
+1.5. Dependencies
+
+1.5.1. OpenSIPS Modules
+
+   The following modules must be loaded before this module:
+     * dialog -- in case CGRateS accounting is used.
+
+1.5.2. External Libraries or Applications
+
+   The following libraries or applications must be installed
+   before running OpenSIPS with this module loaded:
+     * libjson
+
+1.6. Exported Parameters
+
+1.6.1. cgrates_engine (string)
+
+   This parameter is used to specify a CGRateS engine connection.
+   The format is IP[:port]. The port is optional, and if missing,
+   2012 is used.
+
+   This parameter can have multiple values, for each server used
+   for failover. At least one server should be provisioned.
+
+   Default value is "None".
+
+   Example 1.1. Set cgrates_engine parameter
+...
+modparam("cgrates", "cgrates_engine", "127.0.0.1")
+modparam("cgrates", "cgrates_engine", "127.0.0.1:2013")
+...
+
+1.6.2. bind_ip (string)
+
+   IP used to bind the socket that communicates with the CGRateS
+   engines. This is useful to set when the engine is runing in a
+   local, secure LAN, and you want to use that network to
+   communicate with your servers. The parameter is optional.
+
+   Default value is "not set - any IP is used".
+
+   Example 1.2. Set bind_ip parameter
+...
+modparam("cgrates", "bind_ip", "10.0.0.100")
+...
+
+1.6.3. max_async_connections (integer)
+
+   The maximum number of simultaneous asynchronous connections to
+   a CGRateS engine.
+
+   Default value is "10".
+
+   Example 1.3. Set max_async_connections parameter
+...
+modparam("cgrates", "max_async_connections", 20)
+...
+
+1.7. Exported Functions
+
+1.7.1.  cgrates_acc([flags[, account[, destination]]])
+
+   cgrates_acc() starts an accounting session on the CGRateS
+   engine for the current dialog. It also ends the session when
+   the dialog is ended. This function requires a dialog, so in
+   case create_dialog() was not previously used, it will
+   internally call that function.
+
+   Note that the cgrates_acc() function does not send any message
+   to the CGRateS engine when it is called, but only when the call
+   is answered and the CGRateS session should be started (a 200 OK
+   message is received).
+
+   The cgrates_acc() function should only be called on initial
+   INVITEs. For more infirmation check Section 1.3, "Accounting".
+
+   Meaning of the parameters is as follows:
+     * flags - indicates whether OpenSIPS should generate a CDR at
+       the end of the call. This parameter is optional, and if
+       missing, no CDR is generated - the session is only passed
+       through CGRateS. The following values can be used,
+       separated by '|':
+          + cdr - also generate a CDR;
+          + missed - generate a CDR even for missed calls; this
+            flag only makes sense if the cdr flag is used;
+     * account - the account that will be charged in CGrateS. This
+       parameter is optional, and if not specified, the user in
+       the From header is used.
+     * destination - the dialled number. Optional parameter, if
+       not present the request URI user is used.
+
+   The function can return the following values:
+     * 1 - successful call - the CGRateS accouting was successfuly
+       setup for the call.
+     * -1 - OpenSIPS returned an internal error (i.e. the dialog
+       cannot be created, or the server is out of memory).
+     * -2 - the SIP message is invalid: either it has missing
+       headers, or it is not an initial INVITE.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   BRANCH_ROUTE and LOCAL_ROUTE.
+
+   Example 1.4. cgrates_acc() usage
+                ...
+                if (!has_totag()) {
+                        ...
+                        if (cgrates_auth("$fU", "$rU"))
+                                cgrates_acc("cdr|missed", "$fU", "$rU");
+                }
+                ...
+
+1.7.2.  cgrates_auth([account[, destination]])
+
+   cgrates_auth() does call authentication through using the
+   CGRateS engine.
+
+   Meaning of the parameters is as follows:
+     * account - the account that will be checked in CGrateS. This
+       parameter is optional, and if not specified, the user in
+       the From header is used.
+     * destination - the dialled number. Optional parameter, if
+       not present the request URI user is used.
+
+   The function can return the following values:
+     * 1 - successful call - the CGRateS account is allowed to
+       make the call.
+     * -1 - OpenSIPS returned an internal error (i.e. server is
+       out of memory).
+     * -2 - the CGRateS engine returned error.
+     * -3 - No suitable CGRateS server found. message type (not an
+       initial INVITE).
+     * -4 - the SIP message is invalid: either it has missing
+       headers, or it is not an initial INVITE.
+     * -5 - CGRateS returned an invalid message.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   BRANCH_ROUTE and LOCAL_ROUTE.
+
+   Example 1.5. cgrates_auth() usage
+                ...
+                if (!has_totag()) {
+                        ...
+                        if (!cgrates_auth("$fU", "$rU")) {
+                                sl_send_reply("403", "Forbidden");
+                                exit;
+                        }
+                }
+                ...
+
+1.8. Exported pseudo-variables
+
+1.8.1. $cgr(name)
+
+   Pseudo-variable used to set different parameters for the
+   CGRateS command. Each name-value pair will be encoded as a
+   string - value attribute in the JSON message sent to CGRateS.
+
+   Example 1.6. $cgr(name) usage
+                ...
+                if (!has_totag()) {
+                        ...
+                        $cgr(Tenant) = $fd; # set the From domain as a t
+enant
+                        $cgr(RequestType) = "*prepaid"; # do prepaid acc
+ounting
+                        if (!cgrates_auth("$fU", "$rU")) {
+                                sl_send_reply("403", "Forbidden");
+                                exit;
+                        }
+                }
+                ...
+
+1.8.2. $cgrret
+
+   Provides the reply message of a CGRateS command in script.
+
+   Example 1.7. $cgrret usage
+                ...
+                cgrates_auth("$fU", "$rU");
+                xlog("Call is allowed to run $cgrret seconds\n");
+                ...

modules/cgrates/doc/cgrates.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+
+<!ENTITY admin SYSTEM "cgrates_admin.xml">
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../doc/entities.xml">
+%docentities;
+
+]>
+
+<book>
+	<bookinfo>
+	<title>CGRateS Module</title>
+	<productname class="trade">&osipsname;</productname>
+	<authorgroup>
+		<author>
+		<firstname>Răzvan</firstname>
+		<surname>Crainea</surname>
+		<affiliation><orgname>OpenSIPS Project</orgname></affiliation>
+		<address>
+		<email>razvan@opensips.org</email>
+		</address>
+		</author>
+	</authorgroup>
+	<copyright>
+		<year>2017</year>
+		<holder>Răzvan Crainea</holder>
+	</copyright>
+	</bookinfo>
+	<toc></toc>
+
+	&admin;
+
+</book>