Integration with Kamailio
Kamailio is an Open Source SIP Server released under GPL, able to handle thousands of call setups per second. Kamailio can be used to build large platforms for VoIP and realtime communications – presence, WebRTC, Instant messaging and other applications. Moreover, it can be easily used for scaling up SIP-to-PSTN gateways, PBX systems or media servers like Asterisk™, FreeSWITCH™ or SEMS.
Prerequisites
The integration repository contains everything we need for understanding the usage of Canyan Rating Engine with Kamailio.
The Makefile provides us with two shortcut commands:
make docker-start
and make docker-stop
.
Also there is a make test-kamailio
command that we will look at in a while to understand what is happening behind the scenes.
Scope
Integrating the authorization, begin and start transaction methods of the Rating Engine in a Kamailio instance. Kamailio needs to perform an authorization for every outgoing and incoming call, getting all the information needed to perform or not the calls. Also the begin and end of a call needs to be signalized to the Rating Engine.
The Rating Agent is listening for http requests with REST and GraphQL APIs. In Kamailio we will use the HTTP_ASYNC_CLIENT Module to avoid binding Kamailio workers with synchronous http calls.
Kamailio configuration
The integration repository contains an example configuration file for the integration with Canyan's Rating Engine.
Note: The Kamailio configuration file is simple and basic for the purpose of this tutorial and should not be used in production.
Authorization
Let's start with the authorization method of the Rating Engine. In the kamailio.cfg we can notice this piece of code:
if (is_method("INVITE") && !has_totag()) { route(RATING_AUTHORIZATION); }
The route RATING_AUTHORIZATION
is run for every new INVITE
method that does not have a to
tag.
RATING_AUTHORIZATION
prepares the json to be sent to the Rating Agent populating the following variables:
- transaction_tag (
$ci
) - account_tag (
$fU
) - source (
$fu
) - destination (
$tu
)
The route RATING_AUTHORIZATION_RESPONSE
is the most complex of the Canyan Rating Engine Kamailio integration routes.
It handles the response from the Agent to the authorization
endpoint request.
Let's break it down and see what it does.
The first check is performed on the response from the Agent module. It checks if the http response is 200 then it checks if the response contains the expected fields.
Then the max available units are set to a variable that will be used if the call is authorized to set the dialog timeout with dlg_set_timeout
.
The check of the unauthorized reasons is then performed to send the correct reply to the SIP client.
It there are no errors the prioritized carriers list is gathered from the authorization response and the list is parsed with the route RATING_AUTHORIZATION_PARSE_CARRIERS
.
At the end of the route the SIPOUT
route is called.
Begin Transaction
The route RATING_BEGIN_TRANSACTION
is called with the event route dialog:start.
The route prepares the following variables for the Rating Agent http async call:
- transaction_tag (
$ci
) - account_tag (
$fU
) - source (
$fu
) - destination (
$tu
)
Then the route RATING_BEGIN_TRANSACTION_RESPONSE
that handles the response from the Agent is doing some simple checks like http_ok
and if the http response code is 200. After that the check of the content of the response is performed and it consists in checking if the variable ok
is true.
If some of the checks are not good the route sends a 500 reply to che client with a message that the Rating is not available. The route also prints an xlog with alert log level and the http error.
End Transaction
The route RATING_END_TRANSACTION
sets the following variables to be sent to the Agent via http async call:
- transaction_tag (
$ci
) - account_tag (
$fU
) - source (
$var(query)
) - destination (
$var(query)
)
As for the Begin Transaction there is a simple RATING_END_TRANSACTION_RESPONSE
route that handles the response and checks the correct http response and the value of the ok
boolean variable inside the response body.
It sends SIP error replies and logs with alert log level the issue.
Testing
The integration repository contains also tests that can be run with a simple make test-kamailio
after the make docker-start
command. Plese refer to those tests to see how this implementation inside Kamailio is tested with Canyan Rating Engine.
The tests are run with the open source tool canyan-tester so refer to the documentation of that tool for better understanding the test process.