cnxcc Module

Carlos Ruiz Díaz

   ConexionGroup S.A.

   Copyright © 2013 Carlos Ruiz Díaz, carlos.ruizdiaz@gmail.com

   Copyright © 2014 Carlos Ruiz Díaz, carlos@latamvoices.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Modules
              2.2. Libraries

        3. Parameters

              3.1. redis (integer)
              3.2. credit_check_period (integer)

        4. Functions

              4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps,
                      ipulse, fpulse)

              4.2. cnxcc_set_max_time(customer, maxtime)
              4.3. cnxcc_update_max_time(customer, maxtime)
              4.4. cnxcc_set_max_channel(customer, maxchan)
              4.5. cnxcc_terminate_all(customer)

        5. RPC Commands

              5.1. cnxcc.active_clients
              5.2. cnxcc.check_client
              5.3. cnxcc.kill_call
              5.4. cnxcc.stats

        6. Events
        7. Web Interface
        8. Sample Config

   List of Examples

   1.1. redis parameter
   1.2. credit_check_period parameter
   1.3. cnxcc_set_max_credit()
   1.4. cnxcc_set_max_time()
   1.5. cnxcc_update_max_time()
   1.6. cnxcc_set_max_channels()
   1.7. cnxcc_set_max_time()
   1.8. kamailio-cnxcc.cfg

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Modules
        2.2. Libraries

   3. Parameters

        3.1. redis (integer)
        3.2. credit_check_period (integer)

   4. Functions

        4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps,
                ipulse, fpulse)

        4.2. cnxcc_set_max_time(customer, maxtime)
        4.3. cnxcc_update_max_time(customer, maxtime)
        4.4. cnxcc_set_max_channel(customer, maxchan)
        4.5. cnxcc_terminate_all(customer)

   5. RPC Commands

        5.1. cnxcc.active_clients
        5.2. cnxcc.check_client
        5.3. cnxcc.kill_call
        5.4. cnxcc.stats

   6. Events
   7. Web Interface
   8. Sample Config

1. Overview

   This module was designed to act as a mechanism to limit call duration
   based on credit information parameters. After getting the credit
   information of the call being set up, you can instruct the module to
   start monitoring the consumed credit to shutdown a single call or a
   group of calls in case of credit exhaustion.

   Every call is associated to an unique client/customer identifier. If a
   credit event occurs, all calls hooked to this identifier are
   automatically shutdown.

   Cnxcc is dialog-aware so there's no need to explicitly
   allocate/deallocate the monitoring. Only a single function call inside
   the script is needed upon reception of the INVITE.

   The credit discount rate is proportional to the number of calls grouped
   inside an identifier. Once the setup of the first call is done, the
   information remains while the call is active. If the customer starts a
   new call with the same routing criteria, it will land in the same
   monitoring bag and it will consume the same pool of credit in rates
   that are equal to the cost per second of both calls.

   If your accounting program does not maintain the state of the call in
   real time, this module can provide you with that ability.

   Cnxcc can also provide more common means of monitoring, i.e., by time
   limit or by maximum simultaneous calls.

2. Dependencies

   2.1. Modules
   2.2. Libraries

2.1. Modules

   The following module must be loaded before this module:
     * dialog

2.2. Libraries

   The following module must be loaded before this module:
     * hiredis-devel >= 0.11.0
     * libevent-devel >= 2.0.18-2

3. Parameters

   3.1. redis (integer)
   3.2. credit_check_period (integer)

3.1. redis (integer)

   Redis datasource connection information

   Example 1.1. redis parameter
...
modparam("cnxcc", "redis", "addr=127.0.0.1;port=6379;db=1")
...

3.2. credit_check_period (integer)

   Indicates how often the credit checking function should be called. It
   is directly related to the precision of the module. The maximum
   precision is 1, which means that every call is checked every one
   second.

   Values greater than 1 leads to precision lost but less CPU consumption.

   Example 1.2. credit_check_period parameter
