name mode size
..
doc 040000
example 040000
Makefile 100644 1.19kB
README 100644 10.9kB
cnxcc.c 100644 1.15kB
cnxcc.h 100644 1.54kB
cnxcc_check.c 100644 7.21kB
cnxcc_check.h 100644 1.13kB
cnxcc_mod.c 100644 54.07kB
cnxcc_mod.h 100644 5.07kB
cnxcc_redis.c 100644 15.03kB
cnxcc_redis.h 100644 2.61kB
cnxcc_rpc.c 100644 6.92kB
cnxcc_rpc.h 100644 1.15kB
cnxcc_select.c 100644 1.75kB
cnxcc_select.h 100644 1.16kB
cnxcc_sip_msg_faker.c 100644 2.5kB
cnxcc_sip_msg_faker.h 100644 1.12kB
README
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, 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, 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, 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, cps, ipulse, fpulse) Associates the call with a customer id and sets the max credit, 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. The customer value can be provided as a string or a variable holding a string. The maxcredit and cps can be double (float) or integer values, they have to be provided as static string values of variables holding string values. The ipulse and fpulse values are integer values, they can be also given via variables holding integers. Return code: * 1 - successful * -1 - failed, error logged * -2 - failed, credit value is less than initial pulse value Example 1.3. cnxcc_set_max_credit() ... cnxcc_set_max_credit("john-doe", "100.5", "0.5", "20", "10"); ... $var(customer) = "john-doe-premium"; # customer id $var(credit) = "100"; # max credit $var(cps) = "2.00"; # cost per second $var(initial_p) = 30; # initial pulse $var(final_p) = 6; # final pulse cnxcc_set_max_credit("$var(customer)", "$var(credit)", "$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 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 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(cost_per_sec) = "0.5"; $var(i_pulse) = 30; $var(f_pulse) = 6; if (!cnxcc_set_max_credit("$var(client)", "$var(credit)", "$var(cost_per_sec)", "$var(i_pulse)", "$var(f_pulse)")) { xlog("Error setting up credit control"); } } event_route[cnxcc:call-shutdown] { xlog("L_INFO", "[$ci]: call killed"); } ...