mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1020 lines
26 KiB
1020 lines
26 KiB
<?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>
|
|
User location module. The module keeps a user location table and
|
|
provides access to the table to other modules. The module exports no
|
|
functions that could be used directly from scripts.
|
|
</para>
|
|
<section id="contact-matching-algs">
|
|
<title>Contact matching</title>
|
|
<para>
|
|
How the contacts are matched (dor same AOR - Address of Record) is an
|
|
important aspect of the usrloc module, especially in the context of NAT
|
|
traversal - this raises more problems since contacts from different
|
|
phones of the same user may overlap (if behind NATs with same
|
|
configuration) or the re-register contact of the same phone may be
|
|
seen as a new one (due different binding via NAT).
|
|
</para>
|
|
<para>
|
|
The SIP RFC 3261 publishes a matching algorithm based only on the
|
|
contact string with callid and cseq number extra checking (if callid
|
|
is the same, it must have a higher cseq number, otherwise it is invalid).
|
|
But as argumented above, this is not enough in NAT traversal context,
|
|
so the &kamailio; implementation of contact matching offers more algorithms:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>contact based only</emphasis> - it is strict RFC 3261
|
|
compliancy - the contact is matched as string and extra checked
|
|
via callid and cseq (if callid is the same, it must have a
|
|
higher cseq number, otherwise it is invalid).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>contact and callid based</emphasis> - it is an extension
|
|
of the first case - the contact and callid must be matched as
|
|
string; the cseq must be higher than the previous one - so be
|
|
careful how you deal with REGISTER retransmissions in this
|
|
case.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>contact and path based</emphasis> - it is an extension
|
|
of the first case - the contact and path must be matched as
|
|
string; the cseq must be higher than the previous one - so be
|
|
careful how you deal with REGISTER retransmissions in this
|
|
case.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
How to control/select the contact maching algorithm, please see the
|
|
module parameter matching_mode at <xref linkend="matching-mode"/>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Optionally a database module</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><varname>nat_bflag</varname> (integer)</title>
|
|
<para>
|
|
The index of the branch flag to be used as NAT marker (if the contact
|
|
is or not natted). This is a branch flag and it will be imported and
|
|
used by all other modules depending of usrloc module.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>not set</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>nat_bflag</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "nat_bflag", 3)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>user_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing usernames.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>username</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>user_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "user_column", "username")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>domain_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing domains.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>domain</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>user_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "domain_column", "domain")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>contact_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing contacts.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>contact</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>contact_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "contact_column", "contact")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>expires_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing expires value.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>expires</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>expires_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "expires_column", "expires")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>q_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing q values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>q</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>q_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "q_column", "q")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>callid_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing callid values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>callid</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>callid_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "callid_column", "callid")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>cseq_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing cseq numbers.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>cseq</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cseq_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "cseq_column", "cseq")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>methods_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing supported methods.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>methods</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>methods_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "methods_column", "methods")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>flags_column</varname> (string)</title>
|
|
<para>
|
|
Name of column to save the internal flags of the record.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>flags</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>flags_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "flags_column", "flags")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>cflags_column</varname> (string)</title>
|
|
<para>
|
|
Name of column to save the branch/contact flags of the record.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>cflags</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cflags_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "cflags_column", "cflags")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>user_agent_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing user-agent values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>user_agent</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>user_agent_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "user_agent_column", "user_agent")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>received_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing the source IP, port, and protocol from the REGISTER
|
|
message.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>received</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>received_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "received_column", "received")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>socket_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing the received socket information (IP:port)
|
|
for the REGISTER message.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>socket</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>socket_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "socket_column", "socket")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>path_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing the Path header.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>path</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>path_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "path_column", "path")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>ruid_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing the record unique id.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>ruid</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>ruid_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "ruid_column", "myruid")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>instance_column</varname> (string)</title>
|
|
<para>
|
|
Name of column containing the SIP instace (GRUU - RFC5627).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>instance</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>instance_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "instance_column", "myinstance")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>use_domain</varname> (integer)</title>
|
|
<para>
|
|
If the domain part of the user should be also saved and used for
|
|
identifing the user (along with the username part). Useful in
|
|
multi domain scenarios. Non 0 value means true.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0 (false)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>use_domain</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "use_domain", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>desc_time_order</varname> (integer)</title>
|
|
<para>
|
|
If the user's contacts should be kept timestamp ordered; otherwise the
|
|
contact will be ordered based on q value.
|
|
Non 0 value means true.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0 (false)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>desc_time_order</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "desc_time_order", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>timer_interval</varname> (integer)</title>
|
|
<para>
|
|
Number of seconds between two timer runs. The module uses timer to
|
|
delete expired contacts, synchronize with database and other tasks,
|
|
that need to be run periodically.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 60.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_interval</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "timer_interval", 120)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
&url; of the database that should be used.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>&defaultdb;</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "db_url", "&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>db_mode</varname> (integer)</title>
|
|
<para>
|
|
The usrloc module can utilize database for persistent contact storage.
|
|
If you use database, your contacts will survive machine restarts or
|
|
SW crashes. The disadvantage is that accessing database can be very
|
|
time consuming. Therefore, usrloc module implements four database
|
|
accessing modes:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
0 - This disables database completely. Only memory will be used.
|
|
Contacts will not survive restart. Use this value if you need a
|
|
really fast usrloc and contact persistence is not necessary or
|
|
is provided by other means.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
1 - Write-Through scheme. All changes to usrloc are immediately
|
|
reflected in database too. This is very slow, but very reliable.
|
|
Use this scheme if speed is not your priority but need to make
|
|
sure that no registered contacts will be lost during crash or
|
|
reboot.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
2 - Write-Back scheme. This is a combination of previous two
|
|
schemes. All changes are made to memory and database
|
|
synchronization is done in the timer. The timer deletes all
|
|
expired contacts and flushes all modified or new contacts to
|
|
database. Use this scheme if you encounter high-load peaks
|
|
and want them to process as fast as possible. The mode will
|
|
not help at all if the load is high all the time. Also, latency
|
|
of this mode is much lower than latency of mode 1, but slightly
|
|
higher than latency of mode 0.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
3 - DB-Only scheme. No memory cache is kept, all operations being
|
|
directly performed with the database. The timer deletes all
|
|
expired contacts from database - cleans after clients that didn't
|
|
un-register or re-register. The mode is useful if you configure
|
|
more servers sharing the same DB without any replication at SIP
|
|
level. The mode may be slower due the high number of DB operation.
|
|
For example NAT pinging is a killer since during each ping cycle
|
|
all nated contact are loaded from the DB; The lack of memory
|
|
caching also disable the statistics exports.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<warning>
|
|
<para>
|
|
In case of crash or restart contacts that are in memory only and
|
|
haven't been flushed yet will get lost. If you want minimize the
|
|
risk, use shorter timer interval.
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "db_mode", 2)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="matching-mode">
|
|
<title><varname>matching_mode</varname> (integer)</title>
|
|
<para>
|
|
What contact matching algorithm to be used. Refer to section
|
|
<xref linkend="contact-matching-algs"/> for the description of the
|
|
algorithms.
|
|
</para>
|
|
<para>
|
|
The parameter may take the following values:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>0</emphasis> - CONTACT ONLY based matching
|
|
algorithm.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>1</emphasis> - CONTACT and CALLID based
|
|
matching algorithm.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>2</emphasis> - CONTACT and PATH based
|
|
matching algorithm. This mode is like mode <emphasis>0</emphasis>
|
|
but allows for duplicate contacts from differing paths.
|
|
If no path is available, it defaults to mode 0.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <emphasis>0 (CONTACT_ONLY)</emphasis>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>matching_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "matching_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>cseq_delay</varname> (integer)</title>
|
|
<para>
|
|
Delay (in seconds) for accepting as retransmissions register requests
|
|
with same Call-ID and Cseq. The delay is calculated starting from the
|
|
receiving time of the first register with that Call-ID and Cseq.
|
|
</para>
|
|
<para>
|
|
Retransmissions within this delay interval will be accepted and replied
|
|
as the original request, but no update will be done in location. If the
|
|
delay is exceeded, error is reported.
|
|
</para>
|
|
<para>
|
|
A value of 0 disable the retransmission detection.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>20 seconds</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cseq_delay</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "cseq_delay", 5)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>fetch_rows</varname> (integer)</title>
|
|
<para>
|
|
The number of the rows to be fetched at once from database
|
|
when loading the location records. This value can be used
|
|
to tune the load time at startup. For 1MB of private memory (default)
|
|
it should be below 4000. The database driver must support
|
|
fetch_result() capability.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>2000</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>fetch_rows</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "fetch_rows", 3000)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>hash_size</varname> (integer)</title>
|
|
<para>
|
|
The number of entries of the hash table used by usrloc to store the
|
|
location 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 <quote>9</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>hash_size</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "hash_size", 10)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="preload">
|
|
<title><varname>preload</varname> (string)</title>
|
|
<para>
|
|
Preload location table given as value. A location table is loaded
|
|
based on fixup of registrar functions, therefore you need to use this
|
|
parameter only to load tables that are not used by registrar module
|
|
directly in configuration file.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>NULL</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>preload</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "preload", "location")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="db_update_as_insert">
|
|
<title><varname>db_update_as_insert</varname> (string)</title>
|
|
<para>
|
|
Set this parameter if you want to do INSERT DB operations
|
|
instead of UPDATE DB operations. It is recommended to set this parameter
|
|
if you use Cassandra as a DB backend.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_update_as_insert</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "db_update_as_insert", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="db_check_update">
|
|
<title><varname>db_check_update</varname> (string)</title>
|
|
<para>
|
|
Set this parameter to 1 if you want to do DB INSERT if the number
|
|
of affected rows by contact DB UPDATE operation is 0. The
|
|
database module driver has to implement affected_rows() DB API
|
|
function, otherwise this parameter is ignored - e.g., MySQL and
|
|
Postgres DB connectors offer affected_rows().
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> (no DB INSERT).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_check_update</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "db_check_update", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="timer_procs">
|
|
<title><varname>timer_procs</varname> (string)</title>
|
|
<para>
|
|
Number of timer processes to be started by module. Timer processes
|
|
take care of checking expired records and syncronization with
|
|
database. If set to 0, no dedicated timer is started, the one from
|
|
core will be used.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_procs</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("usrloc", "timer_procs", 4)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<para>
|
|
There are no exported functions that could be used in scripts.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>MI Commands</title>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_rm</function>
|
|
</title>
|
|
<para>
|
|
Deletes an entire AOR record (including its contacts).
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>table name</emphasis> - table where the AOR
|
|
is removed from (Ex: location).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>AOR</emphasis> - user AOR in username[@domain]
|
|
format (domain must be supplied only if use_domain option
|
|
is on).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_rm_contact</function>
|
|
</title>
|
|
<para>
|
|
Deletes a contact from an AOR record.
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>table name</emphasis> - table where the AOR
|
|
is removed from (Ex: location).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>AOR</emphasis> - user AOR in username[@domain]
|
|
format (domain must be supplied only if use_domain option
|
|
is on).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>contact</emphasis> - exact contact to be removed
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_dump</function>
|
|
</title>
|
|
<para>
|
|
Dumps the entire content of the USRLOC in memory cache
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>brief</emphasis> - (optional, may not be present); if
|
|
equals to string <quote>brief</quote>, a brief dump will be
|
|
done (only AOR and contacts, with no other details)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_flush</function>
|
|
</title>
|
|
<para>
|
|
Triggers the flush of USRLOC memory cache into DB.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_add</function>
|
|
</title>
|
|
<para>
|
|
Adds a new contact for an user AOR.
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>table name</emphasis> - table where the contact
|
|
will be added (Ex: location).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>AOR</emphasis> - user AOR in username[@domain]
|
|
format (domain must be supplied only if use_domain option
|
|
is on).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>contact</emphasis> - contact string to be added
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>expires</emphasis> - expires value of the contact
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>Q</emphasis> - Q value of the contact
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>unused</emphasis> - unused attribute (kept for
|
|
backword compatibility)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>flags</emphasis> - internal USRLOC flags of the
|
|
contact
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>cflags</emphasis> - per branch flags of the
|
|
contact
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>methods</emphasis> - mask with supported requests
|
|
of the contact
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">ul_show_contact</function>
|
|
</title>
|
|
<para>
|
|
Dumps the contacts of an user AOR.
|
|
</para>
|
|
<para>Parameters: </para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>table name</emphasis> - table where the AOR
|
|
resides (Ex: location).
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>AOR</emphasis> - user AOR in username[@domain]
|
|
format (domain must be supplied only if use_domain option
|
|
is on).
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Statistics</title>
|
|
<para>
|
|
Exported statistics are listed in the next sections.
|
|
</para>
|
|
<section>
|
|
<title>users</title>
|
|
<para>
|
|
Number of AOR existing in the USRLOC memory cache for that domain
|
|
- can not be resetted; this statistic will be register for each
|
|
used domain (Ex: location).
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>contacts</title>
|
|
<para>
|
|
Number of contacts existing in the USRLOC memory cache for that
|
|
domain - can not be resetted; this statistic will be register for
|
|
each used domain (Ex: location).
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>expires</title>
|
|
<para>
|
|
Total number of expired contacts for that domain - can be resetted;
|
|
this statistic will be register for each used domain
|
|
(Ex: location).
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>registered_users</title>
|
|
<para>
|
|
Total number of AOR existing in the USRLOC memory cache for all
|
|
domains - can not be resetted.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
</chapter>
|
|
|