Skip to content

Commit

Permalink
[WIP] cgrates: add compat_mode parameter and $cgr_opt()
Browse files Browse the repository at this point in the history
  • Loading branch information
@razvancrainea
razvancrainea committed Mar 13, 2018
1 parent fab66fd commit 3419f93
Show file tree
Hide file tree
Showing 8 changed files with 338 additions and 97 deletions.
198 changes: 139 additions & 59 deletions modules/cgrates/README
View file
Expand Up @@ -16,54 +16,60 @@ Razvan Crainea
1.3. Accounting
1.4. Other Commands
1.5. CGRateS Failover
1.6. Dependencies
1.6.
1.7. Dependencies

1.6.1. OpenSIPS Modules
1.6.2. External Libraries or Applications
1.7.1. OpenSIPS Modules
1.7.2. External Libraries or Applications

1.7. Exported Parameters
1.8. Exported Parameters

1.7.1. cgrates_engine (string)
1.7.2. bind_ip (string)
1.7.3. max_async_connections (integer)
1.7.4. retry_timeout (integer)
1.8.1. cgrates_engine (string)
1.8.2. bind_ip (string)
1.8.3. max_async_connections (integer)
1.8.4. retry_timeout (integer)
1.8.5. compat_mode (integer)

1.8. Exported Functions
1.9. Exported Functions

