<?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 "../../../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. Alot 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 Assocation 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
			  "mysql://kamailio:kamailiorw@localhost/kamailio".</emphasis></para>

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

        <programlisting format="linespecific">...
modparam("ims_usrloc_pcscf", "db_url",
       "dbdriver://username:password@dbhost/dbname")
...
</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 refelcted 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>hashing_type (int)</title>

      <para>This is used to specify how contacts are stored in the internal
      memory hashing structures. This is an important parameter, not only for
      efficiency, but also for functionality. IMS can get rather confusing
      when it comes to contacts, SIP URIs and Implicitly registered SIP URIs
      (IMPUs). Originally the hash for storage of contacts was performed over
      the full contact URI viz (27821234567@10.0.0.10:12345;user=phone). This
      scheme is useful (from a performance perspective) in circumstances where
      you have many SIP URIs being registered from the same host/port.
      However, this causes problems in IMS environments where an implicit
      registration set of IMPU's is implicitly registered on behalf of a UA
      when it registers. This is because the implicit contact being used in
      subsequent requests could use a different SIP URI, for example
      john.doe@10.0.0.10:12345. In this case the P-CSCF would not be able to
      retrieve the initial contact as the hash over the different contact
      would in most cases be different. It was therefore proposed to hash the
      contact by IP:PORT only, effectively identifying a "device" - assuming a
      1-1 relationship between an IP:PORT pair. In our example, we would get
      to the same hash slot using the second SIP URI as we got using the
      initial registered SIP URI. Within this slot we can now search for the
      appropriate contact (remember there are still collision possibilities)
      and then traverse through the linked list if iumplcit IMPUs to find the
      contact currently being used. Of course if it is not found, then you can
      deny the request.</para>

      <itemizedlist>
        <listitem>
          <para>0 - This uses the original hash over AOR method. By default we
          are backwards compatible...</para>
        </listitem>
        <listitem>
          <para>1 - Use the newer hash over the Host from Contact-Header.</para>
        </listitem>
        <listitem>
          <para>2 - Use the newer hash over the source-IP from where the 
		request was received (useful for NAT-Scenarios)</para>
        </listitem>
      </itemizedlist>

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

      <example>
        <title>Set hashing_type parameter</title>

        <programlisting format="linespecific">...
modparam("ims_usrloc_pcscf", "hashing_type", 1)
...
</programlisting>
      </example>
    </section>
 <section>
      <title>lookup_check_received (int)</title>

      <para>If set to 1 (default), the Host in the contact will be checked
	against the Host, from which the request was received.</para>

      <itemizedlist>
        <listitem>
          <para>0 - Upon lookup, do not check the host against received.</para>
        </listitem>

        <listitem>
          <para>1 - Compare the host in the contact against the received info.</para>
        </listitem>
      </itemizedlist>

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

      <example>
        <title>Set lookup_check_received parameter</title>

        <programlisting format="linespecific">...
modparam("ims_usrloc_pcscf", "lookup_check_received", 0)
...
</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>
