<?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 "../../../../doc/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. It is an enhaced variant of ims_qos.</para>
  </section>

  <section>
    <title>Dependencies</title>

    <section>
      <title>&kamailio; Modules</title>

      <para>The Following modules must be loaded before this module:</para>

      <itemizedlist>
        <listitem>
          <para>removed dependency on IMS Dialog - since the ims_dialog is quite far behind dialog and lacking in features needed</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 module 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>FQDN of the Diameter server (typically a PCRF) to communicate
      with. If not set then realm routing is used. If you use this, the
      routing defined in your diameter xml configuration file (CDP) will be
      ignored and as a result you will lose the benefits of load balancing and
      failover. </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>
      <title><varname>authorize_video_flow</varname> (integer)</title>

      <para>This is a flag that specifies whether or not to authorize video flows.
      1 means video flows will be authorized over Rx and
      0 means video flows will not be authorized over Rx</para>

      <para><emphasis> Default value is 1. </emphasis></para>

      <example>
        <title><varname>authorize_video_flow</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "authorize_video_flow", 0)
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>cdp_event_list_size_threshold</varname> (integer)</title>

      <para>This is a threshold on the size of the cdp event list.  Once the
	queue exceeds this length a warning is logged.  0 disables this feature</para>

      <para><emphasis> Default value is 0. </emphasis></para>

      <example>
        <title><varname>cdp_event_list_size_threshold</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "cdp_event_list_size_threshold", 10)
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>audio_default_bandwidth</varname> (integer)</title>

      <para>This parameters defines the default bandwidth for Audio,
            if no "b=AS"-Parameter is found in the SDP.</para>

      <para><emphasis> Default value is 64 (64 kBit)</emphasis></para>

      <example>
        <title><varname>audio_default_bandwidth</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "audio_default_bandwidth", 32)
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>video_default_bandwidth</varname> (integer)</title>

      <para>This parameters defines the default bandwidth for Video,
            if no "b=AS"-Parameter is found in the SDP.</para>

      <para><emphasis> Default value is 128 (128 kBit)</emphasis></para>

      <example>
        <title><varname>video_default_bandwidth</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "video_default_bandwidth", 256)
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>early_qosrelease_reason</varname> (String)</title>

      <para>This sets the default Reason, when a call is terminated in
            early stage due to QoS-failure.</para>

      <para><emphasis> Default value is "QoS released", a call in early stage
		       would be released with "488 QoS released".</emphasis></para>

      <example>
        <title><varname>early_qosrelease_reason</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "early_qosrelease_reason", "Sorry - QoS failed")
...
        </programlisting>
      </example>
    </section>
    <section>
      <title><varname>confirmed_qosrelease_headers</varname> (String)</title>

      <para>These headers are added to the BYE-Message, when a confirmed call
	    is terminated due to a QoS failure.</para>

      <para><emphasis> Default value is "", no Extra-Headers</emphasis></para>

      <para><emphasis> The headers must end with CRLF.</emphasis></para>

      <example>
        <title><varname>confirmed_qosrelease_headers</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "confirmed_qosrelease_headers", "X-Reason: QoS failed\r\n")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>regex_sdp_ip_prefix_to_maintain_in_fd</varname> (String)</title>

      <para>The flow-description AVP is typically populated using IP:port information
          present in the SDP.  Certain (buggy) UEs can change ports midway during
          calls which causes the flow-description to no longer match the
          traffic.  This parameter allows the flow-description AVP to use to the
          any keyword instead of certain IP:port combinations in the SDP. The
          parameter is a regex that if set adds an extra filter for all IPs that do not match
          the regex with the any keyword in the flow-description AVP</para>

      <para><emphasis> Default value is "", no extra filters added</emphasis></para>

      <example>
        <title><varname>regex_sdp_ip_prefix_to_maintain_in_fd</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "regex_sdp_ip_prefix_to_maintain_in_fd", "10.21.0.1")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>terminate_dialog_on_rx_failure</varname> integer</title>

      <para>If set then active dialogs associated with an Rx session are
      torn down in the Rx session fails</para>

      <para><emphasis> Default value is 1, dialogs are torn down</emphasis></para>

      <example>
        <title><varname>terminate_dialog_on_rx_failure</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "terminate_dialog_on_rx_failure", 0)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>delete_contact_on_rx_failure</varname> integer</title>

      <para>If set then contacts associated with signalling Rx sessions are deleted
