The IMS QoS Module

Dragos Vingarzan

   Core Network Dynamics (ex FhG Fokus)
   <dragos@corenetdynamics.com>

Jason Penton

   Smile Communications
   <jason.penton@smilecoms.com>

Richard Good

   Smile Communications
   <richard.good@smilecoms.com>

Carsten Bock

   ng-voice GmbH
   <carsten@ng-voice.com>

Dragos Vingarzan

   <vingarzan -at- gmail dot com>

   Copyright © 2007 FhG FOKUS

   Copyright © 2012 Smile Communications

   Copyright © 2015 ng-voice GmbH

   Copyright © 2016 Core Network Dynamics GmbH
     __________________________________________________________________

   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)
              3.7. authorize_video_flow (integer)
              3.8. cdp_event_list_size_threshold (integer)
              3.9. audio_default_bandwidth (integer)
              3.10. video_default_bandwidth (integer)
              3.11. early_qosrelease_reason (String)
              3.12. confirmed_qosrelease_headers (String)
              3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String)
              3.14. terminate_dialog_on_rx_failure integer
              3.15. delete_contact_on_rx_failure integer
              3.16. include_rtcp_fd integer
              3.17. af_signaling_ip (String)
              3.18. af_signaling_ip6 (String)
              3.19. media_type (String)
              3.20. flow_protocol (String)
              3.21. omit_flow_ports integer
              3.22. rs_default_bandwidth integer
              3.23. rr_default_bandwidth integer
              3.24. suspend_transaction integer
              3.25. recv_mode integer
              3.26. dialog_direction integer
              3.27. trust_bottom_via (int)

        4. Functions

              4.1. Rx_AAR_Register(route_block, domain)
              4.2. Rx_AAR(route_block, direction, subscription_id,
                      subscription_id_type)

        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. authorize_video_flow parameter usage
   1.8. cdp_event_list_size_threshold parameter usage
   1.9. audio_default_bandwidth parameter usage
   1.10. video_default_bandwidth parameter usage
   1.11. early_qosrelease_reason parameter usage
   1.12. confirmed_qosrelease_headers parameter usage
   1.13. regex_sdp_ip_prefix_to_maintain_in_fd parameter usage
   1.14. terminate_dialog_on_rx_failure parameter usage
   1.15. delete_contact_on_rx_failure parameter usage
   1.16. include_rtcp_fd parameter usage
   1.17. af_signaling_ip parameter usage
   1.18. af_signaling_ip6 parameter usage
   1.19. media_type parameter usage
   1.20. flow_protocol parameter usage
   1.21. omit_flow_ports parameter usage
   1.22. rs_default_bandwidth parameter usage
   1.23. rr_default_bandwidth parameter usage
   1.24. suspend_transaction parameter usage
   1.25. recv_mode parameter usage
   1.26. dialog_direction parameter usage
   1.27. trust_bottom_via parameter usage
   1.28. Rx_AAR_Register
   1.29. 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)
        3.7. authorize_video_flow (integer)
        3.8. cdp_event_list_size_threshold (integer)
        3.9. audio_default_bandwidth (integer)
        3.10. video_default_bandwidth (integer)
        3.11. early_qosrelease_reason (String)
        3.12. confirmed_qosrelease_headers (String)
        3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String)
        3.14. terminate_dialog_on_rx_failure integer
        3.15. delete_contact_on_rx_failure integer
        3.16. include_rtcp_fd integer
        3.17. af_signaling_ip (String)
        3.18. af_signaling_ip6 (String)
        3.19. media_type (String)
        3.20. flow_protocol (String)
        3.21. omit_flow_ports integer
        3.22. rs_default_bandwidth integer
        3.23. rr_default_bandwidth integer
        3.24. suspend_transaction integer
        3.25. recv_mode integer
        3.26. dialog_direction integer
        3.27. trust_bottom_via (int)

   4. Functions

        4.1. Rx_AAR_Register(route_block, domain)
        4.2. Rx_AAR(route_block, direction, subscription_id,
                subscription_id_type)

   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 modules must be loaded before this module:
     * IMS Dialog
     * Usrloc PCSCF
     * TM - Transaction Manager
     * CDP - C Diameter Peer
     * CDP_AVP - CDP AVP Applications

