The IMS PCSCF-Registrar Module

Dragos Vingarzan

   FhG Fokus
   <Dragos.Vingarzan@fokus.fraunhofer.de>

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>

   Copyright © 2007 FhG FOKUS

   Copyright © 2012 Smile Communications

   Copyright © 2015 ng-voice 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. pcscf_uri (string)
              3.2. pending_reg_expires (int)
              3.3. received_avp (string)
              3.4. is_registered_fallback2ip (int)
              3.5. publish_reginfo (int)
              3.6. subscribe_to_reginfo (int)
              3.7. subscription_expires (int)
              3.8. ignore_contact_rxport_check (int)
              3.9. ignore_reg_state (int)
              3.10. force_icscf_uri (string)
              3.11. reginfo_queue_size_threshold (int)

        4. Functions

              4.1. pcscf_save(domain)
              4.2. pcscf_save_pending(domain)
              4.3. pcscf_follows_service_routes(domain)
              4.4. pcscf_force_service_routes(domain)
              4.5. pcscf_is_registered(domain)

   List of Examples

   1.1. pcscf_uri parameter usage
   1.2. pending_reg_expires parameter usage
   1.3. received_avp parameter usage
   1.4. is_registered_fallback2ip parameter usage
   1.5. publish_reginfo parameter usage
   1.6. subscribe_to_reginfo parameter usage
   1.7. subscription_expires parameter usage
   1.8. ignore_contact_rxport_check parameter usage
   1.9. ignore_reg_state parameter usage
   1.10. force_icscf_uri parameter usage
   1.11. reginfo_queue_size_threshold parameter usage
   1.12. pcscf_save

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. pcscf_uri (string)
        3.2. pending_reg_expires (int)
        3.3. received_avp (string)
        3.4. is_registered_fallback2ip (int)
        3.5. publish_reginfo (int)
        3.6. subscribe_to_reginfo (int)
        3.7. subscription_expires (int)
        3.8. ignore_contact_rxport_check (int)
        3.9. ignore_reg_state (int)
        3.10. force_icscf_uri (string)
        3.11. reginfo_queue_size_threshold (int)

   4. Functions

        4.1. pcscf_save(domain)
        4.2. pcscf_save_pending(domain)
        4.3. pcscf_follows_service_routes(domain)
        4.4. pcscf_force_service_routes(domain)
        4.5. pcscf_is_registered(domain)

1. Overview

   This module contains all methods related for usage of Kamailio as a
   Proxy-CSCF.

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:
     * Usrloc PCSCF
     * PUA - if reginfo is used.

2.2. External Libraries or Applications

   This module requires the internal IMS library.

3. Parameters

   3.1. pcscf_uri (string)
   3.2. pending_reg_expires (int)
   3.3. received_avp (string)
   3.4. is_registered_fallback2ip (int)
   3.5. publish_reginfo (int)
   3.6. subscribe_to_reginfo (int)
   3.7. subscription_expires (int)
   3.8. ignore_contact_rxport_check (int)
   3.9. ignore_reg_state (int)
   3.10. force_icscf_uri (string)
   3.11. reginfo_queue_size_threshold (int)

3.1. pcscf_uri (string)

   URI of this Proxy-CSCF.

   Example 1.1. pcscf_uri parameter usage
