modules/ims_qos: new mod_param to add RTCP flow description for media flow
[sip-router] / modules / ims_qos / doc / ims_qos_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 <!-- Include general documentation entities -->
5 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
6 %docentities;
7 ]>
8 <!-- Auth_db Module User's Guide -->
9 <chapter>
10   <title>&adminguide;</title>
11
12   <section>
13     <title>Overview</title>
14
15     <para>This module contains all method related to the IMS policy and
16     charging control functions performed by an Application Function (e.g.
17     P-CSCF) over the Rx interface. This module is dependent on the CDP (C
18     Diameter Peer) modules for communicating with PCRF as specified in 3GPP
19     specification TS 29.214.</para>
20   </section>
21
22   <section>
23     <title>Dependencies</title>
24
25     <section>
26       <title>&kamailio; Modules</title>
27
28       <para>The Following mouldes must be loaded before this module:</para>
29
30       <itemizedlist>
31         <listitem>
32           <para>Dialog2</para>
33         </listitem>
34
35         <listitem>
36           <para>Usrloc PCSCF</para>
37         </listitem>
38
39         <listitem>
40           <para>TM - Transaction Manager</para>
41         </listitem>
42
43         <listitem>
44           <para>CDP - C Diameter Peer</para>
45         </listitem>
46
47         <listitem>
48           <para>CDP_AVP - CDP AVP Applications</para>
49         </listitem>
50       </itemizedlist>
51     </section>
52
53     <section>
54       <title>External Libraries or Applications</title>
55
56       <para>This modules requires the internal IMS library.</para>
57     </section>
58   </section>
59
60   <section>
61     <title>Parameters</title>
62
63     <section>
64       <title><varname>rx_dest_realm</varname> (string)</title>
65
66       <para>This is the name of the Diameter realm of the Diameter server
67       (typically a PCRF).</para>
68
69       <para><emphasis> Default value is 'ims.smilecoms.com'.
70       </emphasis></para>
71
72       <example>
73         <title><varname>rx_dest_realm</varname> parameter usage</title>
74
75         <programlisting format="linespecific">
76 ...
77 modparam("ims_qos", "rx_dest_realm", "ims.smilecoms.com")
78 ...
79         </programlisting>
80       </example>
81     </section>
82
83     <section>
84       <title><varname>rx_forced_peer</varname> (string)</title>
85
86       <para>FQDN of the Diameter server (typically a PCRF) to communicate
87       with. If not set then realm routing is used. If you use this, the
88       routing defined in your diameter xml configuration file (CDP) will be
89       ignored and as a result you will lose the benefits of load balancing and
90       failover. </para>
91
92       <para><emphasis> Default value is ''. </emphasis></para>
93
94       <example>
95         <title><varname>rx_forced_peer</varname> parameter usage</title>
96
97         <programlisting format="linespecific">
98 ...
99 modparam("ims_qos", "rx_forced_peer", "pcrf.ims.smilecoms.com")
100 ...
101         </programlisting>
102       </example>
103     </section>
104
105     <section>
106       <title><varname>rx_auth_expiry</varname> (integer)</title>
107
108       <para>This is the expiry length in seconds of the initiated Diameter
109       sessions.</para>
110
111       <para><emphasis> Default value is 7200. </emphasis></para>
112
113       <example>
114         <title><varname>rx_auth_expiry</varname> parameter usage</title>
115
116         <programlisting format="linespecific">
117 ...
118 modparam("ims_qos", "rx_auth_expiry", 14400)
119 ...
120         </programlisting>
121       </example>
122     </section>
123
124     <section>
125       <title><varname>cdp_event_latency</varname> (integer)</title>
126
127       <para>This is a flag to determine whether or slow CDP responses should
128       be reported in the log file. 1 is enabled and 0 is disabled.</para>
129
130       <para><emphasis> Default value is 1. </emphasis></para>
131
132       <example>
133         <title><varname>cdp_event_latency</varname> parameter usage</title>
134
135         <programlisting format="linespecific">
136 ...
137 modparam("ims_qos", "cdp_event_latency", 1)
138 ...
139         </programlisting>
140       </example>
141     </section>
142
143     <section>
144       <title><varname>cdp_event_threshold</varname> (integer)</title>
145
146       <para>This time in milliseconds is the limit we should report a CDP
147       response as slow. i.e. if a CDP response exceeds this limit it will be
148       reported in the log file. This is only relevant is cdp_event_latency is
149       enabled (set to 0).</para>
150
151       <para><emphasis> Default value is 500. </emphasis></para>
152
153       <example>
154         <title><varname>cdp_event_threshold</varname> parameter usage</title>
155
156         <programlisting format="linespecific">
157 ...
158 modparam("ims_qos", "cdp_event_threshold", 500)
159 ...
160         </programlisting>
161       </example>
162     </section>
163
164     <section>
165       <title><varname>cdp_event_latency_log</varname> (integer)</title>
166
167       <para>This time log level at which we should report slow CDP responses.
168       0 is ERROR, 1 is WARN, 2 is INFO and 3 is DEBUG. This is only relevant
169       is cdp_event_latency is enabled (set to 0)</para>
170
171       <para><emphasis> Default value is 0. </emphasis></para>
172
173       <example>
174         <title><varname>cdp_event_latency_log</varname> parameter
175         usage</title>
176
177         <programlisting format="linespecific">
178 ...
179 modparam("ims_qos", "cdp_event_latency_log", 1)
180 ...
181         </programlisting>
182       </example>
183     </section>
184     <section>
185       <title><varname>authorize_video_flow</varname> (integer)</title>
186
187       <para>This is a flag that specifies whether or not to authorize video flows.
188       1 means video flows will be authorized over Rx and
189       0 means video flows will not be authorized over Rx</para>
190
191       <para><emphasis> Default value is 1. </emphasis></para>
192
193       <example>
194         <title><varname>authorize_video_flow</varname> parameter
195         usage</title>
196
197         <programlisting format="linespecific">
198 ...
199 modparam("ims_qos", "authorize_video_flow", 0)
200 ...
201         </programlisting>
202       </example>
203     </section>
204     <section>
205       <title><varname>cdp_event_list_size_threshold</varname> (integer)</title>
206
207       <para>This is a threshold on the size of the cdp event list.  Once the
208         queue exceeds this length a warning is logged.  0 disables this feature</para>
209
210       <para><emphasis> Default value is 0. </emphasis></para>
211
212       <example>
213         <title><varname>cdp_event_list_size_threshold</varname> parameter
214         usage</title>
215
216         <programlisting format="linespecific">
217 ...
218 modparam("ims_qos", "cdp_event_list_size_threshold", 10)
219 ...
220         </programlisting>
221       </example>
222     </section>
223     <section>
224       <title><varname>audio_default_bandwidth</varname> (integer)</title>
225
226       <para>This parameters defines the default bandwidth for Audio,
227             if no "b=AS"-Parameter is found in the SDP.</para>
228
229       <para><emphasis> Default value is 64 (64 kBit)</emphasis></para>
230
231       <example>
232         <title><varname>audio_default_bandwidth</varname> parameter
233         usage</title>
234
235         <programlisting format="linespecific">
236 ...
237 modparam("ims_qos", "audio_default_bandwidth", 32)
238 ...
239         </programlisting>
240       </example>
241     </section>
242     <section>
243       <title><varname>video_default_bandwidth</varname> (integer)</title>
244
245       <para>This parameters defines the default bandwidth for Video,
246             if no "b=AS"-Parameter is found in the SDP.</para>
247
248       <para><emphasis> Default value is 128 (128 kBit)</emphasis></para>
249
250       <example>
251         <title><varname>video_default_bandwidth</varname> parameter
252         usage</title>
253
254         <programlisting format="linespecific">
255 ...
256 modparam("ims_qos", "video_default_bandwidth", 256)
257 ...
258         </programlisting>
259       </example>
260     </section>
261     <section>
262       <title><varname>early_qosrelease_reason</varname> (String)</title>
263
264       <para>This sets the default Reason, when a call is terminated in 
265             early stage due to QoS-failure.</para>
266
267       <para><emphasis> Default value is "QoS released", an call in early stage
268                        would be released with "488 QoS released".</emphasis></para>
269
270       <example>
271         <title><varname>early_qosrelease_reason</varname> parameter
272         usage</title>
273
274         <programlisting format="linespecific">
275 ...
276 modparam("ims_qos", "early_qosrelease_reason", "Sorry - QoS failed")
277 ...
278         </programlisting>
279       </example>
280     </section>
281     <section>
282       <title><varname>confirmed_qosrelease_headers</varname> (String)</title>
283
284       <para>These headers are added to the BYE-Message, when an confirmed call
285             is terminated due to a QoS failure.</para>
286
287       <para><emphasis> Default value is "", no Extra-Headers</emphasis></para>
288
289       <para><emphasis> The headers must end with CRLF.</emphasis></para>
290
291       <example>
292         <title><varname>confirmed_qosrelease_headers</varname> parameter
293         usage</title>
294
295         <programlisting format="linespecific">
296 ...
297 modparam("ims_qos", "confirmed_qosrelease_headers", "X-Reason: QoS failed\r\n")
298 ...
299         </programlisting>
300       </example>
301     </section>
302     
303     <section>
304       <title><varname>regex_sdp_ip_prefix_to_maintain_in_fd</varname> (String)</title>
305
306       <para>The flow-description AVP is typically populated using IP:port information
307           present in the SDP.  Certain (buggy) UEs can change ports midway during 
308           calls which causes the flow-description to no longer match the 
309           traffic.  This parameter allows the flow-description AVP to use to the 
310           any keyword instead of certain IP:port combinations in the SDP. The 
311           parameter is a regex that if set adds an extra filter for all IPs that do not match 
312           the regex with the any keyword in the flow-description AVP</para>
313
314       <para><emphasis> Default value is "", no extra filters added</emphasis></para>
315
316       <example>
317         <title><varname>regex_sdp_ip_prefix_to_maintain_in_fd</varname> parameter
318         usage</title>
319
320         <programlisting format="linespecific">
321 ...
322 modparam("ims_qos", "regex_sdp_ip_prefix_to_maintain_in_fd", "10.21.0.1")
323 ...
324         </programlisting>
325       </example>
326     </section>
327     
328     <section>
329       <title><varname>terminate_dialog_on_rx_failure</varname> integer</title>
330
331       <para>If set then active dialogs associated with an Rx session are
332       torn down in the Rx session fails</para>
333
334       <para><emphasis> Default value is 1, dialogs are torn down</emphasis></para>
335
336       <example>
337         <title><varname>terminate_dialog_on_rx_failure</varname> parameter
338         usage</title>
339
340         <programlisting format="linespecific">
341 ...
342 modparam("ims_qos", "terminate_dialog_on_rx_failure", 0)
343 ...
344         </programlisting>
345       </example>
346     </section>
347     
348     <section>
349       <title><varname>delete_contact_on_rx_failure</varname> integer</title>
350
351       <para>If set then contacts associated with signalling Rx sessions are deleted
352 if the Rx session fails</para>
353
354       <para><emphasis> Default value is 1, contacts are deleted</emphasis></para>
355
356       <example>
357         <title><varname>delete_contact_on_rx_failure</varname> parameter
358         usage</title>
359
360         <programlisting format="linespecific">
361 ...
362 modparam("ims_qos", "delete_contact_on_rx_failure", 0)
363 ...
364         </programlisting>
365       </example>
366     </section>
367     
368     <section>
369       <title><varname>include_rtcp_fd</varname> integer</title>
370
371       <para>If set then a flow description is added for media flows - next available odd port 
372           is used as the default for RTCP traffic</para>
373
374       <para><emphasis> Default value is 0, RTCP flow description not added</emphasis></para>
375
376       <example>
377         <title><varname>include_rtcp_fd</varname> parameter
378         usage</title>
379
380         <programlisting format="linespecific">
381 ...
382 modparam("ims_qos", "include_rtcp_fd", 1)
383 ...
384         </programlisting>
385       </example>
386     </section>
387     
388   </section>
389
390   <section>
391     <title>Functions</title>
392
393     <section>
394       <title><function moreinfo="none">Rx_AAR_Register(route_block,
395       domain)</function></title>
396
397       <para>Perform a AAR on Diameter RX interface to subscribe to signalling
398       status. This purpose of this is tell a Diameter server (typically a
399       PCRF) to inform the requesting Diameter client on changes to the status
400       of signalling bearer for the same framed IP address. For more details
401       see 3GGP TS 29.214.</para>
402
403       <para>Meaning of the parameters is as follows:</para>
404
405       <itemizedlist>
406         <listitem>
407           <para>Route block to resume after async UAR Diameter reply.</para>
408         </listitem>
409
410         <listitem>
411           <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store
412           user information.</para>
413         </listitem>
414       </itemizedlist>
415
416         <para>Return codes:</para>
417                 <itemizedlist>
418                 <listitem>
419                         <para>
420                         <emphasis>-1</emphasis> - error: There was an error, so we must either ignore it (no subscription) or send 403 (depends on behaviour you want)
421                         </para>
422                         <para>
423                         <emphasis>0</emphasis> - Success: AAR-Request sent, reply is processed asynchronously.
424                         </para>
425                         <para>
426                         <emphasis>1</emphasis> - Success: No need to send AAR-Request, as a subscription still exists (continue as normal)
427                         </para>
428                 </listitem>
429                 </itemizedlist>
430
431
432       <para>This function can be used from REQUEST_ROUTE.</para>
433
434       <para>p.s. this is executed asynchronously. See example on how to
435       retrieve return value</para>
436
437       <example>
438         <title>Rx_AAR_Register</title>
439
440         <programlisting format="linespecific">
441 ...
442 if(Rx_AAR_Register("REG_AAR_REPLY","location")==0){
443     exit;
444 }
445 ...
446 route[REG_AAR_REPLY]
447 {
448     switch ($avp(s:aar_return_code)) {
449         case 1:
450             xlog("L_DBG", "Diameter: AAR success on subscription to signalling\n");
451             break;
452         default:
453             xlog("L_ERR", "Diameter: AAR failed on subscription to signalling\n");
454             t_reply("403", "Can't register to QoS for signalling");
455             exit;
456     }
457 ...
458 </programlisting>
459       </example>
460     </section>
461
462     <section>
463       <title><function moreinfo="none">Rx_AAR(route_block,
464       direction, subscription_id, subscription_id_type)</function></title>
465
466       <para>Perform a AAR on Diameter RX interface to request resource
467       authorisation from a Diameter server (typically a PCRF). For more
468       details see 3GGP TS 29.214.</para>
469
470       <para>Meaning of the parameters is as follows:</para>
471
472       <itemizedlist>
473         <listitem>
474           <para><emphasis>Route block</emphasis> to resume after async UAR Diameter reply.</para>
475         </listitem>
476
477         <listitem>
478           <para><emphasis>direction</emphasis> of this message -
479           orig, term, etc.</para>
480         </listitem>
481         
482         <listitem>
483           <para><emphasis>subscription_id</emphasis> to hard code subscription ID for AAR.
484           Used for some broken PCRFs.  Leave blank to use default</para>
485         </listitem>
486         
487         <listitem>
488           <para><emphasis>subscription_id_type</emphasis> to hard code subscription ID type
489           for AAR. Only applicable if subscription_id is set. Set to -1 to use default.
490           This is as per RFC 4006: 
491           END_USER_E164 0, END_USER_IMSI 1, END_USER_SIP_URI 2, END_USER_NAI 3,
492           END_USER_PRIVATE 4</para>
493         </listitem>
494         </itemizedlist>
495
496       <para>This function can be used from REQUEST_ROUTE or
497       ONREPLY_ROUTE.</para>
498
499       <para>p.s. this is executed asynchronously. See example on how to
500       retrieve return value</para>
501
502       <example>
503         <title>Rx_AAR</title>
504
505         <programlisting format="linespecific">
506 ...
507 if(Rx_AAR("ORIG_SESSION_AAR_REPLY","orig","",-1)==0){
508     exit;
509 }
510 ...
511 route[ORIGN_SESSION_AAR_REPLY]
512 {
513     if ($avp(s:aar_return_code) != 1) {
514         xlog("L_ERR", "IMS: AAR failed Orig\n");
515         dlg_terminate("all", "Sorry no QoS available");
516     } else {
517         xlog("L_DBG", "Diameter: Orig AAR success on media authorization\n");
518     } 
519 }
520 ...
521 </programlisting>
522       </example>
523     </section>
524   </section>
525
526   <section>
527     <title>Statistics</title>
528
529     <section>
530       <title>AAR Timeouts (aar_timeouts)</title>
531
532       <para>The number of timeouts on sending a AAR. i.e. no response to
533       AAR.</para>
534     </section>
535
536     <section>
537       <title>Average AAR Response Time (aar_avg_response_time)</title>
538
539       <para>The average response time in milliseconds for AAR-AAA
540       transaction.</para>
541     </section>
542   </section>
543 </chapter>