if the Rx session fails</para>

      <para><emphasis> Default value is 1, contacts are deleted</emphasis></para>

      <example>
        <title><varname>delete_contact_on_rx_failure</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "delete_contact_on_rx_failure", 0)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>include_rtcp_fd</varname> integer</title>

      <para>If set then a flow description is added for media flows - next available odd port
          is used as the default for RTCP traffic</para>

      <para><emphasis> Default value is 0, RTCP flow description not added</emphasis></para>

      <example>
        <title><varname>include_rtcp_fd</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "include_rtcp_fd", 1)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>media_type</varname> (String)</title>

      <para>Describe Media Type AVP(520) for AAR register</para>

      <para><emphasis> Default value is 'control'</emphasis></para>

      <example>
        <title><varname>media_type</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "media_type", "audio")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>flow_protocol</varname> (String)</title>

      <para>Describe Flow protocol for Flow-Description AVP (507). Used only for AAR register</para>

      <para><emphasis> Default value is 'IP'</emphasis></para>

      <example>
        <title><varname>flow_protocol</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "flow_protocol", "UDP")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>omit_flow_ports</varname> integer</title>

      <para>If set to 1 ommit ports for Flow-Description AVP (507). Used only for AAR register</para>

      <para><emphasis> Default value is 0, Add ports to Flow-Description AVP (507)</emphasis></para>

      <example>
        <title><varname>omit_flow_ports</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "omit_flow_ports", 1)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>rs_default_bandwidth</varname> integer</title>

      <para>Describe default RS-Bandwidth AVP(522) for AAR</para>

      <para><emphasis> Default value is 0</emphasis></para>

      <example>
        <title><varname>rs_default_bandwidth</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "rs_default_bandwidth", 600)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>rr_default_bandwidth</varname> integer</title>

      <para>Describe default RR-Bandwidth AVP(521) for AAR</para>

      <para><emphasis> Default value is 0</emphasis></para>

      <example>
        <title><varname>rr_default_bandwidth</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "rr_default_bandwidth", 2000)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>suspend_transaction</varname> integer</title>

      <para>If enabled, suspends the tm transaction while doing the AAR.</para>

      <para><emphasis> Default value is 1 (enabled)</emphasis></para>

      <example>
        <title><varname>suspend_transaction</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "suspend_transaction", 0)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>recv_mode</varname> integer</title>

	  <para>If set to 0, RX_AAR_Register() takes the received-from address values
	  (IP, port, proto) from the IP frame. If set to 1, it takes them from
      Via header. </para>

      <para><emphasis> Default value is 0</emphasis></para>

      <example>
        <title><varname>recv_mode</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "recv_mode", 1)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>dialog_direction</varname> integer</title>

	  <para>If set to 1, DLG_MOBILE_ORIGINATING is set to
	  rx_add_media_component_description_avp() instead of DLG_MOBILE_REGISTER
	  (which corresponds to value 3).
      </para>

      <para><emphasis> Default value is 3</emphasis></para>

      <example>
        <title><varname>dialog_direction</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "dialog_direction", 1)
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>trust_bottom_via</varname> (int)</title>
      <para>
        If set to 1 it will trust the bottom Via as the UE IP/port/transport when doing client identification.
      </para>
      <para>
        Normally, the UE identification should be done on IPsec SPIs and source IP/port of the packets.
        In some cases the ims_* modules trust the top Via on requests and the bottom Via on responses. In some (better)
        cases this trusts the received-from IP (or the alias in the Contact header).
      </para>
      <para>
        This parameter allows for an external-to-Kamailio IPsec functionality to be used. That will be in charge of
        guaranteeing that the bottom Via header is always correct (on requests; on responses the P-CSCF itself should
        guarantee unmodified Via headers stack). Then the code here will always use the bottom Via as the source of
        truth for IMS UE identification.
      </para>
      <para>
        <emphasis>Note:</emphasis> this will prefer the standard received and rport values, if present, over the actual
        Via sent-by host and port.
      </para>
      <para>
        <emphasis>Note:</emphasis> !! trusting the Via header has security drawbacks, as it might be easily spoofed by
        an attacker. Hence, without extra security, the P-CSCF shouldn't trust the Via header for client identification
        on requests and the ims_registrar_pcscf module would require a fix or extension for that. !!
      </para>
      <para>
        See also the same parameter in the ims_registrar_pcscf module.
      </para>
      <para><emphasis>Default value is 0 (trust received-from IP and alias in Contact, and, unfortunately somewhat wrongly
      top/bottom Via on requests/responses).</emphasis></para>
      <example>
        <title><varname>trust_bottom_via</varname> parameter usage</title>
        <programlisting format="linespecific">