...
modparam("ims_registrar_pcscf", "pcscf_uri", "pcscf.mnc001.mcc001.3gppnetwork.or
g")
...

3.2. pending_reg_expires (int)

   How long (in seconds), until pending (uncomplete) Registrations expire

   Default value is 30.

   Example 1.2. pending_reg_expires parameter usage
...
modparam("ims_registrar_pcscf", "pending_reg_expires", 15)
...

3.3. received_avp (string)

   AVP, holding the received information (optional)

   Example 1.3. received_avp parameter usage
...
modparam("ims_registrar_pcscf", "received_avp", "$avp(i:42)")
...

3.4. is_registered_fallback2ip (int)

   Defines, whether a contact should be searched by its Contact: only or
   alternatively by the received IP-Address.

   The option may have the following values:
     * 0 Search by Contact-Header only
     * 1 Search by Contact-Header, if this fails, search by Received
       Information (IP, Port, Proto)
     * 2 Search by Received Information (IP, Port, Proto), if this fails,
       Search by Contact Header

   This Parameter is primarily used by the "is_registered" function.

   Default value is 0 (Contact only).

   Example 1.4. is_registered_fallback2ip parameter usage
...
modparam("ims_registrar_pcscf", "is_registered_fallback2ip", 2)
...

3.5. publish_reginfo (int)

   If set to "1", the module will send PUBLISH regarding changes of the
   registration (e.g. due to Rx-Information) towards the network core.

   Default value is 0 (Do not send PUBLISH).

   Example 1.5. publish_reginfo parameter usage
...
modparam("ims_registrar_pcscf", "publish_reginfo", 1)
...

3.6. subscribe_to_reginfo (int)

   If set to "1", the module will send a SUBSCRIBE for the registration
   status towards the network core.

   Default value is 0 (Do not send SUBSCRIBE).

   Example 1.6. subscribe_to_reginfo parameter usage
...
modparam("ims_registrar_pcscf", "subscribe_to_reginfo", 1)
...

3.7. subscription_expires (int)

   How long should the subscription of reg-info towards the packet-core be
   valid?

   Default value is 3600.

   Example 1.7. subscription_expires parameter usage
...
modparam("ims_registrar_pcscf", "subscription_expires", 7200)
...

3.8. ignore_contact_rxport_check (int)

   Validate, if the port, from which the request was received, is the same
   as used during registration.

   This Parameter is primarily used by the "is_registered" function.

   Default value is 0 (do not ignore Ports).

   Example 1.8. ignore_contact_rxport_check parameter usage
...
modparam("ims_registrar_pcscf", "ignore_contact_rxport_check", 1)
...

3.9. ignore_reg_state (int)

   Validate, if the found contact is really and completely registered.

   This Parameter is primarily used by the "is_registered" function.

   Default value is 0 (do not ignore registration state).

   Example 1.9. ignore_reg_state parameter usage
...
modparam("ims_registrar_pcscf", "ignore_reg_state", 1)
...

3.10. force_icscf_uri (string)

   Instead of doing a DNS-Lookup on the domain, always send the requests
   to a specific I-CSCF.

   Default value is not set, do the DNS-Lookup.

   Example 1.10. force_icscf_uri parameter usage
...
modparam("ims_registrar_pcscf", "force_icscf_uri", "sip:icscf.mnc001.mcc001.3gpp
network.org")
...

3.11. reginfo_queue_size_threshold (int)

   As reginfo operations are processed asynchronously, this parameter
   defines at what length of the queue, the length should be logged (in
   order to determine overload)

   Default value is 0 (do not log queue length).

   Example 1.11. reginfo_queue_size_threshold parameter usage
...
modparam("ims_registrar_pcscf", "reginfo_queue_size_threshold", 42)
...

4. Functions

   4.1. pcscf_save(domain)
   4.2. pcscf_save_pending(domain)
   4.3. pcscf_follows_service_routes(domain)
   4.4. pcscf_force_service_routes(domain)
   4.5. pcscf_is_registered(domain)

4.1. pcscf_save(domain)

   The function processes a reply to a REGISTER message. It can add,
   remove or modify location records (in usrloc) depending on Contact and
   Expires HFs in the REGISTER message.

   Meaning of the parameters is as follows:
     * domain - Logical domain within the registrar. If a database is used
       then this must be name of the table which stores the contacts.

   Example 1.12. pcscf_save
...
pcscf_save("location");
...

4.2. pcscf_save_pending(domain)

   Same as pcscf_save(), but it will store the registration in a "Pending"
   state.

   Meaning of the parameters is as follows:
     * domain - Logical domain within the registrar. If a database is used
       then this must be name of the table which stores the contacts.

   The return code may have the following values:
     * ( 1) OK
     * (-1) Parsing of contact data failed
     * (-2) Deregistration in progress

   For db_mode = DB_ONLY (3) setting for ims_usrloc_pcscf module modparam
   following logic is implemented:
     * To avoid race time conditions between a REREGISTER and the expiry
       handler state machine in the scscf an approach is chosen to refuse
       a REREGISTER in time window of 20 seconds after pcontact expiry on
       the pcscf (thus allowing expiry handling to finish). REREGISTER is
       refused in this scenario with return code -2.
     * In case a REREGISTER arrives at pcscf and the respective pcontact
       is expired longer than time window of 20 seconds registration also
       is refused with return code -2 and additionaly PUBLISH is sent to
       scscf with expiry = 0.
     * The rc -2 shall be handled in register.cfg script as follows:
       pcscf_save_pending("location");
       switch ($retcode) {
       case -1:
       .......
       case -2:
       send_reply("500", "Deregister in progress - Please try again");
       exit;
       break;
       }

4.3. pcscf_follows_service_routes(domain)

   Returns true, if the request is following the "learned" service-routes
   during registration.

   Meaning of the parameters is as follows:
     * domain - Logical domain within the registrar. If a database is used
       then this must be name of the table which stores the contacts.

4.4. pcscf_force_service_routes(domain)

   Remove existing route-headers and force the Service-Routes, that were
   learned during registration.

   Meaning of the parameters is as follows:
     * domain - Logical domain within the registrar. If a database is used
       then this must be name of the table which stores the contacts.

4.5. pcscf_is_registered(domain)

   Returns true, if the request is coming from a "registered" endpoint.

   Meaning of the parameters is as follows:
     * domain - Logical domain within the registrar. If a database is used
       then this must be name of the table which stores the contacts.
