IMS Usrloc PCSCF Module

Jason Penton

   Smile Communications

Edited by

Richard Good

   Smile Communications

Carsten Bock

   ng-voice GmbH

   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. hash_size (int)
              3.2. timer_interval (int)
              3.3. db_url (string)
              3.4. db_mode (int)
              3.5. match_contact_host_port (int)
              3.6. expires_grace (int)
              3.7. audit_expired_pcontacts_interval (int)
              3.8. audit_expired_pcontacts_timeout (int)

        4. RPC Commands

              4.1. ulpcscf.status

        5. Statistics

              5.1. registered contacts
              5.2. impus
              5.3. expired contacts

   2. Frequently Asked Questions

   List of Examples

   1.1. Set hash_size parameter
   1.2. Set timer_interval parameter
   1.3. Set db_url parameter
   1.4. Set db_mode parameter
   1.5. Set match_contact_host_port parameter
   1.6. Set expires_grace parameter
   1.7. Set audit_expired_pcontacts_interval parameter
   1.8. Set audit_expired_pcontacts_timeout parameter

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. hash_size (int)
        3.2. timer_interval (int)
        3.3. db_url (string)
        3.4. db_mode (int)
        3.5. match_contact_host_port (int)
        3.6. expires_grace (int)
        3.7. audit_expired_pcontacts_interval (int)
        3.8. audit_expired_pcontacts_timeout (int)

   4. RPC Commands

        4.1. ulpcscf.status

   5. Statistics

        5.1. registered contacts
        5.2. impus
        5.3. expired contacts

1. Overview

   This module serves as a storage engine for PCSCF contacts, much like
   the standard Kamailio module, usrloc, is a storage engine for standard
   SIP contacts. The concept of a contact in IMS, PCSCF specifically, is
   very different to that of std. SIP and as a result we have built this
   new module. A lot of the design has been borrowed from the std. usrloc
   module. For example. An IMS contact, in PCSCF, needs things like:

     * Diameter Rx session for signalling bearer status. i.e. this is
       effectively QoS from the network to make sure the signalling link
       can be 'trusted'
     * IPSEC Security Association for secure signalling between UE and
       PCSCF (first point of contact)
     * IMPU, each contact can have a number of associated public
       identities (IMPU).

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:
     * None.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. hash_size (int)
   3.2. timer_interval (int)
   3.3. db_url (string)
   3.4. db_mode (int)
   3.5. match_contact_host_port (int)
   3.6. expires_grace (int)
   3.7. audit_expired_pcontacts_interval (int)
   3.8. audit_expired_pcontacts_timeout (int)

3.1. hash_size (int)

   The number of entries of the hash table used by to store the contact
   records is 2^hash_size. For hash_size=4, the number of entries of the
   hash table is 16.

   Default value is 9.

   Example 1.1. Set hash_size parameter
...
modparam("ims_usrloc_pcscf", "hash_size", 10)
...

3.2. timer_interval (int)

   Number of seconds between two timer runs. The module uses timer to
   delete expired contacts.

   Default value is 60.

   Example 1.2. Set timer_interval parameter
...
modparam("ims_usrloc_pcscf", "timer_interval", 30)
...

3.3. db_url (string)

   Database URL.

   Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".

   Example 1.3. Set db_url parameter
