call_control: docs - link to mailing list discussion about MI to RPC control
[sip-router] / src / modules / call_control / doc / call_control_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13   
14   <title>&adminguide;</title>
15   
16   <section id="call_control.overview">
17   <title>Overview</title>
18     <para>
19       This module allows one to limit the duration of calls and automatically
20       end them when they exceed the imposed limit. Its main use case is to
21       implement a prepaid system, but it can also be used to impose a global
22       limit on all calls processed by the proxy.
23     </para>
24   </section>
25   
26   <section>
27   <title>Description</title>
28     <para>
29       Callcontrol consists of 3 components:
30       <itemizedlist>
31         <listitem>
32           <para>The &kamailio; call_control module</para>
33         </listitem>
34         <listitem>
35           <para>
36             An external application called callcontrol which keeps track of
37             the calls that have a time limit and automatically ends them when
38             they exceed it. This application receives requests from &kamailio;
39             and makes requests to a rating engine (see below) to find out if
40             a call needs to be limited or not. When a call ends (or is ended)
41             it will also instruct the rating engine to debit the balance for
42             the caller with the consumed amount. The callcontrol application
43             is available from http://callcontrol.ag-projects.com/
44           </para>
45         </listitem>
46         <listitem>
47           <para>
48                         NOTE: At the moment the callcontrol application only supports the old
49                         <quote>MI</quote> interface for communication with &kamailio;. This
50                         interface is unfortunately not available anymore in &kamailio;. So
51                         this application cannot be used right now out of the box together
52                         with the call_control module. See the next link for possible
53                         solutions:
54                         <ulink url="https://lists.kamailio.org/pipermail/sr-users/2019-June/106056.html">
55                                 https://lists.kamailio.org/pipermail/sr-users/2019-June/106056.html</ulink>.
56           </para>
57         </listitem>
58         <listitem>
59           <para>
60             A rating engine that is used to calculate the time limit based on
61             the caller's credit and the destination price and to debit the
62             caller's balance after a call ends. This is available as part of
63             CDRTool from http://cdrtool.ag-projects.com/
64           </para>
65         </listitem>
66       </itemizedlist>
67     </para>
68
69     <para>
70       The callcontrol application runs on the same machine as &kamailio; and they
71       communicate over a filesystem socket, while the rating engine can run on
72       a different host and communicates with the callcontrol application using
73       a TCP connection.
74     </para>
75
76     <para>
77       Callcontrol is invoked by calling the call_control() function for the
78       initial INVITE of every call we want to apply a limit to. This will end
79       up as a request to the callcontrol application, which will interogate
80       the rating engine for a time limit for the given caller and destination.
81       The rating engine will determine if the destination has any associated
82       cost and if the caller has any credit limit and if so will return the
83       amount of time he is allowed to call that destination. Otherwise it will
84       indicate that there is no limit associated with the call. If there is a
85       limit, the callcontrol application will retain the session and attach
86       a timer to it that will expire after the given time causing it to call
87       back to &kamailio; with a request to end the dialog. If the rating engine
88       returns that there is no limit for the call, the session is discarded
89       by the callcontrol application and it will allow it to go proceed any
90       limit. An appropriate response is returned to the call_control module
91       that is then returned by the call_control() function call and allows
92       the script to make a decision based on the answer.
93     </para>
94   </section>
95
96   <section>
97   <title>Features</title>
98     <para>
99       <itemizedlist>
100         <listitem>
101           <para>
102             Very simple API consisting of a single function that needs to be
103             called once for the first INVITE of every call. The rest is done
104             automatically in the background using dialog callbacks.
105           </para>
106         </listitem>
107
108         <listitem>
109           <para>
110             Gracefully end dialogs when they exceed their time by triggering
111             a dlg_end_dlg request into the dialog module, that will generate
112             two BYE messages towards each endpoint, ending the call cleanly.
113           </para>
114         </listitem>
115
116         <listitem>
117           <para>
118             Allow parallel sessions using one balance per subscriber
119           </para>
120         </listitem>
121
122         <listitem>
123           <para>
124             Integrates with mediaproxy's ability to detect when a call does
125             timeout sending media and is closed. In this case the dlg_end_dlg
126             that is triggered by mediaproxy will end the callcontrol session
127             before it reaches the limit and consumes all the credit for a call
128             that died and didn't actually take place. For this mediaproxy has
129             to be used and it has to be started by engage_media_proxy() to be
130             able to keep track of the call's dialog and end it on timeout.
131           </para>
132           <para>
133             Even when mediaproxy is unable to end the dialog because it was
134             not started with engage_media_proxy(), the callcontrol application
135             is still able to detect calls that did timeout sending media, by
136             looking in the radius accounting records for entries recorded by
137             mediaproxy for calls that did timeout. These calls will also be
138             ended gracefully by the callcontrol application itself.
139           </para>
140         </listitem>
141       </itemizedlist>
142     </para>
143   </section>
144
145   <section>
146   <title>Dependencies</title>
147     <section>
148     <title>&kamailio; Modules</title>
149       <para>
150         The following modules must be loaded before this module:
151         <itemizedlist>
152           <listitem>
153             <para>
154               <emphasis>pv</emphasis> module
155             </para>
156           </listitem>
157           <listitem>
158             <para>
159               <emphasis>dialog</emphasis> module
160             </para>
161           </listitem>
162         </itemizedlist>
163       </para>
164     </section>
165
166     <section>
167     <title>External Libraries or Applications</title>
168       <para>
169         The following libraries or applications must be installed before
170         running &kamailio; with this module loaded:
171         <itemizedlist>
172           <listitem>
173             <para>
174               <emphasis>None</emphasis>.
175             </para>
176           </listitem>
177         </itemizedlist>
178       </para>
179     </section>
180   </section>
181   
182   <section>
183   <title>Exported parameters</title>
184     <section id="call_control.p.disable">
185     <title><varname>disable</varname> (int)</title>
186       <para>
187         Boolean flag that specifies if callcontrol should be disabled. This
188         is useful when you want to use the same &kamailio; configuration in
189         two different contexts, one using callcontrol, the other not. In the
190         case callcontrol is disabled, calls to the call_control() function
191         will return a code indicating that there is no limit associated with
192         the call, allowing the use of the same configuration without changes.
193       </para>
194
195       <para>
196         <emphasis>
197           Default value is <quote>0</quote>.
198         </emphasis>
199       </para>
200
201       <example>
202       <title>Setting the <varname>disable</varname> parameter</title>
203         <programlisting format="linespecific">
204 ...
205 modparam("call_control", "disable", 1)
206 ...
207         </programlisting>
208       </example>
209     </section>
210
211     <section id="call_control.p.socket_name">
212     <title><varname>socket_name</varname> (string)</title>
213       <para>
214         The path to the filesystem socket where the callcontrol
215         application listens for commands from the module.
216       </para>
217
218       <para>
219         <emphasis>
220           Default value is 
221             <quote>/var/run/callcontrol/socket</quote>.
222         </emphasis>
223       </para>
224
225       <example>
226       <title>Setting the <varname>socket_name</varname> parameter</title>
227         <programlisting format="linespecific">
228 ...
229 modparam("call_control", "socket_name", "/var/run/callcontrol/socket")
230 ...
231         </programlisting>
232       </example>
233     </section>
234
235     <section id="call_control.p.socket_time">
236     <title><varname>socket_timeout</varname> (int)</title>
237       <para>
238         How long time (in milliseconds) to wait for an answer from the
239         callcontrol application.
240       </para>
241
242       <para>
243         <emphasis>
244           Default value is <quote>500</quote> ms.
245         </emphasis>
246       </para>
247
248       <example>
249       <title>Setting the <varname>socket_timeout</varname> parameter</title>
250         <programlisting format="linespecific">
251 ...
252 modparam("call_control", "socket_timeout", 500)
253 ...
254         </programlisting>
255       </example>
256     </section>
257
258     <section id="call_control.p.signaling_ip_avp">
259     <title><varname>signaling_ip_avp</varname> (string)</title>
260       <para>
261         Specification of the AVP which holds the IP address from where
262         the SIP signaling originated. If this AVP is set it will be used
263         to get the signaling IP address, else the source IP address
264         from where the SIP message was received will be used.
265         This AVP is meant to be used in cases where there are more than
266         one proxy in the call setup path and the proxy that actually
267         starts callcontrol doesn't receive the SIP messages directly
268         from the UA and it cannot determine the NAT IP address from
269         where the signaling originated. In such a case attaching a
270         SIP header at the first proxy and then copying that header's
271         value into the signaling_ip_avp on the proxy that starts
272         callcontrol will allow it to get the correct NAT IP address
273         from where the SIP signaling originated.
274       </para>
275       
276       <para>
277         This is used by the rating engine which finds the rates to apply to a
278         call based on caller's SIP URI, caller's SIP domain or caller's IP
279         address (whichever yields a rate first, in this order).
280       </para>
281
282       <para>
283         <emphasis>
284           Default value is <quote>$avp(s:signaling_ip)</quote>.
285         </emphasis>
286       </para>
287
288       <example>
289       <title>Setting the <varname>signaling_ip_avp</varname> parameter</title>
290         <programlisting format="linespecific">
291 ...
292 modparam("call_control", "signaling_ip_avp", "$avp(s:signaling_ip)")
293 ...
294         </programlisting>
295       </example>
296     </section>
297
298     <section id="call_control.p.canonical_uri_avp">
299     <title><varname>canonical_uri_avp</varname> (string)</title>
300       <para>
301         Specification of the AVP which holds an optional application defined
302         canonical request URI. When this is set, it will be used as the
303         destination when computing the call price, otherwise the request URI
304         will be used. This is useful when the username of the ruri needs to
305         have a different, canonical form in the rating engine computation
306         than it has in the ruri.
307       </para>
308
309       <para>
310         <emphasis>
311           Default value is <quote>$avp(s:can_uri)</quote>.
312         </emphasis>
313       </para>
314
315       <example>
316       <title>Setting the <varname>canonical_uri_avp</varname> parameter</title>
317         <programlisting format="linespecific">
318 ...
319 modparam("call_control", "canonical_uri_avp", "$avp(s:can_uri)")
320 ...
321         </programlisting>
322       </example>
323     </section>
324
325     <section id="call_control.p.diverter_avp_id">
326     <title><varname>diverter_avp_id</varname> (string)</title>
327       <para>
328         Specification of the id of an integer AVP which holds an optional
329         application defined diverter SIP URI. When this is set, it will be
330         used by the rating engine as the billing party when finding the rates
331         to apply to a given call, otherwise, the caller's URI taken from the
332         From field will be used. When set, this AVP should contain a value in
333         the form <quote>user@domain</quote> (no sip: prefix should be used).
334       </para>
335       <para>
336         This is useful when a destination diverts a call, thus becoming the
337         new caller. In this case the billing party is the diverter and this
338         AVP should be set to it, to allow the rating engine to pick the right
339         rates for the call. For example, if A calls B and B diverts all its
340         calls unconditionally to C, then the diverter AVP should the set to
341         B's URI, because B is the billing party in the call not A after the
342         call was diverted.
343       </para>
344
345       <para>
346         <emphasis>
347           Default value is <quote>805</quote>.
348         </emphasis>
349       </para>
350
351       <example>
352       <title>Setting the <varname>diverter_avp_id</varname> parameter</title>
353         <programlisting format="linespecific">
354 ...
355 modparam("call_control", "diverter_avp_id", 805)
356
357 route {
358   ...
359   # alice@example.com is paying for this call
360   $avp(i:805) = "sip:alice@example.com";
361   ...
362 }
363 ...
364         </programlisting>
365       </example>
366     </section>
367   </section>
368
369   <section>
370   <title>Functions</title>
371     <section id="call_control.f.call_control">
372     <title><function moreinfo="none">call_control()</function></title>
373       <para>
374         Trigger the use of callcontrol for the dialog started by the INVITE
375         for which this function is called (the function should only be called
376         for the first INVITE of a call). Further in-dialog requests will be
377         processed automatically using internal bindings into the dialog state
378         machine, allowing callcontrol to update its internal state as the
379         dialog progresses, without any other intervention from the script.
380       </para>
381
382       <para>
383         This function should be called right before the message is sent out
384         using t_relay(), when all the request uri modifications are over and
385         a final destination has been determined.
386       </para>
387
388       <para>This function has the following return codes:</para>
389       <para>
390         <itemizedlist>
391         <listitem><para>
392           +2 - call has no limit
393         </para></listitem>
394         <listitem><para>
395           +1 - call has limit and is traced by callcontrol
396         </para></listitem>
397         <listitem><para>
398           -1 - not enough credit to make the call
399         </para></listitem>
400         <listitem><para>
401           -2 - call is locked by another call in progress
402         </para></listitem>
403         <listitem><para>
404           -5 - internal error (message parsing, communication, ...)
405         </para></listitem>
406         </itemizedlist>
407       </para>
408
409       <para>
410         This function can be used from REQUEST_ROUTE.
411       </para>
412
413       <example>
414       <title>Using the <function>call_control</function> function</title>
415         <programlisting format="linespecific">
416
417 ...
418 if (is_avp_set("$avp(i:805)")) {
419     # the diverter AVP is set, use it as billing party
420     $avp(s:billing_party_domain) = $(avp(i:805){uri.domain});
421 } else {
422     $avp(s:billing_party_domain) = $fd;
423 }
424
425 if (method==INVITE &amp;&amp; !has_totag() &amp;&amp;
426     is_domain_local("$avp(s:billing_party_domain)")) {
427     call_control();
428     switch ($retcode) {
429     case 2:
430         # Call with no limit
431     case 1:
432         # Call has limit and is under callcontrol management
433         break;
434     case -1:
435         # Not enough credit (prepaid call)
436         sl_send_reply("402", "Not enough credit");
437         exit;
438         break;
439     case -2:
440         # Locked by another call in progress (prepaid call)
441         sl_send_reply("403", "Call locked by another call in progress");
442         exit;
443         break;
444     default:
445         # Internal error (message parsing, communication, ...)
446         if (PREPAID_ACCOUNT) {
447             xlog("Call control: internal server error\n");
448             sl_send_reply("500", "Internal server error");
449             exit;
450         } else {
451             xlog("L_WARN", "Cannot set time limit for postpaid call\n");
452         }
453     }
454 }
455 t_relay();
456 ...
457         </programlisting>
458       </example>
459     </section>
460   </section>
461
462 </chapter>
463