src/modules/cnxcc/README
96596e28
 cnxcc Module
 
c587ce0b
 Carlos Ruiz Díaz
96596e28
 
0efe5a4d
    ConexionGroup S.A.
96596e28
 
d73ce5b7
 Edited by
 
 Jose Luis Verdeguer
 
    Zoon Suite
    <verdeguer@zoonsuite.com>
 
c587ce0b
    Copyright © 2013 Carlos Ruiz Díaz, carlos.ruizdiaz@gmail.com
 
    Copyright © 2014 Carlos Ruiz Díaz, carlos@latamvoices.com
d73ce5b7
 
    Copyright © 2018 Jose Luis Verdeguer
96596e28
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Modules
c587ce0b
               2.2. Libraries
96596e28
 
         3. Parameters
 
c587ce0b
               3.1. redis (integer)
96596e28
               3.2. credit_check_period (integer)
 
         4. Functions
 
d73ce5b7
               4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps,
                       ipulse, fpulse)
b34a31a6
 
               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)
96596e28
 
c0b36f62
         5. RPC Commands
96596e28
 
               5.1. cnxcc.active_clients
               5.2. cnxcc.check_client
               5.3. cnxcc.kill_call
c0b36f62
               5.4. cnxcc.stats
96596e28
 
         6. Events
         7. Web Interface
ae7e19fa
         8. Sample Config
96596e28
 
    List of Examples
 
b34a31a6
    1.1. redis parameter
    1.2. credit_check_period parameter
96596e28
    1.3. cnxcc_set_max_credit()
    1.4. cnxcc_set_max_time()
0efe5a4d
    1.5. cnxcc_update_max_time()
    1.6. cnxcc_set_max_channels()
    1.7. cnxcc_set_max_time()
    1.8. kamailio-cnxcc.cfg
96596e28
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Modules
c587ce0b
         2.2. Libraries
96596e28
 
    3. Parameters
 
c587ce0b
         3.1. redis (integer)
96596e28
         3.2. credit_check_period (integer)
 
    4. Functions
 
d73ce5b7
         4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps,
                 ipulse, fpulse)
b34a31a6
 
         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)
96596e28
 
c0b36f62
    5. RPC Commands
96596e28
 
         5.1. cnxcc.active_clients
         5.2. cnxcc.check_client
         5.3. cnxcc.kill_call
c0b36f62
         5.4. cnxcc.stats
96596e28
 
    6. Events
    7. Web Interface
ae7e19fa
    8. Sample Config
96596e28
 
 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
c587ce0b
    real time, this module can provide you with that ability.
96596e28
 
0efe5a4d
    Cnxcc can also provide more common means of monitoring, i.e., by time
    limit or by maximum simultaneous calls.
 
96596e28
 2. Dependencies
 
    2.1. Modules
c587ce0b
    2.2. Libraries
96596e28
 
 2.1. Modules
 
    The following module must be loaded before this module:
      * dialog
 
c587ce0b
 2.2. Libraries
 
    The following module must be loaded before this module:
      * hiredis-devel >= 0.11.0
      * libevent-devel >= 2.0.18-2
 
96596e28
 3. Parameters
 
c587ce0b
    3.1. redis (integer)
96596e28
    3.2. credit_check_period (integer)
 
ae7e19fa
 3.1. redis (integer)
96596e28
 
c587ce0b
    Redis datasource connection information
96596e28
 
b34a31a6
    Example 1.1. redis parameter
96596e28
 ...
c587ce0b
 modparam("cnxcc", "redis", "addr=127.0.0.1;port=6379;db=1")
96596e28
 ...
 
 3.2. credit_check_period (integer)
 
    Indicates how often the credit checking function should be called. It
8868e624
    is directly related to the precision of the module. The maximum
96596e28
    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.
 
b34a31a6
    Example 1.2. credit_check_period parameter
96596e28
 ...
 modparam("cnxcc", "credit_check_period", 1)
 ...
 
 4. Functions
 
d73ce5b7
    4.1. cnxcc_set_max_credit(customer, maxcredit, connect, cps, ipulse,
           fpulse)
 
b34a31a6
    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)
 
d73ce5b7
 4.1.  cnxcc_set_max_credit(customer, maxcredit, connect, cps, ipulse, fpulse)
b34a31a6
 
d73ce5b7
    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 (30/6, 1/1, etc) and subtracted from the pool of
    credit.
96596e28
 
b34a31a6
    The customer value can be provided as a string or a variable holding a
    string.
96596e28
 
d73ce5b7
    The maxcredit, connect and cps can be double (float) or integer values,
    they have to be provided as static string values of variables holding
    string values.
b34a31a6
 
    The ipulse and fpulse values are integer values, they can be also given
    via variables holding integers.
96596e28
 
    Return code:
      * 1 - successful
      * -1 - failed, error logged
