<?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;
]>
<!-- Module User's Guide -->
<chapter>
  <title>&adminguide;</title>

  <section>
    <title>Overview</title>

    <para>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:</para>

    <para>
      <itemizedlist>
        <listitem>
          <para>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'</para>
        </listitem>

        <listitem>
          <para>IPSEC Security Association for secure signalling between UE and
          PCSCF (first point of contact)</para>
        </listitem>

        <listitem>
          <para>IMPU, each contact can have a number of associated public
          identities (IMPU).</para>
        </listitem>
      </itemizedlist>
    </para>
  </section>

  <section>
    <title>Dependencies</title>

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

      <para>The following modules must be loaded before this module:
        <itemizedlist>
          <listitem>
            <para>
              <emphasis>None</emphasis>.
            </para>
          </listitem>
        </itemizedlist>
      </para>
    </section>

    <section>
      <title>External Libraries or Applications</title>

      <para>The following libraries or applications must be installed before
      running &kamailio; with this module loaded: <itemizedlist>
        <listitem>
          <para>
            <emphasis>None</emphasis>.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </section>
</section>

<section>
  <title>Parameters</title>

  <section>
    <title>hash_size (int)</title>

    <para>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.</para>

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

    <example>
      <title>Set <varname>hash_size</varname> parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "hash_size", 10)
...
      </programlisting>
    </example>
  </section>

  <section>
    <title>timer_interval (int)</title>

    <para>Number of seconds between two timer runs. The module uses timer to
      delete expired contacts.</para>

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

    <example>
      <title>Set timer_interval parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "timer_interval", 30)
...
      </programlisting>
    </example>
  </section>

  <section>
    <title><varname>db_url</varname> (string)</title>

    <para>Database URL.</para>

    <para>
      <emphasis>Default value is "&defaultdb;".</emphasis>
    </para>

    <example>
      <title>Set db_url parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "db_url", "&exampledb;")
...
      </programlisting>
    </example>
  </section>

  <section>
    <title>db_mode (int)</title>

    <para>This is the database mode to be used for the PCSCF usrloc data
      persistent storage. Currently this module supports the Write-Through
      scheme only.</para>

    <itemizedlist>
      <listitem>
        <para>0 - This disables DB mode. Only memory will be used for usrloc
          and data will not survive a restart.</para>
      </listitem>

      <listitem>
        <para>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.</para>
      </listitem>

      <listitem>
        <para>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.</para>
      </listitem>

    </itemizedlist>

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

    <example>
      <title>Set db_mode parameter</title>

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

  <section>
    <title>match_contact_host_port (int)</title>

    <para>If set to 1 (default), the contact is matched using only host
	  and port in the contact URI.</para>

    <itemizedlist>
      <listitem>
        <para>0 - When matching contact do full contact match procedure.</para>
      </listitem>

      <listitem>
        <para>1 - When matching contact compare only host and port of the contact URI.</para>
      </listitem>
    </itemizedlist>

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

    <example>
      <title>Set match_contact_host_port parameter</title>

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

  <section>
    <title>expires_grace (int)</title>

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

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

    <example>
      <title>Set expires_grace parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "expires_grace", 1800)
...
      </programlisting>
    </example>
  </section>

  <section>
    <title>audit_expired_pcontacts_interval (int)</title>

    <para>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.
    </para>

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

    <example>
      <title>Set audit_expired_pcontacts_interval parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "audit_expired_pcontacts_interval", 120)
...
      </programlisting>
    </example>
  </section>

  <section>
    <title>audit_expired_pcontacts_timeout (int)</title>

    <para>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.
    </para>

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

    <example>
      <title>Set audit_expired_pcontacts_timeout parameter</title>

      <programlisting format="linespecific">
...
modparam("ims_usrloc_pcscf", "audit_expired_pcontacts_timeout", 120)
...
      </programlisting>
    </example>
  </section>

</section>

<section>
  <title>RPC Commands</title>

  <para>exported RPC commands.</para>

  <section>
    <title>ulpcscf.status</title>

    <para>Status of pcscf_usrloc, AORs, max slots, etc.</para>
  </section>
</section>

<section>
  <title>Statistics</title>

  <para>Exported statistics are listed in the next sections.</para>

  <section>
    <title>registered contacts</title>

    <para>Number of AOR contacts in registered state - cannot be
      reset.</para>
  </section>

  <section>
    <title>impus</title>

    <para>Number of IMPUs - cannot be reset.</para>
  </section>

  <section>
    <title>expired contacts</title>

    <para>Number of expired contacts - can be reset.</para>
  </section>
</section>
</chapter>
