<?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>db_url (int)</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>
      </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>

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