...
modparam("cnxcc", "credit_check_period", 1)
...

4. Functions

   4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps, ipulse,
          fpulse)

   4.2. cnxcc_set_max_time(customer, maxtime)
   4.3. cnxcc_update_max_time(customer, maxtime)
   4.4. cnxcc_set_max_channel(customer, maxchan)
   4.5. cnxcc_terminate_all(customer)

4.1.  cnxcc_set_max_credit(customer, maxcredit, connect, cps, ipulse, fpulse)

   Associates the call with a customer id and sets the max credit, connect
   cost, cost per second, initial pulse and final pulse. The discount is
   calculated in pulses (1/1, 60/1, etc) and subtracted from the pool of
   credit.

   The customer value can be provided as a string or a variable holding a
   string. This value identifies all calls from the same customer.

   The maxcredit (float) value is the maximum credit available for the
   current call.

   The connect (float) value is the connect cost for the current call.

   The cps (float) value is the cost per second for the current call.

   The ipuse (integer) value is the initial pulse and establishes the
   minimum time to be charged. For example, value 1 establishes a charge
   per second and value 60 sets a charge per minute. If it is taken as
   value 60, even if the duration is 5 seconds, 1 minute will be charged.

   The fpulse (integer) value is the final pulse and establishes, from the
   initial pulse, the time range to be charged. For example, the value 1
   establishes a charge per second, 5 sets a charge in blocks of 5
   seconds, 60 sets a full minute charge.

   1/1 will make a charge per seconds for the entire call. 60/1 will make
   a charge per seconds with the first full minute. 60/60 always perform a
   full minute charge.

   Return code:
     * 1 - successful
     * -1 - failed, error logged
     * -4 - call-id already present for this client

   Example 1.3. cnxcc_set_max_credit()
...
cnxcc_set_max_credit("john-doe", "100", "3.0", "0.5", 60, 1);
...
$var(customer)  = "john-doe"; # customer id
$var(credit)    = "100";      # max credit for all calls with the same
                              # customer id
$var(connect)   = "3.0";      # connect cost or initial cost for the call
$var(cps)       = "0.5";      # cost per second
$var(initial_p) = 60;         # initial pulse (60 = the first minute will be
                              # charged even if the call is shorter)
$var(final_p)   = 1;          # final pulse (after the first minute, it will
                              # be charge in ranges of 1 second)
cnxcc_set_max_credit("$var(customer)", "$var(credit)", "$var(connect)",
        "$var(cps)", "$var(initial_p)", "$var(final_p)");
...

4.2.  cnxcc_set_max_time(customer, maxtime)

   Specifies the amount of time the call should last at most.

   The customer value can be provided as a string or a variable holding a
   string.

   The maxtime value is an integer values, it can be also given via a
   variable holding an integer.

   Return code:
     * 1 - successful
     * -1 - failed, error logged
     * -4 - call-id already present for this client

   Example 1.4. cnxcc_set_max_time()
...
$var(customer) = "john-doe-basic";
$var(max_time) = 120;
cnxcc_set_max_time("$var(customer)", "$var(max_time)");
...

4.3.  cnxcc_update_max_time(customer, maxtime)

   Updates max-time of an established and monitored call. This can be used
   to grant minimum values and to update them every short periods on time
   as a mean to prevent frauds and/or to mimic requested/granted units of
   time of Credit Control Application behavior.

   The customer value can be provided as a string or a variable holding a
   string.

   The maxtime value is an integer values, it can be also given via a
   variable holding an integer.

   Return code:
     * 1 - successful
     * -1 - failed, error logged

   Example 1.5. cnxcc_update_max_time()
...
$var(client)       = "john-doe-basic";
$var(update_time)  = 5;

if (!cnxcc_update_max_time("$var(client)", "$var(update_time)")) {
        xlog("Error updating max-time");
        return;
        }
...