2.2. External Libraries or Applications

   This module 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.7. authorize_video_flow (integer)
   3.8. cdp_event_list_size_threshold (integer)
   3.9. audio_default_bandwidth (integer)
   3.10. video_default_bandwidth (integer)
   3.11. early_qosrelease_reason (String)
   3.12. confirmed_qosrelease_headers (String)
   3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String)
   3.14. terminate_dialog_on_rx_failure integer
   3.15. delete_contact_on_rx_failure integer
   3.16. include_rtcp_fd integer
   3.17. af_signaling_ip (String)
   3.18. af_signaling_ip6 (String)
   3.19. media_type (String)
   3.20. flow_protocol (String)
   3.21. omit_flow_ports integer
   3.22. rs_default_bandwidth integer
   3.23. rr_default_bandwidth integer
   3.24. suspend_transaction integer
   3.25. recv_mode integer
   3.26. dialog_direction integer
   3.27. trust_bottom_via (int)

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)

   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.

   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)
...

3.7. authorize_video_flow (integer)

   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

   Default value is 1.

   Example 1.7. authorize_video_flow parameter usage
...
modparam("ims_qos", "authorize_video_flow", 0)
...

3.8. cdp_event_list_size_threshold (integer)

   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

   Default value is 0.

   Example 1.8. cdp_event_list_size_threshold parameter usage
...
modparam("ims_qos", "cdp_event_list_size_threshold", 10)
...

3.9. audio_default_bandwidth (integer)

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

   Default value is 64 (64 kBit)

   Example 1.9. audio_default_bandwidth parameter usage
...
modparam("ims_qos", "audio_default_bandwidth", 32)
...

3.10. video_default_bandwidth (integer)

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

   Default value is 128 (128 kBit)

   Example 1.10. video_default_bandwidth parameter usage
...
modparam("ims_qos", "video_default_bandwidth", 256)
...

3.11. early_qosrelease_reason (String)

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

   Default value is "QoS released", a call in early stage would be
   released with "488 QoS released".

   Example 1.11. early_qosrelease_reason parameter usage
...
modparam("ims_qos", "early_qosrelease_reason", "Sorry - QoS failed")
...

3.12. confirmed_qosrelease_headers (String)

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

   Default value is "", no Extra-Headers

   The headers must end with CRLF.

   Example 1.12. confirmed_qosrelease_headers parameter usage
...
modparam("ims_qos", "confirmed_qosrelease_headers", "X-Reason: QoS failed\r\n")
...

3.13. regex_sdp_ip_prefix_to_maintain_in_fd (String)

   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

   Default value is "", no extra filters added

   Example 1.13. regex_sdp_ip_prefix_to_maintain_in_fd parameter usage
...
modparam("ims_qos", "regex_sdp_ip_prefix_to_maintain_in_fd", "10.21.0.1")
...

3.14. terminate_dialog_on_rx_failure integer

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

   Default value is 1, dialogs are torn down

   Example 1.14. terminate_dialog_on_rx_failure parameter usage
...
modparam("ims_qos", "terminate_dialog_on_rx_failure", 0)
...

3.15. delete_contact_on_rx_failure integer

   If set then contacts associated with signalling Rx sessions are deleted
   if the Rx session fails

   Default value is 1, contacts are deleted

   Example 1.15. delete_contact_on_rx_failure parameter usage
...
modparam("ims_qos", "delete_contact_on_rx_failure", 0)
...

3.16. include_rtcp_fd integer

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

   Default value is 0, RTCP flow description not added

   Example 1.16. include_rtcp_fd parameter usage
...
modparam("ims_qos", "include_rtcp_fd", 1)
...

3.17. af_signaling_ip (String)

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

   Default value is 127.0.0.1

   Example 1.17. af_signaling_ip parameter usage
...
modparam("ims_qos", "af_signaling_ip", "127.0.0.1")
...