1.8.1. cgrates_acc([flags[, account[, destination[,
1.9.1. cgrates_acc([flags[, account[, destination[,
session]]]])

1.8.2. cgrates_auth([account[, destination[,
1.9.2. cgrates_auth([account[, destination[,
session]]])

1.8.3. cgrates_cmd(command[, session])
1.9.3. cgrates_cmd(command[, session])

1.9. Exported pseudo-variables
1.10. Exported pseudo-variables

1.9.1. $cgr(name) / $(cgr(name)[session])
1.9.2. $cgrret
1.10.1. $cgr(name) / $(cgr(name)[session])
1.10.2. $cgr_opt(name) / $(cgr_opt(name)[session])
1.10.3. $cgrret

1.10. Exported Asynchronous Functions
1.11. Exported Asynchronous Functions

1.10.1. cgrates_auth([account[, destination[,
1.11.1. cgrates_auth([account[, destination[,
session]]])

1.10.2. cgrates_cmd(command[, session])
1.11.2. cgrates_cmd(command[, session])

List of Examples

1.1. Set cgrates_engine parameter
1.2. Set bind_ip parameter
1.3. Set max_async_connections parameter
1.4. Set retry_timeout parameter
1.5. cgrates_acc() usage
1.6. cgrates_auth() usage
1.7. cgrates_cmd() usage
1.8. $cgr(name) simple usage
1.9. $cgr(name) multiple sessions usage
1.10. $cgrret usage
1.11. async cgrates_auth usage
1.12. async cgrates_cmd usage
1.5. Set compat_mode parameter
1.6. cgrates_acc() usage
1.7. cgrates_auth() usage
1.8. cgrates_cmd() usage
1.9. $cgr(name) simple usage
1.10. $cgr(name) multiple sessions usage
1.11. $cgr_opt(name) usage
1.12. $cgrret usage
1.13. async cgrates_auth usage
1.14. async cgrates_cmd compat_mode usage
1.15. async cgrates_cmd new usage

Chapter 1. Admin Guide

Expand Down Expand Up @@ -160,7 +166,8 @@ Chapter 1. Admin Guide
The following example simulates the cgrates_auth() CGRateS
call:
...
$cgr(Tenant) = $fd;
$cgr_opt(Tenant) = $fd; # or $cgr(Tenant) = $fd; /* in c
ompat mode */
$cgr(Account) = $fU;
$cgr(OriginID) = $ci;
$cgr(SetupTime) = "" + $Ts;
Expand Down Expand Up @@ -189,22 +196,33 @@ Chapter 1. Admin Guide
enabled. Otherwise, the other engines are used, until none is
available and the command fails.

1.6. Dependencies
The module supports two different versions of CGRateS: the
compat_mode one, which works with pre-rc8 releases, and a new
one which works with the post-rc8 releases. The difference
between the two versions consist in the way the requests and
responses to and from CGRateS are built. In the
non-compat_mode/new version, a new variable, $cgr_opt(), is
available, and can be used to tune the request options. This
variable should not be used in compat_mode mode to avoid
abiguities, but if it is used, it behaves exactly as $cgr(). By
default compat_mode is disabled.

1.6.1. OpenSIPS Modules
1.7. Dependencies

1.7.1. OpenSIPS Modules

The following modules must be loaded before this module:
* dialog -- in case CGRateS accounting is used.

1.6.2. External Libraries or Applications
1.7.2. External Libraries or Applications

The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* libjson

1.7. Exported Parameters
1.8. Exported Parameters

1.7.1. cgrates_engine (string)
1.8.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,
Expand All @@ -221,7 +239,7 @@ modparam("cgrates", "cgrates_engine", "127.0.0.1")
modparam("cgrates", "cgrates_engine", "127.0.0.1:2013")
...

1.7.2. bind_ip (string)
1.8.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
Expand All @@ -235,7 +253,7 @@ modparam("cgrates", "cgrates_engine", "127.0.0.1:2013")
modparam("cgrates", "bind_ip", "10.0.0.100")
...

1.7.3. max_async_connections (integer)
1.8.3. max_async_connections (integer)

The maximum number of simultaneous asynchronous connections to
a CGRateS engine.
Expand All @@ -247,7 +265,7 @@ modparam("cgrates", "bind_ip", "10.0.0.100")
modparam("cgrates", "max_async_connections", 20)
...

1.7.4. retry_timeout (integer)
1.8.4. retry_timeout (integer)

The number of seconds after which a disabled connection/engine
is retried.
Expand All @@ -259,9 +277,21 @@ modparam("cgrates", "max_async_connections", 20)
modparam("cgrates", "retry_timeout", 120)
...

1.8. Exported Functions
1.8.5. compat_mode (integer)

Indicates whether OpenSIPS should use the old (compat_mode)
CGRateS version API (pre-rc8).

Default value is "false (0)".

1.8.1. cgrates_acc([flags[, account[, destination[, session]]]])
Example 1.5. Set compat_mode parameter
...
modparam("cgrates", "compat_mode", 1)
...

1.9. Exported Functions

1.9.1. cgrates_acc([flags[, account[, destination[, session]]]])

cgrates_acc() starts an accounting session on the CGRateS
engine for the current dialog. It also ends the session when
Expand Down Expand Up @@ -312,7 +342,7 @@ modparam("cgrates", "retry_timeout", 120)
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
BRANCH_ROUTE and LOCAL_ROUTE.

Example 1.5. cgrates_acc() usage
Example 1.6. cgrates_acc() usage
...
if (!has_totag()) {
...
Expand All @@ -322,7 +352,7 @@ modparam("cgrates", "retry_timeout", 120)
}
...

1.8.2. cgrates_auth([account[, destination[, session]]])
1.9.2. cgrates_auth([account[, destination[, session]]])

cgrates_auth() does call authorization through using the
CGRateS engine.
Expand Down Expand Up @@ -353,7 +383,7 @@ modparam("cgrates", "retry_timeout", 120)
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
BRANCH_ROUTE and LOCAL_ROUTE.

Example 1.6. cgrates_auth() usage
Example 1.7. cgrates_auth() usage
...
if (!has_totag()) {
...
Expand All @@ -365,7 +395,7 @@ modparam("cgrates", "retry_timeout", 120)
}
...

1.8.3. cgrates_cmd(command[, session])
1.9.3. cgrates_cmd(command[, session])

cgrates_cmd() can send arbitrary commands to the CGRateS
engine.
Expand All @@ -389,10 +419,10 @@ modparam("cgrates", "retry_timeout", 120)

This function can be used from any route.

Example 1.7. cgrates_cmd() usage
Example 1.8. cgrates_cmd() usage
...
# cgrates_auth("$fU", "$rU"); simulation
$cgr(Tenant) = $fd;
$cgr_opt(Tenant) = $fd;
$cgr(Account) = $fU;
$cgr(OriginID) = $ci;
$cgr(SetupTime) = "" + $Ts;
Expand All @@ -402,9 +432,9 @@ modparam("cgrates", "retry_timeout", 120)
xlog("Call is allowed to run $cgrret seconds\n");
...

1.9. Exported pseudo-variables
1.10. Exported pseudo-variables

1.9.1. $cgr(name) / $(cgr(name)[session])
1.10.1. $cgr(name) / $(cgr(name)[session])

Pseudo-variable used to set different parameters for the
CGRateS command. Each name-value pair will be encoded as a
Expand All @@ -424,12 +454,12 @@ modparam("cgrates", "retry_timeout", 120)
another. if the session tag does not exist, the default (no
name) one is used.

Example 1.8. $cgr(name) simple usage
Example 1.9. $cgr(name) simple usage
...
if (!has_totag()) {
...
$cgr(Tenant) = $fd; # set the From domain as a t
enant
$cgr_opt(Tenant) = $fd; # set the From domain as
a tenant
$cgr(RequestType) = "*prepaid"; # do prepaid acc
ounting
if (!cgrates_auth("$fU", "$rU")) {
Expand All @@ -439,13 +469,13 @@ ounting
}
...

Example 1.9. $cgr(name) multiple sessions usage
Example 1.10. $cgr(name) multiple sessions usage
...
if (!has_totag()) {
...
# first session - authorize the user
$cgr(Tenant) = $fd; # set the From domain as a t
enant
$cgr_opt(Tenant) = $fd; # set the From domain as
a tenant
$cgr(RequestType) = "*prepaid"; # do prepaid acc
ounting
if (!cgrates_auth("$fU", "$rU")) {
Expand All @@ -454,7 +484,7 @@ ounting
}

# second session - authorize the carrier
$(cgr(Tenant)[carrier]) = $td;
$(cgr_opt(Tenant)[carrier]) = $td;
$(cgr(RequestType)[carrier]) = "*postpaid";
if (!cgrates_auth("$tU", "$fU", "carrier")) {
# use a different carrier
Expand All @@ -468,19 +498,46 @@ ounting
}
...

1.9.2. $cgrret
1.10.2. $cgr_opt(name) / $(cgr_opt(name)[session])

Used to tune the request parameter of a CGRateS request when
used in non-compat_mode.

Note: for all request options integer values act as boolean
values: 0 disables the feature and 1(or different than 0 value)
enables it. String variables are passed just as they are set.

Possible values at the time the documentation was written:
* Tenant - tune CGRateS Tenant.
* GetAttributes - requests the account attributes from the
CGRateS DB.
* GetMaxUsage - request the maximum time the call is allowed
to run.
* GetSuppliers - request an array with all the suppliers for
that can terminate that call.

Example 1.11. $cgr_opt(name) usage
...
$cgr_opt(Tenant) = "cgrates.org";
$cgr_opt(GetMaxUsage) = 1; # also retrieve the max usage
if (!cgrates_auth("$fU", "$rU")) {
# call rejected
}
...

1.10.3. $cgrret

Returns the reply message of a CGRateS command in script.

Example 1.10. $cgrret usage
Example 1.12. $cgrret usage
...
cgrates_auth("$fU", "$rU");
xlog("Call is allowed to run $cgrret seconds\n");
...

1.10. Exported Asynchronous Functions
1.11. Exported Asynchronous Functions

1.10.1. cgrates_auth([account[, destination[, session]]])
1.11.1. cgrates_auth([account[, destination[, session]]])

Does the CGRateS authorization call in an asynchronous way.
Script execution is suspended until the CGRateS engine sends
Expand Down Expand Up @@ -509,7 +566,7 @@ ounting
headers, or it is not an initial INVITE.
* -5 - CGRateS returned an invalid message.

Example 1.11. async cgrates_auth usage
Example 1.13. async cgrates_auth usage
route {
...
async(cgrates_auth("$fU", "$rU"), auth_reply);
Expand All @@ -525,7 +582,7 @@ route [auth_reply]
...
}

1.10.2. cgrates_cmd(command[, session])
1.11.2. cgrates_cmd(command[, session])

Can run an arbitrary CGRateS command in an asynchronous way.
The execution is suspended until the CGRateS engine sends the
Expand All @@ -548,7 +605,7 @@ route [auth_reply]
* -3 - No suitable CGRateS server found. message type (not an
initial INVITE).

Example 1.12. async cgrates_cmd usage
Example 1.14. async cgrates_cmd compat_mode usage
route {
...
$cgr(Tenant) = $fd;
Expand All @@ -560,6 +617,29 @@ route {
async(cgrates_cmd("SMGenericV1.GetMaxUsage"), auth_reply);
}

route [auth_reply]
{
if ($rc < 0) {
xlog("Call not authorized: code=$cgrret!\n");
send_reply("403", "Forbidden");
exit;
}
...
}

Example 1.15. async cgrates_cmd new usage
route {
...
$cgr_opt(Tenant) = $fd;
$cgr(Account) = $fU;
$cgr(OriginID) = $ci;
$cgr(SetupTime) = "" + $Ts;
$cgr(RequestType) = "*prepaid";
$cgr(Destination) = $rU;
async(cgrates_cmd("SessionSv1.AuthorizeEventWithDigest"), auth_r
eply);
}

route [auth_reply]
{
if ($rc < 0) {
Expand Down

0 comments on commit 3419f93

Please sign in to comment.