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