...
modparam("ims_qos", "trust_bottom_via", 1)
...
        </programlisting>
      </example>
    </section>


    <section>
      <title><varname>af_signaling_ip</varname> (String)</title>

      <para>Set P-CSCF IPv4 address to generate the flows for the UE - PCSCF signaling path. Used only for AAR register, Flow-Description AVP (507)</para>

      <para><emphasis> Default value is 127.0.0.1</emphasis></para>

      <example>
        <title><varname>af_signaling_ip</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "af_signaling_ip", "192.0.2.1")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>af_signaling_ip6</varname> (String)</title>

      <para>Set P-CSCF IPv6 address to generate the flows for the UE - PCSCF signaling path. Used only for AAR register, Flow-Description AVP (507)</para>

      <para><emphasis> Default value is ""</emphasis></para>

      <example>
        <title><varname>af_signaling_ip6</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "af_signaling_ip6", "fc00:1234::1")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>af_signaling_port_pc</varname> (String)</title>

      <para>Set P-CSCF Port-PC port for the PCSCF - UE signaling path. Used only for AAR register, Flow-Description AVP (507)</para>

      <para><emphasis> Default value is 5062</emphasis></para>

      <example>
        <title><varname>af_signaling_port_pc</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "af_signaling_port_pc", "5062")
...
        </programlisting>
      </example>
    </section>

    <section>
      <title><varname>af_signaling_port_ps</varname> (String)</title>

      <para>Set P-CSCF Port-PS port for the UE - PCSCF signaling path. Used only for AAR register, Flow-Description AVP (507)</para>

      <para><emphasis> Default value is 5063</emphasis></para>

      <example>
        <title><varname>af_signaling_port_pc</varname> parameter
        usage</title>

        <programlisting format="linespecific">
...
modparam("ims_qos", "af_signaling_port_ps", "5063")
...
        </programlisting>
      </example>
    </section>

  </section>

  <section>
    <title>Functions</title>

    <section>
      <title><function moreinfo="none">Rx_AAR_Register(route_block, domain)</function></title>

      <para>Perform an AAR on Diameter RX interface to subscribe to signalling
      status. The purpose of this is tell a Diameter server (typically a
      PCRF) to inform the requesting Diameter client (us) 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>Route block to resume after async AAA Diameter reply.</para>
        </listitem>

        <listitem>
          <para><emphasis>domain</emphasis> that usrloc_pcscf uses to store
          user information.</para>
        </listitem>
      </itemizedlist>

      <para>Return codes:</para>
        <itemizedlist>
          <listitem>
            <para>
              <emphasis>-1</emphasis> - error: There was an error, so we must either ignore it (no subscription) or send 403 (depends on behaviour you want)
            </para>
            <para>
              <emphasis>0</emphasis> - Success: AAR-Request sent, reply is processed asynchronously.
            </para>
            <para>
              <emphasis>1</emphasis> - Success: No need to send AAR-Request, as a subscription still exists (continue as normal)
            </para>
          </listitem>
        </itemizedlist>


      <para>This function can be used from REQUEST_ROUTE.</para>

      <para><emphasis>Note:</emphasis> this is executed asynchronously. See example on how to
      retrieve return value</para>

      <para><emphasis>Note:</emphasis> this authorization session triggers
      event_route[qos:asr_registration], event_route[qos:rar_access_network] and event_route[qos:terminate_dialog].</para>

      <example>
        <title>Rx_AAR_Register</title>

        <programlisting format="linespecific">