0efe5a4d
      * -2 - failed, credit value is less than initial pulse value
96596e28
 
    Example 1.3. cnxcc_set_max_credit()
 ...
d73ce5b7
 cnxcc_set_max_credit("john-doe", "100", "3.0", "0.5", 60, 1);
b34a31a6
 ...
d73ce5b7
 $var(customer)  = "john-doe-premium"; # customer id
 $var(credit)    = "100";  # max credit
 $var(connect)   = "3.0";  # connect const
 $var(cps)       = "0.5";  # cost per second
 $var(initial_p) = 60;     # initial pulse
 $var(final_p)   = 1;      # final pulse
 cnxcc_set_max_credit("$var(customer)", "$var(credit)", "$var(connect)",
         "$var(cps)", "$var(initial_p)", "$var(final_p)");
96596e28
 ...
 
b34a31a6
 4.2.  cnxcc_set_max_time(customer, maxtime)
96596e28
 
    Specifies the amount of time the call should last at most.
 
b34a31a6
    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.
 
96596e28
    Return code:
      * 1 - successful
      * -1 - failed, error logged
 
    Example 1.4. cnxcc_set_max_time()
 ...
b34a31a6
 $var(customer) = "john-doe-basic";
96596e28
 $var(max_time) = 120;
0efe5a4d
 cnxcc_set_max_time("$var(customer)", "$var(max_time)");
 ...
 
b34a31a6
 4.3.  cnxcc_update_max_time(customer, maxtime)
0efe5a4d
 
    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.
 
b34a31a6
    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.
 
0efe5a4d
    Return code:
      * 1 - successful
      * -1 - failed, error logged
 
    Example 1.5. cnxcc_update_max_time()
 ...
b34a31a6
 $var(client)       = "john-doe-basic";
 $var(update_time)  = 5;
0efe5a4d
 
b34a31a6
 if (!cnxcc_update_max_time("$var(client)", "$var(update_time)")) {
         xlog("Error updating max-time");
         return;
0efe5a4d
         }
 ...
 
b34a31a6
 4.4.  cnxcc_set_max_channel(customer, maxchan)
0efe5a4d
 
b34a31a6
    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.
0efe5a4d
 
    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
 
    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;
 }
 ...
 
b34a31a6
 4.5.  cnxcc_terminate_all(customer)
 
    Terminates all calls of the specified customer/profile.
0efe5a4d
 
b34a31a6
    The customer value can be provided as a string or a variable holding a
    string.
0efe5a4d
 
    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");
 }
96596e28
 ...
 
c0b36f62
 5. RPC Commands
96596e28
 
    5.1. cnxcc.active_clients
    5.2. cnxcc.check_client
    5.3. cnxcc.kill_call
c0b36f62
    5.4. cnxcc.stats
96596e28
 
 5.1. cnxcc.active_clients
 
    Retrieves all calls grouped by their identifiers.
 
    Parameters: none
 
    Example:
b34a31a6
 ...
 kamcmd cnxcc.active_clients
 ...
96596e28
 
 5.2. cnxcc.check_client
 
    Retrives all calls from a particular identifier.
 
    Parameters: client/customer identifier
 
    Example:
b34a31a6
 ...
 kamcmd cnxcc.check_client john-doe-premium
 ...
96596e28
 
 5.3. cnxcc.kill_call
 
    Kills an active call using its call ID.
 
    Parameters: Call-ID
 
    Example:
b34a31a6
 ....
 kamcmd cnxcc.kill_call test@carlosrdcnx-laptop.site
 ...
96596e28
 
c0b36f62
 5.4. cnxcc.stats
 
    List credit control stats.
 
    Parameters: none
 
    Example:
b34a31a6
 ...
 kamcmd cnxcc.stats
 ...
c0b36f62
 
96596e28
 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
 
ae7e19fa
 8. Sample Config
96596e28
 
0efe5a4d
    Example 1.8. kamailio-cnxcc.cfg
96596e28
 ...
 route[CNXCC]
 {
b34a31a6
         $var(client)              = "test-client";
96596e28
         $var(credit)              = "50";
56e5e6a8
         $var(connect_cost)        = "3.0";
96596e28
         $var(cost_per_sec)        = "0.5";
b34a31a6
         $var(i_pulse)             = 30;
         $var(f_pulse)             = 6;
96596e28
 
         if (!cnxcc_set_max_credit("$var(client)",
b34a31a6
                         "$var(credit)",
56e5e6a8
                         "$var(connect_cost)",
b34a31a6
                         "$var(cost_per_sec)",
                         "$var(i_pulse)",
                         "$var(f_pulse)")) {
                 xlog("Error setting up credit control");
96596e28
         }
 }
 
 event_route[cnxcc:call-shutdown]
 {
         xlog("L_INFO", "[$ci]: call killed");
 }
 ...