...
modparam("ims_usrloc_pcscf", "db_url", "dbdriver://username:password@dbhost/dbna
me")
...

3.4. db_mode (int)

   This is the database mode to be used for the PCSCF usrloc data
   persistent storage. Currently this module supports the Write-Through
   scheme only.
     * 0 - This disables DB mode. Only memory will be used for usrloc and
       data will not survive a restart.
     * 1 - Write-Through Scheme. All changes to usrloc are immediately
       reflected in the database. This is slow but very reliable. This
       mode will ensure that no registration data is lost as a result of a
       restart or crash.
     * 3 - DB_ONLY Scheme. All changes to usrloc are immediately reflected
       in the database and additionally PCSCF usrloc data are downloaded
       from db and inserted into PCSCF usrloc cache if required - i.e. If
       contact data cannot be found in cache a db query for the contact is
       done in table location and when contact is found there its
       respective data are inserted in PCSCF usrloc cache. Also an audit
       had been added for removal of long expired PCSCF usrloc data in
       table location. This mode will ensure that no registration data is
       lost as a result of a restart or crash.

   Default value is 0.

   Example 1.4. Set db_mode parameter
...
modparam("ims_usrloc_pcscf", "db_mode", 1)
...

3.5. match_contact_host_port (int)

   If set to 1 (default), the contact is matched using only host and port
   in the contact URI.
     * 0 - When matching contact do full contact match procedure.
     * 1 - When matching contact compare only host and port of the contact
       URI.

   Default value is 1.

   Example 1.5. Set match_contact_host_port parameter
...
modparam("ims_usrloc_pcscf", "match_contact_host_port", 0)
...

3.6. expires_grace (int)

   Specify a grace time for keeping the contacts until they are finally
   deleted. The value of the parameter is defined in seconds.

   Default value is 3600.

   Example 1.6. Set expires_grace parameter
...
modparam("ims_usrloc_pcscf", "expires_grace", 1800)
...

3.7. audit_expired_pcontacts_interval (int)

   Number of seconds between two audit runs. Note: audit is used for
   db_mode DB_ONLY (3) only. The module uses this audit to delete expired
   contacts found in db table location which are expired at least as the
   audit_expired_pcontacts_timeout value. Such expired contacts in
   location may appear when these contacts are not present in usrloc cache
   because PCSCF crashed before contact expiry.

   Default value is 60.

   Example 1.7. Set audit_expired_pcontacts_interval parameter
...
modparam("ims_usrloc_pcscf", "audit_expired_pcontacts_interval", 120)
...

3.8. audit_expired_pcontacts_timeout (int)

   Number of seconds the contacts must be already expired before the audit
   starts working on them. It is recommended to set only values greater
   than the Default value 40. The module uses this audit to delete expired
   contacts found in db table location which are expired at least as many
   seconds as the sum of this timeout parameter value plus the value of
   the expires_grace parameter.

   Default value is 40.

   Example 1.8. Set audit_expired_pcontacts_timeout parameter
...
modparam("ims_usrloc_pcscf", "audit_expired_pcontacts_timeout", 120)
...

4. RPC Commands

   4.1. ulpcscf.status

   exported RPC commands.

4.1. ulpcscf.status

   Status of pcscf_usrloc, AORs, max slots, etc.

5. Statistics

   5.1. registered contacts
   5.2. impus
   5.3. expired contacts

   Exported statistics are listed in the next sections.

5.1. registered contacts

   Number of AOR contacts in registered state - cannot be reset.

5.2. impus

   Number of IMPUs - cannot be reset.

5.3. expired contacts

   Number of expired contacts - can be reset.

Chapter 2. Frequently Asked Questions

   2.1. Where can I find more about Kamailio?
   2.2. Where can I post a question about this module?
   2.3. How can I report a bug?

   2.1.

   Where can I find more about Kamailio?

   Take a look at https://www.kamailio.org/.

   2.2.

   Where can I post a question about this module?

   First at all check if your question was already answered on one of our
   mailing lists:
     * User Mailing List -
       https://lists.kamailio.org/mailman3/postorius/lists/sr-users.lists.
       kamailio.org/
     * Developer Mailing List -
       https://lists.kamailio.org/mailman3/postorius/lists/sr-dev.lists.ka
       mailio.org/

   E-mails regarding any stable Kamailio release should be sent to
   <sr-users@lists.kamailio.org> and e-mails regarding development
   versions should be sent to <sr-dev@lists.kamailio.org>.

   2.3.

   How can I report a bug?

   Please follow the guidelines provided at:
   https://github.com/kamailio/kamailio/issues.