...
if(Rx_AAR_Register("REGISTER_AAR_REPLY","location")==0){
    exit;
}
...
route[REGISTER_AAR_REPLY]
{
    switch ($avp(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(route_block,
      direction, subscription_id, subscription_id_type, kemi-cfg, rx_session_id)</function></title>

      <para>Perform an 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>Route block</emphasis> to resume after async AAR Diameter reply.</para>
        </listitem>

        <listitem>
          <para><emphasis>direction</emphasis> of this message -
          orig, term, etc.</para>
        </listitem>

        <listitem>
          <para><emphasis>subscription_id</emphasis> to hard code subscription ID for AAR.
          Used for some broken PCRFs.  Leave blank to use default</para>
        </listitem>

        <listitem>
          <para><emphasis>subscription_id_type</emphasis> to hard code subscription ID type
          for AAR. Only applicable if subscription_id is set. Set to -1 to use default.
          This is as per RFC 4006:
          END_USER_E164 0, END_USER_IMSI 1, END_USER_SIP_URI 2, END_USER_NAI 3,
          END_USER_PRIVATE 4</para>
        </listitem>

        <listitem>
          <para><emphasis>kemi-cfg</emphasis></para>
        </listitem>

        <listitem>
          <para><emphasis>rx_session_id</emphasis> Session-Id to reuse, or leave blank if
          this is the first AAR in the authorization session</para>
        </listitem>

      </itemizedlist>

      <para>This function can be used only from ONREPLY_ROUTE, only for replies to INVITE, UPDATE, PRACK.
      The reply and request must have SDP, for this function to work properly.</para>

      <para><emphasis>Note:</emphasis> this is executed asynchronously. See example on how to
      retrieve return value</para>

      <para><emphasis>Note:</emphasis> this authorization session triggers
      event_route[qos:asr_call], event_route[qos:rar_access_network] and event_route[qos:terminate_dialog].</para>


      <example>
        <title>Rx_AAR</title>

        <programlisting format="linespecific">
...
if(Rx_AAR("ORIG_SESSION_AAR_REPLY","orig","",-1,"")==0){
    exit;
}
...
route[ORIG_SESSION_AAR_REPLY]
{
    if ($avp(aar_return_code) != 1) {
        xlog("L_ERR", "IMS: AAR failed Orig\n");
        dlg_terminate("all", "Sorry no QoS available");
    } else {
        xlog("L_DBG", "Diameter: Orig AAR success on media authorization\n");
    }
}
...
</programlisting>
      </example>
    </section>


    <section>
      <title><function moreinfo="none">Rx_STR(route_block, rx_session_id)</function></title>

      <para>Perform an STR on Diameter RX interface to terminate an authorization session. For more
      details see 3GGP TS 29.214.</para>

      <para>Meaning of the parameters is as follows:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>route_block</emphasis> to resume after async STR Diameter reply.</para>
        </listitem>

        <listitem>
          <para><emphasis>rx_session_id</emphasis> Session-Id to terminate</para>
        </listitem>

      </itemizedlist>

      <para>This function can be used only from ONREPLY_ROUTE, only for replies to INVITE, UPDATE, PRACK.</para>

      <para><emphasis>Note:</emphasis> this is executed asynchronously. See example on how to
      retrieve return value</para>

      <example>
        <title>Rx_STR</title>

        <programlisting format="linespecific">
...
if(Rx_STR("STR_REPLY","$avp(RxSessionId)")==0){
    exit;
}
...
route[STR_REPLY]
{
    if ($avp(aar_return_code) != 1) {
        xlog("L_ERR", "IMS: STR failed\n");
    } else {
        xlog("L_DBG", "Diameter: STR success\n");
    }
}
...
</programlisting>
      </example>
    </section>


  </section>

  <section>
    <title>Statistics</title>

    <section>
      <title>AAR Timeouts (aar_timeouts)</title>

      <para>The number of timeouts on sending an 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>