3.18. af_signaling_ip6 (String)

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

   Default value is ""

   Example 1.18. af_signaling_ip6 parameter usage
...
modparam("ims_qos", "af_signaling_ip6", "fd16::205:2dee:ce4a:ab22")
...

3.19. media_type (String)

   Describe Media Type AVP(520) for AAR register

   Default value is 'control'

   Example 1.19. media_type parameter usage
...
modparam("ims_qos", "media_type", "audio")
...

3.20. flow_protocol (String)

   Describe Flow protocol for Flow-Description AVP (507). Used only for
   AAR register

   Default value is 'IP'

   Example 1.20. flow_protocol parameter usage
...
modparam("ims_qos", "flow_protocol", "UDP")
...

3.21. omit_flow_ports integer

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

   Default value is 0, Add ports to Flow-Description AVP (507)

   Example 1.21. omit_flow_ports parameter usage
...
modparam("ims_qos", "omit_flow_ports", 1)
...

3.22. rs_default_bandwidth integer

   Describe default RS-Bandwidth AVP(522) for AAR

   Default value is 0

   Example 1.22. rs_default_bandwidth parameter usage
...
modparam("ims_qos", "rs_default_bandwidth", 600)
...

3.23. rr_default_bandwidth integer

   Describe default RR-Bandwidth AVP(521) for AAR

   Default value is 0

   Example 1.23. rr_default_bandwidth parameter usage
...
modparam("ims_qos", "rr_default_bandwidth", 2000)
...

3.24. suspend_transaction integer

   If enabled, suspends the tm transaction while doing the AAR.

   Default value is 1 (enabled)

   Example 1.24. suspend_transaction parameter usage
...
modparam("ims_qos", "suspend_transaction", 0)
...

3.25. recv_mode integer

   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.

   Default value is 0

   Example 1.25. recv_mode parameter usage
...
modparam("ims_qos", "recv_mode", 1)
...

3.26. dialog_direction integer

   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).

   Default value is 3

   Example 1.26. dialog_direction parameter usage
...
modparam("ims_qos", "dialog_direction", 1)
...

3.27. trust_bottom_via (int)

   If set to 1 it will trust the bottom Via as the UE IP/port/transport
   when doing client identification.

   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).

   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.

   Note: this will prefer the standard received and rport values, if
   present, over the actual Via sent-by host and port.

   Note: !! 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. !!

   See also the same parameter in the ims_registrar_pcscf module.

   Default value is 0 (trust received-from IP and alias in Contact, and,
   unfortunately somewhat wrongly top/bottom Via on requests/responses).

   Example 1.27. trust_bottom_via parameter usage
...
modparam("ims_qos", "trust_bottom_via", 1)
...

4. Functions

   4.1. Rx_AAR_Register(route_block, domain)
   4.2. Rx_AAR(route_block, direction, subscription_id,
          subscription_id_type)

4.1. Rx_AAR_Register(route_block, domain)

   Perform an 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:
     * Route block to resume after async UAR Diameter reply.
     * domain that usrloc_pcscf uses to store user information.

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

   This function can be used from REQUEST_ROUTE.

   p.s. this is executed asynchronously. See example on how to retrieve
   return value

   Example 1.28. Rx_AAR_Register
...
if(Rx_AAR_Register("REG_AAR_REPLY","location")==0){
    exit;
}
...
route[REG_AAR_REPLY]
{
    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(route_block, direction, subscription_id, subscription_id_type)

   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.

   Meaning of the parameters is as follows:
     * Route block to resume after async UAR Diameter reply.
     * direction of this message - orig, term, etc.
     * subscription_id to hard code subscription ID for AAR. Used for some
       broken PCRFs. Leave blank to use default
     * subscription_id_type 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

   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.

   p.s. this is executed asynchronously. See example on how to retrieve
   return value

   Example 1.29. Rx_AAR
...
if(Rx_AAR("ORIG_SESSION_AAR_REPLY","orig","",-1)==0){
    exit;
}
...
route[ORIGN_SESSION_AAR_REPLY]
{
    if ($avp(s: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");
    }
}
...

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 an 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.
