modules/ims_qos: Added documentation

Added admin documentation and README for ims_qos module

modules/ims_qos/README

@@ -0,0 +1,282 @@
+The IMS QoS Module
+
+Dragos Vingarzan
+
+   FhG Fokus
+   <[email protected]>
+
+Jason Penton
+
+   Smile Communications
+   <[email protected]>
+
+Richard Good
+
+   Smile Communications
+   <[email protected]>
+
+   Copyright © 2007 FhG FOKUS
+
+   Copyright © 2012 Smile Communications
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. rx_dest_realm (string)
+              3.2. rx_forced_peer (string)
+              3.3. rx_auth_expiry (integer)
+              3.4. cdp_event_latency (integer)
+              3.5. cdp_event_threshold (integer)
+              3.6. cdp_event_latency_log (integer)
+
+        4. Functions
+
+              4.1. Rx_AAR_Register(domain)
+              4.2. Rx_AAR(domain)
+
+        5. Statistics
+
+              5.1. AAR Timeouts (aar_timeouts)
+              5.2. Average AAR Response Time (aar_avg_response_time)
+
+   List of Examples
+
+   1.1. rx_dest_realm parameter usage
+   1.2. rx_forced_peer parameter usage
+   1.3. rx_auth_expiry parameter usage
+   1.4. cdp_event_latency parameter usage
+   1.5. cdp_event_threshold parameter usage
+   1.6. cdp_event_latency_log parameter usage
+   1.7. Rx_AAR_Register
+   1.8. Rx_AAR
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. rx_dest_realm (string)
+        3.2. rx_forced_peer (string)
+        3.3. rx_auth_expiry (integer)
+        3.4. cdp_event_latency (integer)
+        3.5. cdp_event_threshold (integer)
+        3.6. cdp_event_latency_log (integer)
+
+   4. Functions
+
+        4.1. Rx_AAR_Register(domain)
+        4.2. Rx_AAR(domain)
+
+   5. Statistics
+
+        5.1. AAR Timeouts (aar_timeouts)
+        5.2. Average AAR Response Time (aar_avg_response_time)
+
+1. Overview
+
+   This module contains all method related to the IMS policy and charging
+   control functions performed by an Application Function (e.g. P-CSCF)
+   over the Rx interface. This module is dependent on the CDP (C Diameter
+   Peer) modules for communicating with PCRF as specified in 3GPP
+   specification TS 29.214.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The Following mouldes must be loaded before this module:
+     * Dialog2
+     * Usrloc PCSCF
+     * TM - Transaction Manager
+     * CDP - C Diameter Peer
+     * CDP_AVP - CDP AVP Applications
+
+2.2. External Libraries or Applications
+
+   This modules requires the internal IMS library.
+
+3. Parameters
+
+   3.1. rx_dest_realm (string)
+   3.2. rx_forced_peer (string)
+   3.3. rx_auth_expiry (integer)
+   3.4. cdp_event_latency (integer)
+   3.5. cdp_event_threshold (integer)
+   3.6. cdp_event_latency_log (integer)
+
+3.1. rx_dest_realm (string)
+
+   This is the name of the Diameter realm of the Diameter server
+   (typically a PCRF).
+
+   Default value is 'ims.smilecoms.com'.
+
+   Example 1.1. rx_dest_realm parameter usage
+...
+modparam("ims_qos", "rx_dest_realm", "ims.smilecoms.com")
+...
+
+3.2. rx_forced_peer (string)
+
+   This is the optional name of the origin host of the Diameter server
+   (typically a PCRF). If not set then realm routing is used.
+
+   Default value is ''.
+
+   Example 1.2. rx_forced_peer parameter usage
+...
+modparam("ims_qos", "rx_forced_peer", "pcrf.ims.smilecoms.com")
+...
+
+3.3. rx_auth_expiry (integer)
+
+   This is the expiry length in seconds of the initiated Diameter
+   sessions.
+
+   Default value is 7200.
+
+   Example 1.3. rx_auth_expiry parameter usage
+...
+modparam("ims_qos", "rx_auth_expiry", 14400)
+...
+
+3.4. cdp_event_latency (integer)
+
+   This is a flag to determine whether or slow CDP responses should be
+   reported in the log file. 1 is enabled and 0 is disabled.
+
+   Default value is 1.
+
+   Example 1.4. cdp_event_latency parameter usage
+...
+modparam("ims_qos", "cdp_event_latency", 1)
+...
+
+3.5. cdp_event_threshold (integer)
+
+   This time in milliseconds is the limit we should report a CDP response
+   as slow. i.e. if a CDP response exceeds this limit it will be reported
+   in the log file. This is only relevant is cdp_event_latency is enabled
+   (set to 0).
+
+   Default value is 500.
+
+   Example 1.5. cdp_event_threshold parameter usage
+...
+modparam("ims_qos", "cdp_event_threshold", 500)
+...
+
+3.6. cdp_event_latency_log (integer)
+
+   This time log level at which we should report slow CDP responses. 0 is
+   ERROR, 1 is WARN, 2 is INFO and 3 is DEBUG. This is only relevant is
+   cdp_event_latency is enabled (set to 0)
+
+   Default value is 0.
+
+   Example 1.6. cdp_event_latency_log parameter usage
+...
+modparam("ims_qos", "cdp_event_latency_log", 1)
+...
+
+4. Functions
+
+   4.1. Rx_AAR_Register(domain)
+   4.2. Rx_AAR(domain)
+
+4.1. Rx_AAR_Register(domain)
+
+   Perform a AAR on Diameter RX interface to subscribe to signalling
+   status. This purpose of this is tell a Diameter server (typically a
+   PCRF) to inform the requesting Diameter client on changes to the status
+   of signalling bearer for the same framed IP address. For more details
+   see 3GGP TS 29.214.
+
+   Meaning of the parameters is as follows:
+     * domain that usrloc_pcscf uses to store user information.
+
+   This function can be used from REQUEST_ROUTE.
+
+   p.s. this is executed asynchronously. See example on how to retrieve
+   return value
+
+   Example 1.7. Rx_AAR_Register
+...
+    Rx_AAR_Register("location");
+
+    switch ($avp(s:aar_return_code)) {
+        case 1:
+            xlog("L_DBG", "Diameter: AAR success on subscription to signalling\n
+");
+            break;
+        default:
+            xlog("L_ERR", "Diameter: AAR failed on subscription to signalling\n"
+);
+            t_reply("403", "Can't register to QoS for signalling");
+            exit;
+    }
+
+...
+
+4.2. Rx_AAR(domain)
+
+   Perform a AAR on Diameter RX interface to request resource
+   authorisation from a Diameter server (typically a PCRF). For more
+   details see 3GGP TS 29.214.
+
+   Meaning of the parameters is as follows:
+     * domain that usrloc_pcscf uses to store user information.
+
+   This function can be used from REQUEST_ROUTE or ONREPLY_ROUTE.
+
+   p.s. this is executed asynchronously. See example on how to retrieve
+   return value
+
+   Example 1.8. Rx_AAR
+...
+    Rx_AAR("location");
+
+    switch ($avp(s:aar_return_code)) {
+        case 1:
+            xlog("L_DBG", "Diameter: AAR success\n");
+            break;
+        default:
+            xlog("L_ERR", "Diameter: AAR failed\n");
+            t_reply("403", "QoS not authorized");
+            exit;
+    }
+
+...
+
+5. Statistics
+
+   5.1. AAR Timeouts (aar_timeouts)
+   5.2. Average AAR Response Time (aar_avg_response_time)
+
+5.1. AAR Timeouts (aar_timeouts)
+
+   The number of timeouts on sending a AAR. i.e. no response to AAR.
+
+5.2. Average AAR Response Time (aar_avg_response_time)
+
+   The average response time in milliseconds for AAR-AAA transaction.

modules/ims_qos/doc/Makefile

@@ -0,0 +1,4 @@
+docs = ims_qos.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module

modules/ims_qos/doc/ims_qos.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+]>
+<book>
+  <bookinfo>
+    <title>The IMS QoS Module</title>
+
+    <authorgroup>
+      <author>
+        <firstname>Dragos Vingarzan</firstname>
+
+        <surname/>
+
+        <affiliation>
+          <orgname>FhG Fokus</orgname>
+        </affiliation>
+
+        <email>[email protected]</email>
+      </author>
+
+      <author>
+        <firstname>Jason</firstname>
+
+        <surname>Penton</surname>
+
+        <affiliation>
+          <orgname>Smile Communications</orgname>
+        </affiliation>
+
+        <email>[email protected]</email>
+      </author>
+
+      <author>
+        <firstname>Richard</firstname>
+
+        <surname>Good</surname>
+        <affiliation>
+          <orgname>Smile Communications</orgname>
+        </affiliation>
+
+        <email>[email protected]</email>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2007</year>
+      <holder>FhG FOKUS</holder>
+    </copyright>
+
+    <copyright>
+      <year>2012</year>
+
+      <holder>Smile Communications</holder>
+    </copyright>
+  </bookinfo>
+
+  <toc/>
+
+  <xi:include href="ims_qos_admin.xml"
+              xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</book>

