91f3814374632a8a5c13d35c398318cdeb365aaf
[sip-router] / src / modules / usrloc / doc / usrloc_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13
14         <title>&adminguide;</title>
15
16         <section>
17         <title>Overview</title>
18         <para>
19                 The User location module module keeps a user location table and
20                 provides access to the table for  other modules. The module exports no
21                 functions that can  be used directly from routing scripts.
22         </para>
23                 <section id="contact-matching-algs">
24                 <title>Contact matching</title>
25                 <para>
26                 How the contacts are matched (for the same AOR - Address of Record) is an
27                 important aspect of the usrloc module, especially in the context of NAT
28                 traversal - this raises more problems since contacts from different
29                 phones of the same user may overlap (if both are behind NATs with the same
30                 configuration) or the re-register contact of the same phone may be
31                 seen as a new one (due different binding via NAT).
32                 </para>
33                 <para>
34                 The SIP RFC 3261 publishes a matching algorithm based only on the
35                 contact string with Call-id and Cseq extra checking (if the Call-ID
36                 is the same, it must have a higher Cseq number, otherwise it is invalid).
37                 But as argued above, this is not enough in NAT traversal context,
38                 so the &kamailio; implementation of contact matching offers more algorithms:
39                 </para>
40                 <itemizedlist>
41                         <listitem>
42                         <para>
43                                 <emphasis>Contact based only</emphasis> - it is strict RFC 3261
44                                 compliancy - the Contact URI is matched as string and extra checked
45                                 via Call-ID and cseq (if Call-ID is the same, it must have a
46                                 higher cseq number, otherwise it is invalid).
47                         </para>
48                         </listitem>
49                         <listitem>
50                         <para>
51                                 <emphasis>Contact and Call-id based</emphasis> - it is an extension
52                                 of the first case - the contact and Call-ID must be matched as
53                                 string; the cseq must be higher than the previous one - so be
54                                 careful how you deal with REGISTER retransmissions in this
55                                 case.
56                         </para>
57                         </listitem>
58                         <listitem>
59                         <para>
60                                 <emphasis>contact and path based</emphasis> - it is an extension
61                                 of the first case - the contact and path must be matched as
62                                 string; the cseq must be higher than the previous one - so be
63                                 careful how you deal with REGISTER retransmissions in this
64                                 case.
65                         </para>
66                         </listitem>
67                         <listitem>
68                         <para>
69                                 <emphasis>Call-id only based</emphasis> - it is not
70                                 according to RFC3261, as it will check the Call-ID only
71                                 (independent of the Contact-Header or Path).
72                         </para>
73                         </listitem>
74                 </itemizedlist>
75                 <para>
76                 To find out how to control/select the contact matching algorithm, please see the
77                 module parameter matching_mode - <xref linkend="usrloc.p.matching_mode"/>.
78                 </para>
79                 </section>
80         </section>
81
82         <section>
83         <title>Dependencies</title>
84         <section>
85                 <title>&kamailio; Modules</title>
86                 <para>
87                 The following modules must be loaded before this module:
88                         <itemizedlist>
89                         <listitem>
90                         <para>
91                                 <emphasis>Optionally a database module</emphasis>.
92                         </para>
93                         </listitem>
94                         </itemizedlist>
95                 </para>
96         </section>
97         <section>
98                 <title>External Libraries or Applications</title>
99                 <para>
100                 The following libraries or applications must be installed before
101                 running &kamailio; with this module loaded:
102                         <itemizedlist>
103                         <listitem>
104                         <para>
105                                 <emphasis>None</emphasis>.
106                         </para>
107                         </listitem>
108                         </itemizedlist>
109                 </para>
110         </section>
111         </section>
112         <section>
113         <title>Parameters</title>
114         <section id="usrloc.p.nat_bflag">
115                 <title><varname>nat_bflag</varname> (integer)</title>
116                 <para>
117                 The index of the branch flag to be used as NAT marker (if the contact
118                 is or not natted). This is a branch flag and it will be imported and
119                 used by all other modules depending of usrloc module.
120                 </para>
121                 <para>
122                 <emphasis>
123                         Default value is <quote>not set</quote>.
124                 </emphasis>
125                 </para>
126                 <example>
127                 <title>Set <varname>nat_bflag</varname> parameter</title>
128                 <programlisting format="linespecific">
129 ...
130 modparam("usrloc", "nat_bflag", 3)
131 ...
132 </programlisting>
133                 </example>
134         </section>
135
136         <section id="usrloc.p.user_column">
137                 <title><varname>user_column</varname> (string)</title>
138                 <para>
139                 Name of database column containing usernames.
140                 </para>
141                 <para>
142                 <emphasis>
143                         Default value is <quote>username</quote>.
144                 </emphasis>
145                 </para>
146                 <example>
147                 <title>Set <varname>user_column</varname> parameter</title>
148                 <programlisting format="linespecific">
149 ...
150 modparam("usrloc", "user_column", "username")
151 ...
152 </programlisting>
153                 </example>
154         </section>
155
156         <section id="usrloc.p.domain_column">
157                 <title><varname>domain_column</varname> (string)</title>
158                 <para>
159                 Name of database column containing domains.
160                 </para>
161                 <para>
162                 <emphasis>
163                         Default value is <quote>domain</quote>.
164                 </emphasis>
165                 </para>
166                 <example>
167                 <title>Set <varname>user_column</varname> parameter</title>
168                 <programlisting format="linespecific">
169 ...
170 modparam("usrloc", "domain_column", "domain")
171 ...
172 </programlisting>
173                 </example>
174         </section>
175
176         <section id="usrloc.p.contact_column">
177                 <title><varname>contact_column</varname> (string)</title>
178                 <para>
179                 Name of database column containing contacts.
180                 </para>
181                 <para>
182                 <emphasis>
183                         Default value is <quote>contact</quote>.
184                 </emphasis>
185                 </para>
186                 <example>
187                 <title>Set <varname>contact_column</varname> parameter</title>
188                 <programlisting format="linespecific">
189 ...
190 modparam("usrloc", "contact_column", "contact")
191 ...
192 </programlisting>
193                 </example>
194         </section>
195
196         <section id="usrloc.p.expires_column">
197                 <title><varname>expires_column</varname> (string)</title>
198                 <para>
199                 Name of database column containing expires value.
200                 </para>
201                 <para>
202                 <emphasis>
203                         Default value is <quote>expires</quote>.
204                 </emphasis>
205                 </para>
206                 <example>
207                 <title>Set <varname>expires_column</varname> parameter</title>
208                 <programlisting format="linespecific">
209 ...
210 modparam("usrloc", "expires_column", "expires")
211 ...
212 </programlisting>
213                 </example>
214         </section>
215
216         <section id="usrloc.p.q_column">
217                 <title><varname>q_column</varname> (string)</title>
218                 <para>
219                 Name of database column containing q values.
220                 </para>
221                 <para>
222                 <emphasis>
223                         Default value is <quote>q</quote>.
224                 </emphasis>
225                 </para>
226                 <example>
227                 <title>Set <varname>q_column</varname> parameter</title>
228                 <programlisting format="linespecific">
229 ...
230 modparam("usrloc", "q_column", "q")
231 ...
232 </programlisting>
233                 </example>
234         </section>
235
236         <section id="usrloc.p.callid_column">
237                 <title><varname>callid_column</varname> (string)</title>
238                 <para>
239                 Name of database column containing Call-ID values.
240                 </para>
241                 <para>
242                 <emphasis>
243                         Default value is <quote>callid</quote>.
244                 </emphasis>
245                 </para>
246                 <example>
247                 <title>Set <varname>callid_column</varname> parameter</title>
248                 <programlisting format="linespecific">
249 ...
250 modparam("usrloc", "callid_column", "callid")
251 ...
252 </programlisting>
253                 </example>
254         </section>
255
256         <section id="usrloc.p.cseq_column">
257                 <title><varname>cseq_column</varname> (string)</title>
258                 <para>
259                 Name of database column containing Cseq.
260                 </para>
261                 <para>
262                 <emphasis>
263                         Default value is <quote>cseq</quote>.
264                 </emphasis>
265                 </para>
266                 <example>
267                 <title>Set <varname>cseq_column</varname> parameter</title>
268                 <programlisting format="linespecific">
269 ...
270 modparam("usrloc", "cseq_column", "cseq")
271 ...
272 </programlisting>
273                 </example>
274         </section>
275
276         <section id="usrloc.p.methods_column">
277                 <title><varname>methods_column</varname> (string)</title>
278                 <para>
279                 Name of database column containing supported methods.
280                 </para>
281                 <para>
282                 <emphasis>
283                         Default value is <quote>methods</quote>.
284                 </emphasis>
285                 </para>
286                 <example>
287                 <title>Set <varname>methods_column</varname> parameter</title>
288                 <programlisting format="linespecific">
289 ...
290 modparam("usrloc", "methods_column", "methods")
291 ...
292 </programlisting>
293                 </example>
294         </section>
295
296         <section id="usrloc.p.flags_column">
297                 <title><varname>flags_column</varname> (string)</title>
298                 <para>
299                 Name of database column to save the internal flags of the record.
300                 </para>
301                 <para>
302                 <emphasis>
303                         Default value is <quote>flags</quote>.
304                 </emphasis>
305                 </para>
306                 <example>
307                 <title>Set <varname>flags_column</varname> parameter</title>
308                 <programlisting format="linespecific">
309 ...
310 modparam("usrloc", "flags_column", "flags")
311 ...
312 </programlisting>
313                 </example>
314         </section>
315
316         <section id="usrloc.p.cflags_column">
317                 <title><varname>cflags_column</varname> (string)</title>
318                 <para>
319                 Name of database column to save the branch/contact flags of the record.
320                 </para>
321                 <para>
322                 <emphasis>
323                         Default value is <quote>cflags</quote>.
324                 </emphasis>
325                 </para>
326                 <example>
327                 <title>Set <varname>cflags_column</varname> parameter</title>
328                 <programlisting format="linespecific">
329 ...
330 modparam("usrloc", "cflags_column", "cflags")
331 ...
332 </programlisting>
333                 </example>
334         </section>
335
336         <section id="usrloc.p.user_agent_column">
337                 <title><varname>user_agent_column</varname> (string)</title>
338                 <para>
339                 Name of database column containing user-agent values.
340                 </para>
341                 <para>
342                 <emphasis>
343                         Default value is <quote>user_agent</quote>.
344                 </emphasis>
345                 </para>
346                 <example>
347                 <title>Set <varname>user_agent_column</varname> parameter</title>
348                 <programlisting format="linespecific">
349 ...
350 modparam("usrloc", "user_agent_column", "user_agent")
351 ...
352 </programlisting>
353                 </example>
354         </section>
355
356         <section id="usrloc.p.received_column">
357                 <title><varname>received_column</varname> (string)</title>
358                 <para>
359                 Name of database column containing the source IP, port, and protocol from the REGISTER
360                 message.
361                 </para>
362                 <para>
363                 <emphasis>
364                         Default value is <quote>received</quote>.
365                 </emphasis>
366                 </para>
367                 <example>
368                 <title>Set <varname>received_column</varname> parameter</title>
369                 <programlisting format="linespecific">
370 ...
371 modparam("usrloc", "received_column", "received")
372 ...
373 </programlisting>
374                 </example>
375         </section>
376
377         <section id="usrloc.p.socket_column">
378                 <title><varname>socket_column</varname> (string)</title>
379                 <para>
380                 Name of database column containing the received socket information (IP:port)
381                 for the REGISTER message.
382                 </para>
383                 <para>
384                 <emphasis>
385                         Default value is <quote>socket</quote>.
386                 </emphasis>
387                 </para>
388                 <example>
389                 <title>Set <varname>socket_column</varname> parameter</title>
390                 <programlisting format="linespecific">
391 ...
392 modparam("usrloc", "socket_column", "socket")
393 ...
394 </programlisting>
395                 </example>
396         </section>
397
398         <section id="usrloc.p.path_column">
399                 <title><varname>path_column</varname> (string)</title>
400                 <para>
401                 Name of database column containing the Path header.
402                 </para>
403                 <para>
404                 <emphasis>
405                         Default value is <quote>path</quote>.
406                 </emphasis>
407                 </para>
408                 <example>
409                 <title>Set <varname>path_column</varname> parameter</title>
410                 <programlisting format="linespecific">
411 ...
412 modparam("usrloc", "path_column", "path")
413 ...
414 </programlisting>
415                 </example>
416         </section>
417
418         <section id="usrloc.p.ruid_column">
419                 <title><varname>ruid_column</varname> (string)</title>
420                 <para>
421                 Name of database column containing the Kamailio record unique id.
422                 </para>
423                 <para>
424                 <emphasis>
425                         Default value is <quote>ruid</quote>.
426                 </emphasis>
427                 </para>
428                 <example>
429                 <title>Set <varname>ruid_column</varname> parameter</title>
430                 <programlisting format="linespecific">
431 ...
432 modparam("usrloc", "ruid_column", "myruid")
433 ...
434 </programlisting>
435                 </example>
436         </section>
437
438         <section id="usrloc.p.instance_column">
439                 <title><varname>instance_column</varname> (string)</title>
440                 <para>
441                 Name of database column containing the SIP instance ID (GRUU - RFC5627).
442                 This is a unique device identifier - UUID.
443                 </para>
444                 <para>
445                 <emphasis>
446                         Default value is <quote>instance</quote>.
447                 </emphasis>
448                 </para>
449                 <example>
450                 <title>Set <varname>instance_column</varname> parameter</title>
451                 <programlisting format="linespecific">
452 ...
453 modparam("usrloc", "instance_column", "myinstance")
454 ...
455 </programlisting>
456                 </example>
457         </section>
458
459         <section id="usrloc.p.server_id_column">
460                 <title><varname>server_id_column</varname> (string)</title>
461                 <para>
462                 Name of database table column containing the value for server id.
463                 </para>
464                 <para>
465                 <emphasis>
466                         Default value is <quote>server_id</quote>.
467                 </emphasis>
468                 </para>
469                 <example>
470                 <title>Set <varname>server_id_column</varname> parameter</title>
471                 <programlisting format="linespecific">
472 ...
473 modparam("usrloc", "server_id_column", "srv_id")
474 ...
475 </programlisting>
476                 </example>
477         </section>
478
479         <section id="usrloc.p.connection_id_column">
480                 <title><varname>connection_id_column</varname> (string)</title>
481                 <para>
482                 Name of database table column containing the value for connection id.
483                 </para>
484                 <para>
485                 <emphasis>
486                         Default value is <quote>connection_id</quote>.
487                 </emphasis>
488                 </para>
489                 <example>
490                 <title>Set <varname>connection_id_column</varname> parameter</title>
491                 <programlisting format="linespecific">
492 ...
493 modparam("usrloc", "connection_id_column", "con_id")
494 ...
495 </programlisting>
496                 </example>
497         </section>
498
499         <section id="usrloc.p.keepalive_column">
500                 <title><varname>keepalive_column</varname> (string)</title>
501                 <para>
502                 Name of database table column containing the value for keepalive status.
503                 </para>
504                 <para>
505                 <emphasis>
506                         Default value is <quote>keepalive</quote>.
507                 </emphasis>
508                 </para>
509                 <example>
510                 <title>Set <varname>keepalive_column</varname> parameter</title>
511                 <programlisting format="linespecific">
512 ...
513 modparam("usrloc", "keepalive_column", "kalive")
514 ...
515 </programlisting>
516                 </example>
517         </section>
518
519         <section id="usrloc.p.partition_column">
520                 <title><varname>partition_column</varname> (string)</title>
521                 <para>
522                 Name of database table column containing the value for partition id.
523                 </para>
524                 <para>
525                 <emphasis>
526                         Default value is <quote>partition</quote>.
527                 </emphasis>
528                 </para>
529                 <example>
530                 <title>Set <varname>partitioncolumn</varname> parameter</title>
531                 <programlisting format="linespecific">
532 ...
533 modparam("usrloc", "partition_column", "part")
534 ...
535 </programlisting>
536                 </example>
537         </section>
538
539         <section id="usrloc.p.use_domain">
540                 <title><varname>use_domain</varname> (integer)</title>
541                 <para>
542                 If the domain part of the user should be also saved and used for
543                 identifying the user (along with the username part). Useful in
544                 multi domain scenarios. Non 0 value means true.
545                 </para>
546                 <para>
547                 <emphasis>
548                         Default value is <quote>0 (false)</quote>.
549                 </emphasis>
550                 </para>
551                 <example>
552                 <title>Set <varname>use_domain</varname> parameter</title>
553                 <programlisting format="linespecific">
554 ...
555 modparam("usrloc", "use_domain", 1)
556 ...
557 </programlisting>
558                 </example>
559         </section>
560
561         <section id="usrloc.p.desc_time_order">
562                 <title><varname>desc_time_order</varname> (integer)</title>
563                 <para>
564                 If the user's contacts should be kept timestamp ordered; otherwise the
565                 contact will be ordered based on q value.
566                 Non 0 value means true.
567                 </para>
568                 <para>
569                 <emphasis>
570                         Default value is <quote>0 (false)</quote>.
571                 </emphasis>
572                 </para>
573                 <example>
574                 <title>Set <varname>desc_time_order</varname> parameter</title>
575                 <programlisting format="linespecific">
576 ...
577 modparam("usrloc", "desc_time_order", 1)
578 ...
579 </programlisting>
580                 </example>
581         </section>
582
583         <section id="usrloc.p.timer_interval">
584                 <title><varname>timer_interval</varname> (integer)</title>
585                 <para>
586                 Number of seconds between two timer runs. The module uses a timer to
587                 delete expired contacts, synchronize with database and other tasks,
588                 that need to be run periodically.
589                 </para>
590                 <para>
591                 <emphasis>
592                         Default value is 60.
593                 </emphasis>
594                 </para>
595                 <example>
596                 <title>Set <varname>timer_interval</varname> parameter</title>
597                 <programlisting format="linespecific">
598 ...
599 modparam("usrloc", "timer_interval", 120)
600 ...
601 </programlisting>
602                 </example>
603         </section>
604
605         <section id="usrloc.p.db_url">
606                 <title><varname>db_url</varname> (string)</title>
607                 <para>
608                 &url; of the database that should be used.
609                 </para>
610                 <para>
611                 <emphasis>
612                         Default value is <quote>&defaultdb;</quote>.
613                 </emphasis>
614                 </para>
615                 <example>
616                 <title>Set <varname>db_url</varname> parameter</title>
617                 <programlisting format="linespecific">
618 ...
619 modparam("usrloc", "db_url", "&exampledb;")
620 ...
621 </programlisting>
622                 </example>
623         </section>
624
625         <section id="usrloc.p.db_mode">
626                 <title><varname>db_mode</varname> (integer)</title>
627                 <para>
628                 The usrloc module can utilize a database for persistent contact storage.
629                 If a database is used, the location database (contacts)  will survive
630                 machine restarts or software crashes. The disadvantage is that accessing 
631                 a database can be very time consuming. Therefore, usrloc module implements
632                 four database accessing modes:
633                 </para>
634                 <itemizedlist>
635                 <listitem>
636                         <para>
637                         0 - This disables database completely. Only memory will be used.
638                         Contacts will not survive restart. Use this value if you need a
639                         really fast usrloc and contact persistence is not necessary or
640                         is provided by other means.
641                         </para>
642                 </listitem>
643                 <listitem>
644                         <para>
645                         1 - Write-Through scheme. All changes to usrloc are immediately
646                         reflected in database too. This is very slow, but very reliable.
647                         Use this scheme if speed is not your priority but need to make
648                         sure that no registered contacts will be lost during crash or
649                         reboot.
650                         </para>
651                 </listitem>
652                 <listitem>
653                         <para>
654                         2 - Write-Back scheme. This is a combination of previous two
655                         schemes. All changes are made to memory and database
656                         synchronization is done in the timer. The timer deletes all
657                         expired contacts and flushes all modified or new contacts to
658                         database.  Use this scheme if you encounter high-load peaks
659                         and want them to process as fast as possible. The mode will
660                         not help at all if the load is high all the time.  Also, latency
661                         of this mode is much lower than latency of mode 1, but slightly
662                         higher than latency of mode 0.
663                         </para>
664                 </listitem>
665                 <listitem>
666                         <para>
667                         3 - DB-Only scheme. No memory cache is kept, all operations being
668                         directly performed with the database. The timer deletes all
669                         expired contacts from database - cleans after clients that didn't
670                         un-register or re-register. The mode is useful if you configure
671                         more servers sharing the same DB without any replication at SIP
672                         level. The mode may be slower due the high number of DB operation.
673                         For example NAT pinging is a killer since during each ping cycle
674                         all natted contact are loaded from the DB; The lack of memory
675                         caching also disable the statistics exports.
676                         </para>
677                 </listitem>
678                 <listitem>
679                         <para>
680                         4 - This uses database to load records at startup but uses only
681                         memory during the runtime. Records are not written back at all,
682                         not even at shutdown. Useful for scenarios when registrations are
683                         replicated to a node that does the storage in database during
684                         runtime.
685                         </para>
686                 </listitem>
687                 </itemizedlist>
688                 <warning>
689                 <para>
690                         In case of crash or restart contacts that are in memory only and
691                         haven't been flushed yet will get lost. If you want minimize the
692                         risk, use shorter timer interval.
693                 </para>
694                 </warning>
695                 <para>
696                 <emphasis>
697                         Default value is 0.
698                 </emphasis>
699                 </para>
700                 <example>
701                 <title>Set <varname>db_mode</varname> parameter</title>
702                 <programlisting format="linespecific">
703 ...
704 modparam("usrloc", "db_mode", 2)
705 ...
706 </programlisting>
707                 </example>
708         </section>
709
710         <section id="usrloc.p.db_load">
711                 <title><varname>db_load</varname> (integer)</title>
712                 <para>
713                 Determine if the usrloc module should load contacts from the database storage during module initialization
714                 A value of 0 disable the loading from the database, this parameter is ignored if db_mode 4 is set
715                 </para>
716                 <para>
717                 <emphasis>
718                         Default value is 1.
719                 </emphasis>
720                 </para>
721                 <example>
722                 <title>Set <varname>db_load</varname> parameter</title>
723                 <programlisting format="linespecific">
724 ...
725 modparam("usrloc", "db_load", "0")
726 ...
727                 </programlisting>
728                 </example>
729         </section>
730
731         <section id="usrloc.p.db_insert_update">
732                 <title><varname>db_insert_update</varname> (integer)</title>
733                 <para>
734                 Determine if the usrloc module should do an update when a duplicate key is found while inserting
735                 A value of 1 will activate update on duplicate key
736                 </para>
737                 <para>
738                 <emphasis>
739                         Default value is 0.
740                 </emphasis>
741                 </para>
742                 <example>
743                 <title>Set <varname>db_insert_update</varname> parameter</title>
744                 <programlisting format="linespecific">
745 ...
746 modparam("usrloc", "db_insert_update", "1")
747 ...
748                 </programlisting>
749                 </example>
750         </section>
751
752         <section id="usrloc.p.matching_mode">
753                 <title><varname>matching_mode</varname> (integer)</title>
754                 <para>
755                 What contact matching algorithm to be used. Refer to section
756                 <xref linkend="contact-matching-algs"/> for the description of the
757                 algorithms.
758                 </para>
759                 <para>
760                 The parameter may take the following values:
761                 </para>
762                 <itemizedlist>
763                         <listitem>
764                                 <para><emphasis>0</emphasis> - CONTACT ONLY based matching
765                                 algorithm.
766                                 </para>
767                         </listitem>
768                         <listitem>
769                                 <para><emphasis>1</emphasis> - CONTACT and CALLID based
770                                 matching algorithm.
771                                 </para>
772                         </listitem>
773                         <listitem>
774                                 <para><emphasis>2</emphasis> - CONTACT and PATH based
775                                 matching algorithm.  This mode is like mode <emphasis>0</emphasis>
776                                 but allows for duplicate contacts from differing paths.
777                                 If no path is available, it defaults to mode 0.
778                                 </para>
779                         </listitem>
780                         <listitem>
781                                 <para><emphasis>3</emphasis> - CALLID only based
782                                 matching algorithm. This mode will discard any duplicate
783                                 registration coming through different paths.
784                                 </para>
785                         </listitem>
786                 </itemizedlist>
787                 <para>
788                 <emphasis>
789                         Default value is <emphasis>0 (CONTACT_ONLY)</emphasis>.
790                 </emphasis>
791                 </para>
792                 <example>
793                 <title>Set <varname>matching_mode</varname> parameter</title>
794                 <programlisting format="linespecific">
795 ...
796 modparam("usrloc", "matching_mode", 1)
797 ...
798 </programlisting>
799                 </example>
800         </section>
801
802         <section id="usrloc.p.cseq_delay">
803                 <title><varname>cseq_delay</varname> (integer)</title>
804                 <para>
805                 Delay (in seconds) for accepting as retransmissions register requests
806                 with same Call-ID and Cseq. The delay is calculated starting from the
807                 receiving time of the first register with that Call-ID and Cseq.
808                 </para>
809                 <para>
810                 Retransmissions within this delay interval will be accepted and replied
811                 as the original request, but no update will be done in location. If the
812                 delay is exceeded, error is reported.
813                 </para>
814                 <para>
815                 A value of 0 disable the retransmission detection.
816                 </para>
817                 <para>
818                 <emphasis>
819                         Default value is <quote>20 seconds</quote>.
820                 </emphasis>
821                 </para>
822                 <example>
823                 <title>Set <varname>cseq_delay</varname> parameter</title>
824                 <programlisting format="linespecific">
825 ...
826 modparam("usrloc", "cseq_delay", 5)
827 ...
828 </programlisting>
829                 </example>
830         </section>
831
832         <section id="usrloc.p.fetch_rows">
833                 <title><varname>fetch_rows</varname> (integer)</title>
834                 <para>
835                 The number of the rows to be fetched at once from database
836                 when loading the location records. This value can be used
837                 to tune the load time at startup. For 1MB of private memory (default)
838                 it should be below 4000. The database driver must support
839                 fetch_result() capability.
840                 </para>
841                 <para>
842                 <emphasis>
843                         Default value is <quote>2000</quote>.
844                 </emphasis>
845                 </para>
846                 <example>
847                 <title>Set <varname>fetch_rows</varname> parameter</title>
848                 <programlisting format="linespecific">
849 ...
850 modparam("usrloc", "fetch_rows", 3000)
851 ...
852 </programlisting>
853                 </example>
854         </section>
855
856         <section id="usrloc.p.hash_size">
857                 <title><varname>hash_size</varname> (integer)</title>
858                 <para>
859                 The number of entries of the hash table used by usrloc to store the
860                 location records is 2^hash_size. For hash_size=4, the number of slots
861                 of the hash table is 16.
862                 </para>
863                 <para>
864                 <emphasis>
865                         Default value is <quote>10</quote> (1024 slots).
866                 </emphasis>
867                 </para>
868                 <example>
869                 <title>Set <varname>hash_size</varname> parameter</title>
870                 <programlisting format="linespecific">
871 ...
872 modparam("usrloc", "hash_size", 12)
873 ...
874 </programlisting>
875                 </example>
876         </section>
877
878         <section id="usrloc.p.preload">
879                 <title><varname>preload</varname> (string)</title>
880                 <para>
881                 Preload location table given as value. A location table is loaded
882                 based on fixup of registrar functions, therefore you need to use this
883                 parameter only to load tables that are not used by registrar module
884                 directly in configuration file.
885                 </para>
886                 <para>
887                 <emphasis>
888                         Default value is <quote>NULL</quote>.
889                 </emphasis>
890                 </para>
891                 <example>
892                 <title>Set <varname>preload</varname> parameter</title>
893                 <programlisting format="linespecific">
894 ...
895 modparam("usrloc", "preload", "location")
896 ...
897 </programlisting>
898                 </example>
899         </section>
900
901         <section id="usrloc.p.db_update_as_insert">
902                 <title><varname>db_update_as_insert</varname> (int)</title>
903                 <para>
904                         Set this parameter if you want to do INSERT DB operations
905                         instead of UPDATE DB operations. It is recommended to set this parameter
906                         if you use Cassandra as a DB backend.
907                 </para>
908                 <para>
909                 <emphasis>
910                         Default value is <quote>0</quote>.
911                 </emphasis>
912                 </para>
913                 <example>
914                 <title>Set <varname>db_update_as_insert</varname> parameter</title>
915                 <programlisting format="linespecific">
916 ...
917 modparam("usrloc", "db_update_as_insert", 1)
918 ...
919 </programlisting>
920                 </example>
921         </section>
922
923         <section id="usrloc.p.db_check_update">
924                 <title><varname>db_check_update</varname> (int)</title>
925                 <para>
926                         Set this parameter to 1 if you want to do DB INSERT if the number
927                         of affected rows by contact DB UPDATE operation is 0. The
928                         database module driver has to implement affected_rows() DB API
929                         function, otherwise this parameter is ignored - e.g., MySQL and
930                         Postgres DB connectors offer affected_rows().
931                 </para>
932                 <para>
933                 <emphasis>
934                         Default value is <quote>0</quote> (no DB INSERT).
935                 </emphasis>
936                 </para>
937                 <example>
938                 <title>Set <varname>db_check_update</varname> parameter</title>
939                 <programlisting format="linespecific">
940 ...
941 modparam("usrloc", "db_check_update", 1)
942 ...
943 </programlisting>
944                 </example>
945         </section>
946
947         <section id="usrloc.p.timer_procs">
948                 <title><varname>timer_procs</varname> (int)</title>
949                 <para>
950                         Number of timer processes to be started by module. Timer processes
951                         take care of checking expired records and synchronization with
952                         database. If set to 0, no dedicated timer is started, the one from
953                         core will be used.
954                 </para>
955                 <para>
956                 <emphasis>
957                         Default value is <quote>0</quote>.
958                 </emphasis>
959                 </para>
960                 <example>
961                 <title>Set <varname>timer_procs</varname> parameter</title>
962                 <programlisting format="linespecific">
963 ...
964 modparam("usrloc", "timer_procs", 4)
965 ...
966 </programlisting>
967                 </example>
968         </section>
969
970         <section id="usrloc.p.xavp_contact">
971                 <title><varname>xavp_contact</varname> (string)</title>
972                 <para>
973                 The name of XAVP storing the attributes per contact. They are saved
974                 in location record and restored at lookup. The tm module parameter
975                 <varname>xavp_contact</varname> must also be set to the same value to use the
976                 <varname>t_load_contacts</varname> and <varname>t_next_contacts</varname> functions.
977                 </para>
978                 <para>
979                 <emphasis>
980                         Default value is <quote>NULL</quote>.
981                 </emphasis>
982                 </para>
983                 <example>
984                 <title>Set <varname>xavp_contact</varname> parameter</title>
985                 <programlisting format="linespecific">
986 ...
987 modparam("tm|usrloc", "xavp_contact", "ulattrs")
988 ...
989 </programlisting>
990                 </example>
991         </section>
992
993         <section id="usrloc.p.db_ops_ruid">
994                 <title><varname>db_ops_ruid</varname> (int)</title>
995                 <para>
996                         If set to 1, database queries for update or delete are done using
997                         ruid value. If it is set to 0, the old style using aor, contact and
998                         call-id is done.
999                 </para>
1000                 <para>
1001                 <emphasis>
1002                         Default value is <quote>1</quote>.
1003                 </emphasis>
1004                 </para>
1005                 <example>
1006                 <title>Set <varname>db_ops_ruid</varname> parameter</title>
1007                 <programlisting format="linespecific">
1008 ...
1009 modparam("usrloc", "db_ops_ruid", 0)
1010 ...
1011 </programlisting>
1012                 </example>
1013         </section>
1014
1015         <section id="usrloc.p.handle_lost_tcp">
1016                 <title><varname>handle_lost_tcp</varname> (int)</title>
1017                 <para>
1018                         If set to 1, Kamailio will remove location records made via
1019                         TCP/TLS/WS/WSS transports when it looses corresponding tcp
1020             connections.  Does not currently work in DB-Only scheme.
1021                 </para>
1022                 <para>
1023                 <emphasis>
1024                         Default value is <quote>0</quote>.
1025                 </emphasis>
1026                 </para>
1027                 <example>
1028                 <title>Set <varname>handle_lost_tcp</varname> parameter</title>
1029                 <programlisting format="linespecific">
1030 ...
1031 modparam("usrloc", "handle_lost_tcp", 1)
1032 ...
1033 </programlisting>
1034                 </example>
1035         </section>
1036
1037         <section id="usrloc.p.close_expired_tcp">
1038                 <title><varname>close_expired_tcp</varname> (int)</title>
1039                 <para>
1040             If set to 1, Kamailio will close the TCP connection when a contact
1041             has expired, if the corresponding transport is TCP/TLS/WS/WSS.
1042         </para>
1043                 <para>
1044                 <emphasis>
1045                         Default value is <quote>0</quote>.
1046                 </emphasis>
1047                 </para>
1048                 <example>
1049                 <title>Set <varname>close_expired_tcp</varname> parameter</title>
1050                 <programlisting format="linespecific">
1051 ...
1052 modparam("usrloc", "close_expired_tcp", 1)
1053 ...
1054 </programlisting>
1055                 </example>
1056         </section>
1057
1058         <section id="usrloc.p.expires_type">
1059                 <title><varname>expires_type</varname> (int)</title>
1060                 <para>
1061                         If set to 1, &kamailio; expects to deal with BIGINT type on
1062                         database columns for expires and last modified values. It
1063                         allows to handle better the daylight time adjustments. If set
1064                         to 0, those columns are expected to be on default type
1065                         'DATETIME'. When it is 1, the database columns types have
1066                         to be changed manually to 'BIGINT'.
1067                 </para>
1068                 <para>
1069                 <emphasis>
1070                         Default value is <quote>0</quote>.
1071                 </emphasis>
1072                 </para>
1073                 <example>
1074                 <title>Set <varname>expires_type</varname> parameter</title>
1075                 <programlisting format="linespecific">
1076 ...
1077 modparam("usrloc", "expires_type", 1)
1078 ...
1079 </programlisting>
1080                 </example>
1081         </section>
1082
1083         <section id="usrloc.p.db_raw_fetch_type">
1084                 <title><varname>db_raw_fetch_type</varname> (int)</title>
1085                 <para>
1086                         This affect DB-only mode and controls what kind of
1087                         raw query is used to fetch the contacts from database for
1088                         specific needs (e.g., sending NAT keepalives). If it is set to 0,
1089                         then the common SQL query is used (working for MySQL, PostgreSQL,
1090                         ...). If it is set to 1, the query required by Oracle is used.
1091                 </para>
1092                 <para>
1093                 <emphasis>
1094                         Default value is <quote>0</quote>.
1095                 </emphasis>
1096                 </para>
1097                 <example>
1098                 <title>Set <varname>db_raw_fetch_type</varname> parameter</title>
1099                 <programlisting format="linespecific">
1100 ...
1101 modparam("usrloc", "db_raw_fetch_type", 1)
1102 ...
1103 </programlisting>
1104                 </example>
1105         </section>
1106
1107         <section id="usrloc.p.db_insert_null">
1108                 <title><varname>db_insert_null</varname> (int)</title>
1109                 <para>
1110                         If set to 1, the insert operation to database will add null values
1111                         in the statement. It has to be set to 1 for the database systems
1112                         that do not have table definitions that create automatically the
1113                         null fields (e.g., db_mongodb) for each stored record.
1114                 </para>
1115                 <para>
1116                         When set to 0, the fields that default to null are not
1117                         added to the DB insert statement if they don't have a different
1118                         value, making the query smaller.
1119                 </para>
1120                 <para>
1121                 <emphasis>
1122                         Default value is <quote>0</quote> (don't add null fields in insert
1123                         statement).
1124                 </emphasis>
1125                 </para>
1126                 <example>
1127                 <title>Set <varname>db_insert_null</varname> parameter</title>
1128                 <programlisting format="linespecific">
1129 ...
1130 modparam("usrloc", "db_insert_null", 1)
1131 ...
1132 </programlisting>
1133                 </example>
1134         </section>
1135
1136         <section id="usrloc.p.skip_remote_socket">
1137                 <title><varname>skip_remote_socket</varname> (int)</title>
1138                 <para>
1139                         If set to 1, Kamailio will skip location record when loading from
1140                         database, if socket value of the record does not in kamailio
1141                         listening socket list.
1142                 </para>
1143                 <para>
1144                 <emphasis>
1145                         Default value is <quote>0</quote>.
1146                 </emphasis>
1147                 </para>
1148                 <example>
1149                 <title>Set <varname>skip_remote_socket</varname> parameter</title>
1150                 <programlisting format="linespecific">
1151 ...
1152 modparam("usrloc", "skip_remote_socket", 1)
1153 ...
1154 </programlisting>
1155                 </example>
1156         </section>
1157
1158         <section id="usrloc.p.db_timer_clean">
1159                 <title><varname>db_timer_clean</varname> (int)</title>
1160                 <para>
1161                         Enable (1) or disable (0) cleaning of expired db records on
1162                         timer basis for db_mode WRITE-BACK and WRITE-THROUGH. It uses
1163                         the secondary timer process.
1164                 </para>
1165                 <para>
1166                 <emphasis>
1167                         Default value is <quote>0</quote>.
1168                 </emphasis>
1169                 </para>
1170                 <example>
1171                 <title>Set <varname>db_timer_clean</varname> parameter</title>
1172                 <programlisting format="linespecific">
1173 ...
1174 modparam("usrloc", "db_timer_clean", 1)
1175 ...
1176 </programlisting>
1177                 </example>
1178         </section>
1179
1180         <section id="usrloc.p.rm_expired_delay">
1181                 <title><varname>rm_expired_delay</varname> (int)</title>
1182                 <para>
1183                         Specify the number of seconds to delay the removal of expired
1184                         records. For now it works for DB_ONLY mode (db_mode=3).
1185                 </para>
1186                 <para>
1187                 <emphasis>
1188                         Default value is <quote>0</quote>.
1189                 </emphasis>
1190                 </para>
1191                 <example>
1192                 <title>Set <varname>rm_expired_delay</varname> parameter</title>
1193                 <programlisting format="linespecific">
1194 ...
1195 modparam("usrloc", "rm_expired_delay", 30)
1196 ...
1197 </programlisting>
1198                 </example>
1199         </section>
1200
1201         <section id="usrloc.p.server_id_filter">
1202                 <title><varname>server_id_filter</varname> (int)</title>
1203                 <para>
1204                         Enable (1) or disable (0) filter records by server_id on load and during cleaning of expired db records.
1205                         It could be usefull when you want to use the same location table for several kamailio instances which are configured to work in db_mode=1 or db_mode=2 (cache modes).
1206                         Otherwise one instance of proxy cleans records made by another proxy and that breaks its cache.
1207                 </para>
1208                 <para>
1209                 <emphasis>
1210                         Default value is <quote>0</quote>.
1211                 </emphasis>
1212                 </para>
1213                 <example>
1214                 <title>Set <varname>server_id_filter</varname> parameter</title>
1215                 <programlisting format="linespecific">
1216 ...
1217 modparam("usrloc", "server_id_filter", 1)
1218 ...
1219 </programlisting>
1220                 </example>
1221         </section>
1222
1223         <section id="usrloc.p.version_table">
1224                 <title><varname>version_table</varname> (integer)</title>
1225                 <para>
1226                 If set to 0, the module will skip checking the version
1227                 for location table.
1228                 </para>
1229                 <para>
1230                 Default value is <quote>1 (check for table version)</quote>.
1231                 </para>
1232                 <example>
1233                 <title><varname>version_table</varname> parameter usage</title>
1234                 <programlisting format="linespecific">
1235 ...
1236 modparam("usrloc", "version_table", 0)
1237 ...
1238                 </programlisting>
1239                 </example>
1240         </section>
1241
1242         </section>
1243
1244         <section>
1245         <title>RPC Commands</title>
1246
1247         <section id="usrloc.r.dump">
1248                 <title>
1249                 <function moreinfo="none">ul.dump</function>
1250                 </title>
1251                 <para>
1252                 Dumps the content of the location table
1253                 </para>
1254                 <para>Parameters: </para>
1255                 <itemizedlist>
1256                         <listitem><para>
1257                                 None.
1258                         </para></listitem>
1259                 </itemizedlist>
1260         </section>
1261         <section id="usrloc.r.lookup">
1262                 <title>
1263                 <function moreinfo="none">ul.lookup table AOR</function>
1264                 </title>
1265                 <para>
1266                 Looks up the contents of an AOR entry in the location table
1267                 </para>
1268                 <para>Parameters: </para>
1269                 <itemizedlist>
1270                         <listitem><para>
1271                                 <emphasis>table name</emphasis> - table where the AOR
1272                                 resides (Ex: location).
1273                         </para></listitem>
1274                         <listitem><para>
1275                                 <emphasis>AOR</emphasis> - user AOR in username[@domain]
1276                                 format (domain must be supplied only if use_domain option
1277                                 is on).
1278                         </para></listitem>
1279                 </itemizedlist>
1280         </section>
1281         <section id="usrloc.r.rm">
1282                 <title>
1283                 <function moreinfo="none">ul.rm table AOR</function>
1284                 </title>
1285                 <para>
1286                 Deletes an entire AOR record (including its contacts).
1287                 </para>
1288                 <para>Parameters: </para>
1289                 <itemizedlist>
1290                         <listitem><para>
1291                                 <emphasis>table name</emphasis> - table where the AOR
1292                                 resides (Ex: location).
1293                         </para></listitem>
1294                         <listitem><para>
1295                                 <emphasis>AOR</emphasis> - user AOR in username[@domain]
1296                                 format (domain must be supplied only if use_domain option
1297                                 is on).
1298                         </para></listitem>
1299                 </itemizedlist>
1300         </section>
1301         <section id="usrloc.r.rm_contact">
1302                 <title>
1303                 <function moreinfo="none">ul.rm_contact table AOR contact</function>
1304                 </title>
1305                 <para>
1306                 Deletes a contact from an AOR record.
1307                 </para>
1308                 <para>Parameters: </para>
1309                 <itemizedlist>
1310                         <listitem><para>
1311                                 <emphasis>table name</emphasis> - table where the AOR
1312                                 is removed from (Ex: location).
1313                         </para></listitem>
1314                         <listitem><para>
1315                                 <emphasis>AOR</emphasis> - user AOR in username[@domain]
1316                                 format (domain must be supplied only if use_domain option
1317                                 is on).
1318                         </para></listitem>
1319                         <listitem><para>
1320                                 <emphasis>contact</emphasis> - exact contact to be removed
1321                         </para></listitem>
1322                 </itemizedlist>
1323         </section>
1324         <section id="usrloc.r.flush">
1325                 <title>
1326                 <function moreinfo="none">ul.flush</function>
1327                 </title>
1328                 <para>
1329                 Triggers the flush of USRLOC memory cache into DB.
1330                 </para>
1331         </section>
1332         <section id="usrloc.r.add">
1333                 <title>
1334                 <function moreinfo="none">ul.add</function>
1335                 </title>
1336                 <para>
1337                 Adds a new contact for an user AOR.
1338                 </para>
1339                 <para>Parameters: </para>
1340                 <itemizedlist>
1341                         <listitem><para>
1342                                 <emphasis>table name</emphasis> - table where the contact
1343                                 will be added (Ex: location).
1344                         </para></listitem>
1345                         <listitem><para>
1346                                 <emphasis>AOR</emphasis> - user AOR in username[@domain]
1347                                 format (domain must be supplied only if use_domain option
1348                                 is on).
1349                         </para></listitem>
1350                         <listitem><para>
1351                                 <emphasis>contact</emphasis> - contact string to be added
1352                         </para></listitem>
1353                         <listitem><para>
1354                                 <emphasis>expires</emphasis> - expires value of the contact
1355                         </para></listitem>
1356                         <listitem><para>
1357                                 <emphasis>Q</emphasis> - Q value of the contact
1358                         </para></listitem>
1359                         <listitem><para>
1360                                 <emphasis>path</emphasis> value with the Path vector (use '0'
1361                                 or '.' if it should not be set)
1362                         </para></listitem>
1363                         <listitem><para>
1364                                 <emphasis>flags</emphasis> - internal USRLOC flags of the
1365                                 contact
1366                         </para></listitem>
1367                         <listitem><para>
1368                                 <emphasis>cflags</emphasis> - per branch flags of the
1369                                 contact
1370                         </para></listitem>
1371                         <listitem><para>
1372                                 <emphasis>methods</emphasis> - mask with supported requests
1373                                 of the contact
1374                         </para></listitem>
1375                         <listitem><para>
1376                                 <emphasis>received</emphasis> (optional) value with the
1377                                 received-from address (source address) (use '0'
1378                                 or '.' if it should not be set). Format:
1379                                 sip:srcip:srcport;transport=abc
1380                         </para></listitem>
1381                         <listitem><para>
1382                                 <emphasis>socket</emphasis> (optional) value with the local
1383                                 socket address (use '0' or '.' if it should not be set). Format:
1384                                 proto:localip:localport
1385                         </para></listitem>
1386                 </itemizedlist>
1387                 <para>
1388                         Note: the position of parameters is relevant, in the case of
1389                         optional parameters, use '0' or '.' for parameters that should not
1390                         be set which are positioned before any parameter that has to be set.
1391                 </para>
1392         </section>
1393
1394         <section id="usrloc.r.db_users">
1395                 <title>
1396                 <function moreinfo="none">ul.db_users</function>
1397                 </title>
1398                 <para>
1399                 Tell number of different users (AoRs) in a location table that have unexpired contacts.
1400                 </para>
1401                 <para>Parameters: </para>
1402                 <itemizedlist>
1403                         <listitem><para>
1404                                 <emphasis>table name</emphasis> - location table where the users are looked for, for example, location.
1405                         </para></listitem>
1406                 </itemizedlist>
1407         </section>
1408
1409         <section id="usrloc.r.db_contacts">
1410                 <title>
1411                 <function moreinfo="none">ul.db_contacts</function>
1412                 </title>
1413                 <para>
1414                 Tell number of unexpired contacts in a location table.
1415                 </para>
1416                 <para>Parameters: </para>
1417                 <itemizedlist>
1418                         <listitem><para>
1419                                 <emphasis>table name</emphasis> - location table where the contacts are looked for, for example, location.
1420                         </para></listitem>
1421                 </itemizedlist>
1422         </section>
1423
1424         <section id="usrloc.r.db_expired_contacts">
1425                 <title>
1426                 <function moreinfo="none">ul.db_expired_contacts</function>
1427                 </title>
1428                 <para>
1429                 Tell number of expired contacts in a location table.
1430                 </para>
1431                 <para>Parameters: </para>
1432                 <itemizedlist>
1433                         <listitem><para>
1434                                 <emphasis>table name</emphasis> - location table where the contacts are looked for, for example, location.
1435                         </para></listitem>
1436                 </itemizedlist>
1437         </section>
1438
1439         </section><!-- RPC commands -->
1440
1441
1442         <section>
1443                 <title>Statistics</title>
1444                 <para>
1445                 Exported statistics are listed in the next sections.
1446                 </para>
1447                 <section id="usrloc.s.users">
1448                 <title>users</title>
1449                         <para>
1450                         Number of AOR existing in the USRLOC memory cache for that domain
1451                         - can not be reset; this statistic will be register for each
1452                         used domain (Ex: location).
1453                         </para>
1454                 </section>
1455                 <section id="usrloc.s.contacts">
1456                 <title>contacts</title>
1457                         <para>
1458                         Number of contacts existing in the USRLOC memory cache for that
1459                         domain - can not be reset; this statistic will be register for
1460                         each used domain (Ex: location).
1461                         </para>
1462                 </section>
1463                 <section id="usrloc.s.expires">
1464                 <title>expires</title>
1465                         <para>
1466                         Total number of expired contacts for that domain - can be reset;
1467                          this statistic will be register for each used domain
1468                         (Ex: location).
1469                         </para>
1470                 </section>
1471                 <section id="usrloc.s.registered_users">
1472                 <title>registered_users</title>
1473                         <para>
1474                         Total number of AOR existing in the USRLOC memory cache for all
1475                         domains - can not be reset.
1476                         </para>
1477                 </section>
1478         </section>
1479
1480
1481 </chapter>
1482