4.4.  cnxcc_set_max_channel(customer, maxchan)

   Specifies a limit for the number of simultaneous calls.

   The customer value can be provided as a string or a variable holding a
   string.

   The maxchan value is an integer values, it can be also given via a
   variable holding an integer.

   Return code:
     * 1 - successful
     * -1 - failed, error logged
     * -2 - failed, calls established plus calls being established result
       in more than the limit you specified
     * -3 - failed, number of calls established is more than the limit you
       specified
     * -4 - call-id already present for this client

   Example 1.6. cnxcc_set_max_channels()
...
$var(customer)  = "john-doe-123-basic";
$var(max_chan)  = 2;
$var(retcode)   = cnxcc_set_max_channels("$var(customer)", "$var(max_chan)");

if ($var(retcode) == -1) {
        xlog("Error setting up credit control");
        return;
}

if ($var(retcode) < -1) {
        xlog("Too many channels for customer");
        sl_send_reply(403, "Forbidden");

        if (!cnxcc_terminate_all("$var(customer)")) {
                xlog("Error terminating customer's calls");
        }

        exit;
}
...

4.5.  cnxcc_terminate_all(customer)

   Terminates all calls of the specified customer/profile.

   The customer value can be provided as a string or a variable holding a
   string.

   Return code:
     * 1 - successful
     * -1 - failed, error logged

   Example 1.7. cnxcc_set_max_time()
...
$var(customer)  = "john-doe-123-basic";

if (!cnxcc_terminate_all("$var(customer)")) {
        xlog("Error terminating customer's calls");
}
...

5. RPC Commands

   5.1. cnxcc.active_clients
   5.2. cnxcc.check_client
   5.3. cnxcc.kill_call
   5.4. cnxcc.stats

5.1. cnxcc.active_clients

   Retrieves all calls grouped by their identifiers.

   Parameters: none

   Example:
...
kamcmd cnxcc.active_clients
...

5.2. cnxcc.check_client

   Retrives all calls from a particular identifier.

   Parameters: client/customer identifier

   Example:
...
kamcmd cnxcc.check_client john-doe-premium
...

5.3. cnxcc.kill_call

   Kills an active call using its call ID.

   Parameters: Call-ID

   Example:
....
kamcmd cnxcc.kill_call test@carlosrdcnx-laptop.site
...

5.4. cnxcc.stats

   List credit control stats.

   Parameters: none

   Example:
...
kamcmd cnxcc.stats
...

6. Events

   When a call is forced to end an event route is automatically invoked.
   This route is suited with a fake OPTIONS message containing the call
   ID, ftag and ttag of the original call so it can be located somehow in
   the accounting database.

   Example:
...
event_route[cnxcc:call-shutdown]
{
        xlog("L_INFO", "[$ci]: call killed");

        # perform some kind of notification, database update, email sending, etc
.
}
...

7. Web Interface

   The module contains a web management interface completely optional.
   With it, you can review your calls in real time and hang them up if
   necessary.

   Link: https://github.com/caruizdiaz/cnxcc-web

8. Sample Config

   Example 1.8. kamailio-cnxcc.cfg
...
route[CNXCC]
{
        $var(client)              = "test-client";
        $var(credit)              = "50";
        $var(connect_cost)        = "3.0";
        $var(cost_per_sec)        = "0.5";
        $var(i_pulse)             = 30;
        $var(f_pulse)             = 6;


        cnxcc_set_max_credit("$var(client)",
                        "$var(credit)",
                        "$var(connect_cost)",
                        "$var(cost_per_sec)",
                        "$var(i_pulse)",
                        "$var(f_pulse)");

        switch ($?) {
                case -1:
                        xerr("Error setting up credit control");
                        sl_send_reply("503", "Internal Server Error");
                case -4:
                        xwarn("$ci already present for client $var(client)");
        };
}

event_route[cnxcc:call-shutdown]
{
        xlog("L_INFO", "[$ci]: call killed");
}
...