modules/ims_qos/doc/ims_qos_admin.xml

@@ -0,0 +1,305 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+]>
+<!-- Auth_db Module User's Guide -->
+<chapter>
+  <title>&adminguide;</title>
+
+  <section>
+    <title>Overview</title>
+
+    <para>This module contains all method related to the IMS policy and 
+    charging control functions performed by an Application Function (e.g. 
+    P-CSCF) over the Rx interface.  This module is dependent on the CDP (C 
+    Diameter Peer) modules for communicating with PCRF as specified in 3GPP 
+    specification TS 29.214.
+    </para>
+  </section>
+
+  <section>
+    <title>Dependencies</title>
+
+    <section>
+      <title>&kamailio; Modules</title>
+
+      <para>The Following mouldes must be loaded before this module:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Dialog2</para>
+        </listitem>
+          
+        <listitem>
+          <para>Usrloc PCSCF</para>
+        </listitem>
+          
+        <listitem>
+          <para>TM - Transaction Manager</para>
+        </listitem>
+
+        <listitem>
+          <para>CDP - C Diameter Peer</para>
+        </listitem>
+
+        <listitem>
+          <para>CDP_AVP - CDP AVP Applications</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section>
+      <title>External Libraries or Applications</title>
+
+      <para>This modules requires the internal IMS library.</para>
+    </section>
+  </section>
+
+  <section>
+    <title>Parameters</title>
+
+    <section>
+      <title><varname>rx_dest_realm</varname> (string)</title>
+
+      <para>This is the name of the Diameter realm of the Diameter server 
+      (typically a PCRF).</para>
+
+      <para><emphasis> Default value is 'ims.smilecoms.com'.
+      </emphasis></para>
+
+      <example>
+        <title><varname>rx_dest_realm</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "rx_dest_realm", "ims.smilecoms.com")
+...
+        </programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><varname>rx_forced_peer</varname> (string)</title>
+
+      <para>This is the optional name of the origin host of the Diameter server
+      (typically a PCRF).  If not set then realm routing is used.</para>
+
+      <para><emphasis> Default value is ''.
+      </emphasis></para>
+
+      <example>
+        <title><varname>rx_forced_peer</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "rx_forced_peer", "pcrf.ims.smilecoms.com")
+...
+        </programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><varname>rx_auth_expiry</varname> (integer)</title>
+
+      <para>This is the expiry length in seconds of the initiated 
+      Diameter sessions.</para>
+
+      <para><emphasis> Default value is 7200.
+      </emphasis></para>
+
+      <example>
+        <title><varname>rx_auth_expiry</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "rx_auth_expiry", 14400)
+...
+        </programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><varname>cdp_event_latency</varname> (integer)</title>
+
+      <para>This is a flag to determine whether or slow CDP responses should be 
+      reported in the log file. 1 is enabled and 0 is disabled.</para>
+
+      <para><emphasis> Default value is 1.
+      </emphasis></para>
+
+      <example>
+        <title><varname>cdp_event_latency</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "cdp_event_latency", 1)
+...
+        </programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><varname>cdp_event_threshold</varname> (integer)</title>
+
+      <para>This time in milliseconds is the limit we should report a CDP 
+      response as slow. i.e. if a CDP response exceeds this limit it will be 
+      reported in the log file.  This is only relevant is cdp_event_latency is 
+      enabled (set to 0).
+      </para>
+
+      <para><emphasis> Default value is 500.
+      </emphasis></para>
+
+      <example>
+        <title><varname>cdp_event_threshold</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "cdp_event_threshold", 500)
+...
+        </programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><varname>cdp_event_latency_log</varname> (integer)</title>
+
+      <para>This time log level at which we should report slow CDP responses. 
+          0 is ERROR, 1 is WARN, 2 is INFO and 3 is DEBUG. This is only 
+          relevant is cdp_event_latency is enabled (set to 0)
+      </para>
+
+      <para><emphasis> Default value is 0.
+      </emphasis></para>
+
+      <example>
+        <title><varname>cdp_event_latency_log</varname> parameter usage</title>
+
+        <programlisting format="linespecific">
+...
+modparam("ims_qos", "cdp_event_latency_log", 1)
+...
+        </programlisting>
+      </example>
+    </section>
+  
+  </section>
+
+  <section>
+    <title>Functions</title>
+
+    <section>
+      <title><function
+      moreinfo="none">Rx_AAR_Register(domain)</function></title>
+
+      <para>Perform a AAR on Diameter RX interface to subscribe to signalling 
+      status. This purpose of this is tell a Diameter server (typically a PCRF)
+      to inform the requesting Diameter client on changes to the status of 
+      signalling bearer for the same framed IP address.  For more details see
+      3GGP TS 29.214. </para>
+
+      <para>Meaning of the parameters is as follows:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store 
+          user information.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>This function can be used from REQUEST_ROUTE.</para>
+
+      <para>p.s. this is executed asynchronously. See example on how to
+      retrieve return value</para>
+
+      <example>
+        <title>Rx_AAR_Register</title>
+
+        <programlisting format="linespecific">
+...
+    Rx_AAR_Register("location");
+    
+    switch ($avp(s:aar_return_code)) {
+        case 1:
+            xlog("L_DBG", "Diameter: AAR success on subscription to signalling\n");
+            break;
+        default:
+            xlog("L_ERR", "Diameter: AAR failed on subscription to signalling\n");
+            t_reply("403", "Can't register to QoS for signalling");
+            exit;
+    }
+
+...
+</programlisting>
+      </example>
+    </section>
+    
+    <section>
+      <title><function
+      moreinfo="none">Rx_AAR(domain)</function></title>
+
+      <para>Perform a AAR on Diameter RX interface to request resource 
+      authorisation from a Diameter server (typically a PCRF). For more details 
+      see 3GGP TS 29.214. </para>
+      
+      <para>Meaning of the parameters is as follows:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store 
+          user information.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>This function can be used from REQUEST_ROUTE or ONREPLY_ROUTE.</para>
+
+      <para>p.s. this is executed asynchronously. See example on how to
+      retrieve return value</para>
+
+      <example>
+        <title>Rx_AAR</title>
+
+        <programlisting format="linespecific">
+...
+    Rx_AAR("location");
+    
+    switch ($avp(s:aar_return_code)) {
+        case 1:
+            xlog("L_DBG", "Diameter: AAR success\n");
+            break;
+        default:
+            xlog("L_ERR", "Diameter: AAR failed\n");
+            t_reply("403", "QoS not authorized");
+            exit;
+    }
+
+...
+</programlisting>
+      </example>
+    </section>
+
+    
+    
+   </section>
+
+  <section>
+    <title>Statistics</title>
+
+    <section>
+      <title>AAR Timeouts (aar_timeouts)</title>
+
+      <para>The number of timeouts on sending a AAR. i.e. no response to
+      AAR.</para>
+    </section>
+
+    <section>
+      <title>Average AAR Response Time (aar_avg_response_time)</title>
+
+      <para>The average response time in milliseconds for AAR-AAA
+      transaction.</para>
+    </section>
+  </section>
+</chapter>