htable: docs - rephrased info for db_expires to clarify its purpose
[sip-router] / src / modules / htable / doc / htable_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 module adds a hash table container to the configuration language. The
20                 hash table is stored in shared memory and the access to it can be
21                 done via pseudo-variables: $sht(htname=&gt;name). The module supports
22                 definition of many hash tables and can load values at startup from
23                 a database table.
24         </para>
25         <para>
26                 A typical use case for the SIP server is to implement a cache system
27                 in configuration file - if a value is not found in hash table, load
28                 it from database and store it in hash table so next time the access to
29                 it is very fast. In the definition of the table you can define the
30                 default expiration time of cached items. The expiration time can
31                 be adjusted per item via assignment operation at runtime.
32         </para>
33         <para>
34                 Replication between multiple servers is performed automatically (if
35                 enabled) via the DMQ module.
36         </para>
37         <para>
38                 You can read more about hash tables at:
39                 http://en.wikipedia.org/wiki/Hash_table.
40         </para>
41         <para>
42                 The <quote>name</quote> can be a static string or can include pseudo-
43                 variables that will be replaced at runtime.
44         </para>
45         <example>
46                 <title>Accessing $sht(htname=&gt;key)</title>
47         <programlisting format="linespecific">
48 ...
49 modparam("htable", "htable", "a=&gt;size=8;")
50 ...
51 $sht(a=&gt;test) = 1;
52 $sht(a=&gt;$ci::srcip) = $si;
53 ...
54 </programlisting>
55         </example>
56         <para>
57                 The next example shows a way to protect against dictionary attacks. If
58                 someone fails to authenticate 3 times, it is forbidden for 15 minutes.
59                 Authentication against database is expensive as it does a select
60                 on the <quote>subscriber</quote> table. By disabling the DB auth for 15 minutes,
61                 resources on the server are saved and time to discover the password is increased
62                 substantially. Additional alerting can be done by writing a message
63                 to syslog or sending email, etc.
64         </para>
65         <para>
66                 To implement the logic, two hash table variables are used: one counting
67                 the failed authentications per user and one for storing the time of the
68                 last authentication attempt. To ensure a unique name per user, the
69                 hash table uses a combination of authentication username and text
70                 <quote>::auth_count</quote> and <quote>::last_auth</quote>.
71         </para>
72         <example>
73         <title>Dictionary attack limitation</title>
74         <programlisting format="linespecific">
75 ...
76 modparam("htable", "htable", "a=&gt;size=8;")
77 ...
78 if(is_present_hf("Authorization"))
79 {
80     if($sht(a=&gt;$au::auth_count)==3)
81     {
82                 $var(exp) = $Ts - 900;
83         if($sht(a=&gt;$au::last_auth) &gt; $var(exp))
84         {
85             sl_send_reply("403", "Try later");
86             exit;
87         } else {
88             $sht(a=&gt;$au::auth_count) = 0;
89         }
90     }
91     if(!www_authenticate("$td", "subscriber"))
92     {
93         switch ($retcode) {
94             case -1:
95                 sl_send_reply("403", "Forbidden");
96             exit;
97             case -2:
98                 if($sht(a=&gt;$au::auth_count) == $null)
99                     $sht(a=&gt;$au::auth_count) = 0;
100                 $sht(a=&gt;$au::auth_count) = $sht(a=&gt;$au::auth_count) + 1;
101                 if($sht(a=&gt;$au::auth_count) == 3)
102                     xlog("auth failed 3rd time - src ip: $si\n");
103                 $sht(a=&gt;$au::last_auth) = $Ts;
104             break;
105         }
106         www_challenge("$td"/*realm*/,"0"/*qop*/);
107         exit;
108     }
109     $sht(a=&gt;$au::auth_count) = 0;
110 } else {
111     www_challenge("$td","0");
112     exit;
113 }
114 ...
115 </programlisting>
116         </example>
117         <para>
118                 The module also provides a way to store multiple values for a single key.
119                 This is emulated by storing individual keys as 'key_name[n]', where n is
120                 incremented for each key. The total number of keys is stored in a
121                 dedicated key, by default: 'key_name::size'.
122         </para>
123         <para>
124                 The array is built when the table is loaded in memory and afterwards all
125                 the keys are treated as individual keys.
126                 If a particular entry in the array is deleted, it is the administrator's
127                 responsibility to update the size of the array and any other elements
128                 (if required).
129         </para>
130         <example>
131         <title>Storing array values</title>
132         <programlisting format="linespecific">
133 # Example of dbtext with multiple keys
134 $ cat /usr/local/etc/kamailio/dbtext/htable
135 1:key:1:0:value3:0
136 2:key:1:0:value2:0
137 3:key:1:0:value1:0
138
139 # The array key will be loaded in memory in the following format:
140 $ kamcmd htable.dump htable
141 {
142         entry: 35
143         size: 1
144         slot: {
145                 item: {
146                         name: key[0]
147                         value: value1
148                 }
149         }
150 }
151 {
152         entry: 50
153         size: 1
154         slot: {
155                 item: {
156                         name: key::size
157                         value: 3
158                 }
159         }
160 }
161 {
162         entry: 67
163         size: 1
164         slot: {
165                 item: {
166                         name: key[1]
167                         value: value2
168                 }
169         }
170 }
171 {
172         entry: 227
173         size: 1
174         slot: {
175                 item: {
176                         name: key[2]
177                         value: value3
178                 }
179         }
180 }
181
182 # Now let's delete a particular entry in the array: key[0].
183 $ kamcmd htable.delete htable key[0]
184
185 # The array key will look like this after a key was deleted:
186 $ kamcmd htable.dump htable
187 {
188         entry: 50
189         size: 1
190         slot: {
191                 item: {
192                         name: key::size
193                         value: 3
194                 }
195         }
196 }
197 {
198         entry: 67
199         size: 1
200         slot: {
201                 item: {
202                         name: key[1]
203                         value: value2
204                 }
205         }
206 }
207 {
208         entry: 227
209         size: 1
210         slot: {
211                 item: {
212                         name: key[2]
213                         value: value3
214                 }
215         }
216 }
217 </programlisting>
218         </example>
219
220         </section>
221         <section>
222         <title>Dependencies</title>
223         <section>
224                 <title>&kamailio; Modules</title>
225                 <para>
226                 The following modules must be loaded before this module:
227                         <itemizedlist>
228                         <listitem>
229                         <para>
230                                 <emphasis>If DMQ replication is enabled, the DMQ module must be loaded first.</emphasis>.
231                         </para>
232                         </listitem>
233                         </itemizedlist>
234                 </para>
235         </section>
236         <section>
237                 <title>External Libraries or Applications</title>
238                 <para>
239                 The following libraries or applications must be installed before running
240                 &kamailio; with this module loaded:
241                         <itemizedlist>
242                         <listitem>
243                         <para>
244                                 <emphasis>None</emphasis>.
245                         </para>
246                         </listitem>
247                         </itemizedlist>
248                 </para>
249         </section>
250         <section>
251                 <title>Loading from database</title>
252                 <para>
253                 The module is able to load values in a hash table at startup upon
254                 providing a DB URL and table name.
255                 </para>
256                 <para>
257                         The structure of the table must contain:
258                 </para>
259                         <itemizedlist>
260                         <listitem>
261                         <para>
262                                 <emphasis>key name</emphasis> - string containing the name of
263                                 the key.
264                         </para>
265                         </listitem>
266                         <listitem>
267                         <para>
268                                 <emphasis>key type</emphasis> - the type of the key
269                         </para>
270                         <itemizedlist>
271                                 <listitem>
272                                 <para>
273                                         <emphasis>0</emphasis> - simple key - the key is added
274                                         as 'key_name'.
275                                 </para>
276                                 </listitem>
277                                 <listitem>
278                                 <para>
279                                         <emphasis>1</emphasis> - array key - the key is added
280                                         as 'key_name[n]' - n is incremented for each key with this
281                                         name to build an array in hash table.  In addition, an additional
282                                         key is built to hold the total number of key in the array,
283                                         by default key_name::size (see array_size_suffix parameter).
284                                 </para>
285                                 </listitem>
286                         </itemizedlist>
287                         </listitem>
288                         <listitem>
289                         <para>
290                                 <emphasis>value type</emphasis> - the type of the key value
291                         </para>
292                         <itemizedlist>
293                                 <listitem>
294                                 <para>
295                                         <emphasis>0</emphasis> - value is string.
296                                 </para>
297                                 </listitem>
298                                 <listitem>
299                                 <para>
300                                         <emphasis>1</emphasis> - value is integer.
301                                 </para>
302                                 </listitem>
303                         </itemizedlist>
304                         </listitem>
305                         <listitem>
306                         <para>
307                                 <emphasis>key value</emphasis> - string containing the value of
308                                 the key.
309                         </para>
310                         </listitem>
311                         </itemizedlist>
312         </section>
313
314         </section>
315         <section>
316         <title>Parameters</title>
317         <section id="htable.p.htable">
318                 <title><varname>htable</varname> (str)</title>
319                 <para>
320                 The definition of a hash table. The value of the parameter may have the
321                 following format:
322                 </para>
323                 <itemizedlist>
324                 <listitem>
325                 <para>
326                 "htname=&gt;size=_number_;autoexpire=_number_;dbtable=_string_"
327                 </para>
328                 </listitem>
329                 </itemizedlist>
330                 <para>
331                         The parameter can be set multiple times to get more hash tables in
332                         same configuration file.
333                 </para>
334                 <itemizedlist>
335                 <listitem>
336                 <para>
337                         <emphasis>htname</emphasis> - string specifying the name of
338                         the hash table. This string is used by <emphasis>$sht(...)</emphasis>
339                         to refer to the hash table.
340                 </para>
341                 </listitem>
342                 <listitem>
343                 <para>
344                         <emphasis>size</emphasis> - number specifying the size of hash
345                         table.  Larger value means less collisions. The number of entries
346                         (aka slots or buckets) in the table is 2^size. The possible range
347                         for this value is from 2 to 31, smaller or larger values will be
348                         increased to 3 (8 slots) or decreased to 14 (16384 slots).
349                 </para>
350                 </listitem>
351                 <listitem>
352                 <para>
353                         <emphasis>autoexpire</emphasis> -time in seconds to delete an item
354                         from a hash table if no update was done to it. If is missing or set
355                         to 0, the items won't expire.
356                 </para>
357                 </listitem>
358                 <listitem>
359                 <para>
360                         <emphasis>dbtable</emphasis> - name of database to be loaded at
361                         startup in hash table. If empty or missing, no data will be loaded.
362                 </para>
363                 </listitem>
364                 <listitem>
365                 <para>
366                         <emphasis>cols</emphasis> - the column names of the database table.
367                         They must be enclosed in quotes in order to form a valid SIP
368                         parameter value and be separated by comma. The first column
369                         corresponds to key_name. When specified, there must be at least
370                         two columns. If this attribute is not specified, then the global
371                         module parameters for column names are used. If more than one
372                         value columns are specified, the hash table will pack the column
373                         values in a comma separated string, which will be associated
374                         with the key (string transformation {s.select,...} can be
375                         used in configuration file to extract a specific column value).
376                         When cols attribute is present, writing back to database table
377                         is disabled.
378                         </para>
379                 </listitem>
380                 <listitem>
381                 <para>
382                         <emphasis>dbmode</emphasis> - if set to 1, the content of hash
383                         table is written to database table when the SIP server is stopped
384                         (i.e., ensure persistency over restarts). Default value is 0 (no
385                         write back to db table).
386                 </para>
387                 </listitem>
388                 <listitem>
389                 <para>
390                         <emphasis>initval</emphasis> - the integer value to be returned
391                         instead of $null when a requested key is not set.
392                 </para>
393                 </listitem>
394                 <listitem>
395                 <para>
396                         <emphasis>updateexpire</emphasis> - if set to 1 (default), the time until
397                         expiration of an item is reset when that item is updated.  Certain uses of
398                         htable may dictate that updates should not reset the expiration timeout, however,
399                         in which case this attribute can be set to 0.
400                 </para>
401                 </listitem>
402                 <listitem>
403                 <para>
404                         <emphasis>dmqreplicate</emphasis> - if set to 1, any actions (set, update, delete
405                         etc.) performed upon entries in this table will be replicated to other nodes (htable
406                         peers). Please note, module parameter <quote>enable_dmq</quote> must also be set in
407                         order for this to apply (see below). Default is 0 (no replication).
408                 </para>
409                 </listitem>
410                 </itemizedlist>
411                 <para>
412                 <emphasis>
413                         Default value is NULL.
414                 </emphasis>
415                 </para>
416                 <example>
417                 <title>Set <varname>hash_size</varname> parameter</title>
418                 <programlisting format="linespecific">
419 ...
420 modparam("htable", "htable", "a=&gt;size=4;autoexpire=7200;dbtable=htable_a;")
421 modparam("htable", "htable", "b=&gt;size=5;")
422 modparam("htable", "htable", "c=&gt;size=4;autoexpire=7200;initval=1;dmqreplicate=1;")
423 ...
424 </programlisting>
425                 </example>
426         </section>
427         <section id="htable.p.db_url">
428                 <title><varname>db_url</varname> (str)</title>
429                 <para>
430                         The <acronym>URL</acronym> to connect to database for loading values in hash
431                         table at start up.
432                 </para>
433                 <para>
434                 <emphasis>
435                         Default value is NULL (do not connect).
436                 </emphasis>
437                 </para>
438                 <example>
439                 <title>Set <varname>db_url</varname> parameter</title>
440                 <programlisting format="linespecific">
441 ...
442 modparam("htable", "db_url", "&defaultdb;")
443 ...
444 </programlisting>
445                 </example>
446         </section>
447         <section id="htable.p.key_name_column">
448                 <title><varname>key_name_column</varname> (str)</title>
449                 <para>
450                         The name of the column containing the hash table key name.
451                 </para>
452                 <para>
453                 <emphasis>
454                         Default value is 'key_name'.
455                 </emphasis>
456                 </para>
457                 <example>
458                 <title>Set <varname>key_name_column</varname> parameter</title>
459                 <programlisting format="linespecific">
460 ...
461 modparam("htable", "key_name_column", "kname")
462 ...
463 </programlisting>
464                 </example>
465         </section>
466         <section id="htable.p.key_type_column">
467                 <title><varname>key_type_column</varname> (str)</title>
468                 <para>
469                         The name of the column containing the hash table key type.
470                 </para>
471                 <para>
472                 <emphasis>
473                         Default value is 'key_type'.
474                 </emphasis>
475                 </para>
476                 <example>
477                 <title>Set <varname>key_type_column</varname> parameter</title>
478                 <programlisting format="linespecific">
479 ...
480 modparam("htable", "key_type_column", "ktype")
481 ...
482 </programlisting>
483                 </example>
484         </section>
485         <section id="htable.p.value_type_column">
486                 <title><varname>value_type_column</varname> (str)</title>
487                 <para>
488                         The name of the column containing the hash table value type.
489                 </para>
490                 <para>
491                 <emphasis>
492                         Default value is 'value_type'.
493                 </emphasis>
494                 </para>
495                 <example>
496                 <title>Set <varname>value_type_column</varname> parameter</title>
497                 <programlisting format="linespecific">
498 ...
499 modparam("htable", "value_type_column", "vtype")
500 ...
501 </programlisting>
502                 </example>
503         </section>
504         <section id="htable.p.key_value_column">
505                 <title><varname>key_value_column</varname> (str)</title>
506                 <para>
507                         The name of the column containing hash table key value.
508                 </para>
509                 <para>
510                 <emphasis>
511                         Default value is 'key_value'.
512                 </emphasis>
513                 </para>
514                 <example>
515                 <title>Set <varname>key_value_column</varname> parameter</title>
516                 <programlisting format="linespecific">
517 ...
518 modparam("htable", "key_value_column", "kvalue")
519 ...
520 </programlisting>
521                 </example>
522         </section>
523         <section id="htable.p.expires_column">
524                 <title><varname>expires_column</varname> (str)</title>
525                 <para>
526                         The name of the column containing the expires value.
527                 </para>
528                 <para>
529                 <emphasis>
530                         Default value is 'expires'.
531                 </emphasis>
532                 </para>
533                 <example>
534                 <title>Set <varname>expires_column</varname> parameter</title>
535                 <programlisting format="linespecific">
536 ...
537 modparam("htable", "expires_column", "expiry")
538 ...
539 </programlisting>
540                 </example>
541         </section>
542         <section id="htable.p.array_size_suffix">
543                 <title><varname>array_size_suffix</varname> (str)</title>
544                 <para>
545                         The suffix to be added to store the number of items in an
546                         array (see key type).
547                 </para>
548                 <para>
549                 <emphasis>
550                         Default value is '::size'.
551                 </emphasis>
552                 </para>
553                 <example>
554                 <title>Set <varname>array_size_suffix</varname> parameter</title>
555                 <programlisting format="linespecific">
556 ...
557 modparam("htable", "array_size_suffix", "-count")
558 ...
559 </programlisting>
560                 </example>
561         </section>
562         <section id="htable.p.fetch_rows">
563                 <title><varname>fetch_rows</varname> (integer)</title>
564                 <para>
565                 How many rows to fetch at once from database.
566                 </para>
567                 <para>
568                 <emphasis>
569                         Default value is 100.
570                 </emphasis>
571                 </para>
572                 <example>
573                 <title>Set <varname>fetch_rows</varname> parameter</title>
574                 <programlisting format="linespecific">
575 ...
576 modparam("htable", "fetch_rows", 1000)
577 ...
578 </programlisting>
579                 </example>
580         </section>
581         <section id="htable.p.timer_interval">
582                 <title><varname>timer_interval</varname> (integer)</title>
583                 <para>
584                 Interval in seconds to check for expired htable values.
585                 </para>
586                 <para>
587                 <emphasis>
588                         Default value is 20.
589                 </emphasis>
590                 </para>
591                 <example>
592                 <title>Set <varname>timer_interval</varname> parameter</title>
593                 <programlisting format="linespecific">
594 ...
595 modparam("htable", "timer_interval", 10)
596 ...
597 </programlisting>
598                 </example>
599         </section>
600         <section id="htable.p.db_expires">
601                 <title><varname>db_expires</varname> (integer)</title>
602                 <para>
603                         If set to 1, the module loads/saves the value for expire of
604                         the items in hash table from/to database. It applies only to hash
605                         tables that have the auto-expires attribute defined. If set to 0,
606                         only the key name and the value are loaded, the expires for each
607                         item being set to 0.
608                 </para>
609                 <para>
610                         Note that the module is not reloading automatically the items from
611                         database when they expire, the reloading can be done only via RPC
612                         command.
613                 </para>
614                 <para>
615                 <emphasis>
616                         Default value is 0.
617                 </emphasis>
618                 </para>
619                 <example>
620                 <title>Set <varname>db_expires</varname> parameter</title>
621                 <programlisting format="linespecific">
622 ...
623 modparam("htable", "db_expires", 1)
624 ...
625 </programlisting>
626                 </example>
627         </section>
628         <section id="htable.p.enable_dmq">
629                 <title><varname>enable_dmq</varname> (integer)</title>
630                 <para>
631                         If set to 1, will enable DMQ replication of actions performed upon
632                         entries in all tables having "dmqreplicate" parameter set. Any update
633                         action performed via pseudo-variables and RPC commands will be
634                         repeated on all other nodes. Therefore, it is important to ensure the
635                         table definition (size, autoexpire etc.) is identical across all instances.
636                 </para>
637                 <para>
638                 <emphasis>
639                         Important: If this parameter is enabled, the DMQ module must be loaded first - otherwise, startup will fail.
640                 </emphasis>
641                 </para>
642                 <para>
643                         Currently, values are not replicated on load from DB as it is expected
644                         that in these cases, all servers will load their values from the same DB.
645                 </para>
646                 <para>
647                 <emphasis>
648                         Default value is 0.
649                 </emphasis>
650                 </para>
651                 <example>
652                 <title>Set <varname>enable_dmq</varname> parameter</title>
653                 <programlisting format="linespecific">
654 ...
655 modparam("htable", "enable_dmq", 1)
656 ...
657 </programlisting>
658                 </example>
659         </section>
660         <section id="htable.p.dmq_init_sync">
661                 <title><varname>dmq_init_sync</varname> (integer)</title>
662                 <para>
663                         If set to 1, will request synchronization from other nodes at startup. It applies
664                         to all tables having the "dmqreplicate" parameter set. As above, it is important to 
665                         ensure the definition (size, autoexpire etc.) of replicated tables is identical 
666                         across all instances.
667                 </para>
668                 <para>
669                 <emphasis>
670                         Default value is 0.
671                 </emphasis>
672                 </para>
673                 <example>
674                 <title>Set <varname>dmq_init_sync</varname> parameter</title>
675                 <programlisting format="linespecific">
676 ...
677 modparam("htable", "dmq_init_sync", 1)
678 ...
679 </programlisting>
680                 </example>
681         </section>
682         <section id="htable.p.timer_procs">
683                 <title><varname>timer_procs</varname> (integer)</title>
684                 <para>
685                         If set to 1 or greater, the module will create its own timer
686                         processes to scan for expired items in hash tables. If set to zero,
687                         it will use the core timer for this task. Set it to 1 if you store
688                         a lot of items with autoexpire property.
689                 </para>
690                 <para>
691                 <emphasis>
692                         Default value is 0.
693                 </emphasis>
694                 </para>
695                 <example>
696                 <title>Set <varname>timer_procs</varname> parameter</title>
697                 <programlisting format="linespecific">
698 ...
699 modparam("htable", "timer_procs", 4)
700 ...
701 </programlisting>
702                 </example>
703         </section>
704         <section id="htable.p.event_callback">
705                 <title><varname>event_callback</varname> (str)</title>
706                 <para>
707                         The name of the function in the kemi configuration file (embedded
708                         scripting language such as Lua, Python, ...) to be executed instead
709                         of event_route[...] blocks.
710                 </para>
711                 <para>
712                         The function receives a string parameter with the name of the event,
713                         the values can be: 'htable:mod-init', 'htable:expired:htname'
714                         ('htname' being the name of hash table).
715                 </para>
716                 <para>
717                 <emphasis>
718                         Default value is 'empty' (no function is executed for events).
719                 </emphasis>
720                 </para>
721                 <example>
722                 <title>Set <varname>event_callback</varname> parameter</title>
723                 <programlisting format="linespecific">
724 ...
725 modparam("htable", "event_callback", "ksr_htable_event")
726 ...
727 -- event callback function implemented in Lua
728 function ksr_htable_event(evname)
729         KSR.info("===== htable module triggered event: " .. evname .. "\n");
730         return 1;
731 end
732 ...
733 </programlisting>
734                 </example>
735         </section>
736         <section id="htable.p.event_callback_mode">
737                 <title><varname>event_callback_mode</varname> (int)</title>
738                 <para>
739                         Control when event_route[htable:init] is executed: 0 - after all
740                         modules were initialized; 1 - in first worker process.
741                 </para>
742                 <para>
743                         Set it to 1 if used in a KEMI script or when needing to use database
744                         (e.g., via sqlops) inside event_route[htable:init].
745                 </para>
746                 <para>
747                 <emphasis>
748                         Default value is 0.
749                 </emphasis>
750                 </para>
751                 <example>
752                 <title>Set <varname>event_callback_mode</varname> parameter</title>
753                 <programlisting format="linespecific">
754 ...
755 modparam("htable", "event_callback_mode", 1)
756 ...
757 </programlisting>
758                 </example>
759         </section>
760         </section>
761         <section>
762         <title>Functions</title>
763         <section id="htable.f.sht_print">
764                 <title>
765                 <function moreinfo="none">sht_print()</function>
766                 </title>
767                 <para>
768                         Dump content of hash table to L_ERR log level. Intended for debug
769                         purposes.
770                 </para>
771                 <para>
772                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
773                         ONREPLY_ROUTE, BRANCH_ROUTE.
774                 </para>
775                 <example>
776                 <title><function>sht_print</function> usage</title>
777                 <programlisting format="linespecific">
778 ...
779 sht_print();
780 ...
781 </programlisting>
782                 </example>
783         </section>
784         <section id="htable.f.sht_rm">
785                 <title>
786                 <function moreinfo="none">sht_rm(htname, itname)</function>
787                 </title>
788                 <para>
789                         Delete the item with the name 'itname' from hash table 'htname'.
790                         This API function equivaluent to '$sht(htname=&gt;itname) = $null'.
791                 </para>
792                 <para>
793                         This function can be used from ANY_ROUTE.
794                 </para>
795                 <example>
796                 <title><function>sht_rm</function> usage</title>
797                 <programlisting format="linespecific">
798 ...
799 sht_rm("ha", "test"");
800 ...
801 </programlisting>
802                 </example>
803         </section>
804         <section id="htable.f.sht_rm_name_re">
805                 <title>
806                 <function moreinfo="none">sht_rm_name_re(htable=>regexp)</function>
807                 </title>
808                 <para>
809                         Delete all entries in the htable that match the name against
810                         regular expression.
811                 </para>
812                 <para>
813                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
814                         ONREPLY_ROUTE, BRANCH_ROUTE.
815                 </para>
816                 <example>
817                 <title><function>sht_rm_name_re</function> usage</title>
818                 <programlisting format="linespecific">
819 ...
820 sht_rm_name_re("ha=>.*");
821 ...
822 </programlisting>
823                 </example>
824         </section>
825         <section id="htable.f.sht_rm_value_re">
826                 <title>
827                 <function moreinfo="none">sht_rm_value_re(htable=>regexp)</function>
828                 </title>
829                 <para>
830                         Delete all entries in the htable that match the value against
831                         regular expression.
832                 </para>
833                 <para>
834                         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
835                         ONREPLY_ROUTE, BRANCH_ROUTE.
836                 </para>
837                 <example>
838                 <title><function>sht_rm_value_re</function> usage</title>
839                 <programlisting format="linespecific">
840 ...
841 sht_rm_value_re("ha=>.*");
842 ...
843 </programlisting>
844                 </example>
845         </section>
846         <section id="htable.f.sht_rm_name">
847                 <title>
848                 <function moreinfo="none">sht_rm_name(htable, op, val)</function>
849                 </title>
850                 <para>
851                         Delete all entries in the htable that match the name against
852                         the val parameter.
853                 </para>
854                 <para>
855                         The op parameter can be:
856                 </para>
857                 <itemizedlist>
858                 <listitem>
859                 <para>
860                         <emphasis>re</emphasis> - match the val parameter as regular
861                         expression.
862                 </para>
863                 </listitem>
864                 <listitem>
865                 <para>
866                         <emphasis>sw</emphasis> - match the val parameter as 'starts
867                         with'.
868                 </para>
869                 </listitem>
870                 </itemizedlist>
871                 <para>
872                         All parameters can be static strings or contain variables.
873                 </para>
874                 <para>
875                         This function can be used from ANY_ROUTE.
876                 </para>
877                 <example>
878                 <title><function>sht_rm_name</function> usage</title>
879                 <programlisting format="linespecific">
880 ...
881 sht_rm_name("ha", "re", ".*");
882 ...
883 </programlisting>
884                 </example>
885         </section>
886         <section id="htable.f.sht_rm_value">
887                 <title>
888                 <function moreinfo="none">sht_rm_value(htable, op, val)</function>
889                 </title>
890                 <para>
891                         Delete all entries in the htable that match the value against
892                         the val parameter.
893                 </para>
894                 <para>
895                         The op parameter can be:
896                 </para>
897                 <itemizedlist>
898                 <listitem>
899                 <para>
900                         <emphasis>re</emphasis> - match the val parameter as regular
901                         expression.
902                 </para>
903                 </listitem>
904                 <listitem>
905                 <para>
906                         <emphasis>sw</emphasis> - match the val parameter as 'starts
907                         with'.
908                 </para>
909                 </listitem>
910                 </itemizedlist>
911                 <para>
912                         All parameters can be static strings or contain variables.
913                 </para>
914                 <para>
915                         This function can be used from ANY_ROUTE.
916                 </para>
917                 <example>
918                 <title><function>sht_rm_value</function> usage</title>
919                 <programlisting format="linespecific">
920 ...
921 sht_rm_value("ha", "re", ".*");
922 ...
923 </programlisting>
924                 </example>
925         </section>
926         <section id="htable.f.sht_reset">
927                 <title>
928                 <function moreinfo="none">sht_reset(htable)</function>
929                 </title>
930                 <para>
931                         Delete all entries in the htable. The name of the hash table
932                         can be a dynamic string with variables.
933                 </para>
934                 <para>
935                         This function can be used from ANY_ROUTE.
936                 </para>
937                 <example>
938                 <title><function>sht_reset</function> usage</title>
939                 <programlisting format="linespecific">
940 ...
941 sht_reset("ha$var(x)");
942 ...
943 </programlisting>
944                 </example>
945         </section>
946         <section id="htable.f.sht_lock">
947                 <title>
948                 <function moreinfo="none">sht_lock(htable=>key)</function>
949                 </title>
950                 <para>
951                         Lock the slot in htable corresponding to the key item. Note that
952                         the locking is re-entrant for the process, therefore the lock
953                         and unlock should be done by the same process.
954                 </para>
955                 <para>
956                         This function can be used from ANY_ROUTE.
957                 </para>
958                 <example>
959                 <title><function>sht_lock</function> usage</title>
960                 <programlisting format="linespecific">
961 ...
962 sht_lock("ha=>test");
963 ...
964 </programlisting>
965                 </example>
966         </section>
967         <section id="htable.f.sht_unlock">
968                 <title>
969                 <function moreinfo="none">sht_unlock(htable=>key)</function>
970                 </title>
971                 <para>
972                         Unlock the slot in htable corresponding to the key item. Note that
973                         the locking is re-entrant for the process, therefore the lock
974                         and unlock should be done by the same process.
975                 </para>
976                 <para>
977                         This function can be used from ANY_ROUTE.
978                 </para>
979                 <example>
980                 <title><function>sht_unlock</function> usage</title>
981                 <programlisting format="linespecific">
982 ...
983 sht_lock("ha=>test");
984 $sht(ha=>test) = $sht(ha=>test) + 10;
985 sht_unlock("ha=>test");
986 ...
987 </programlisting>
988                 </example>
989         </section>
990         <section id="htable.f.sht_iterator_start">
991                 <title>
992                 <function moreinfo="none">sht_iterator_start(iname, hname)</function>
993                 </title>
994                 <para>
995                         Start an iterator for hash table named by the value of parameter
996                         hname. The parameter iname is used to identify the iterator. There
997                         can be up to 4 iterators at the same time, with different name.
998                 </para>
999                 <para>
1000                         Both parameters can be dynamic strings with variables.
1001                 </para>
1002                 <para>
1003                         IMPORTANT: the slot of the hash table is left locked when
1004                         retrieving in item. Therefore be sure you do not update the
1005                         content of the hash table in between sht_iterator_start()
1006                         and sht_iterator_end(), because it may end up in dead lock.
1007                 </para>
1008                 <para>
1009                         This function can be used from ANY_ROUTE.
1010                 </para>
1011                 <example>
1012                 <title><function>sht_iterator_start</function> usage</title>
1013                 <programlisting format="linespecific">
1014 ...
1015 sht_iterator_start("i1", "h1");
1016 ...
1017 </programlisting>
1018                 </example>
1019         </section>
1020         <section id="htable.f.sht_iterator_end">
1021                 <title>
1022                 <function moreinfo="none">sht_iterator_end(iname)</function>
1023                 </title>
1024                 <para>
1025                         Close the iterator identified by iname parameter and release
1026                         the hash table slot acquired by the iterator. The iname value
1027                         must be the same used for sht_iterator_start().
1028                 </para>
1029                 <para>
1030                         The parameter can be dynamic string with variables.
1031                 </para>
1032                 <para>
1033                         This function can be used from ANY_ROUTE.
1034                 </para>
1035                 <example>
1036                 <title><function>sht_iterator_end</function> usage</title>
1037                 <programlisting format="linespecific">
1038 ...
1039 sht_iterator_end("i1");
1040 ...
1041 </programlisting>
1042                 </example>
1043         </section>
1044         <section id="htable.f.sht_iterator_next">
1045                 <title>
1046                 <function moreinfo="none">sht_iterator_next(iname)</function>
1047                 </title>
1048                 <para>
1049                         Move the iterator to the next item in hash table. It must
1050                         be called also after sht_iterator_start() to get the first
1051                         item in the hash table. Items are returned as they are found
1052                         in the hash table slot, starting with the first slot.
1053                 </para>
1054                 <para>
1055                         The return code is false when there is no (more) item in the
1056                         hash table.
1057                 </para>
1058                 <para>
1059                         The item name and value are accessible via variables:
1060                         $shtitkey(iname) and $shtitval(iname).
1061                 </para>
1062                 <para>
1063                         The parameter can be dynamic string with variables.
1064                 </para>
1065                 <para>
1066                         This function can be used from ANY_ROUTE.
1067                 </para>
1068                 <example>
1069                 <title><function>sht_iterator_next</function> usage</title>
1070                 <programlisting format="linespecific">
1071 ...
1072     sht_iterator_start("i1", "h1");
1073     while(sht_iterator_next("i1")) {
1074         xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
1075     }
1076     sht_iterator_end("i1");
1077 ...
1078 </programlisting>
1079                 </example>
1080         </section>
1081         <section id="htable.f.sht_has_name">
1082                 <title>
1083                 <function moreinfo="none">sht_has_name(htable, op, mval)</function>
1084                 </title>
1085                 <para>
1086                         Return greater than 0 (true) if the htable has an item that matches
1087                         the name against the mval parameter.
1088                 </para>
1089                 <para>
1090                         The op parameter can be:
1091                 </para>
1092                 <itemizedlist>
1093                 <listitem>
1094                 <para>
1095                         <emphasis>eq</emphasis> - match the val parameter as string equal
1096                         expression.
1097                 </para>
1098                 </listitem>
1099                 <listitem>
1100                 <para>
1101                         <emphasis>ne</emphasis> - match the val parameter as string not-equal
1102                         expression.
1103                 </para>
1104                 </listitem>
1105                 <listitem>
1106                 <para>
1107                         <emphasis>re</emphasis> - match the val parameter as regular
1108                         expression.
1109                 </para>
1110                 </listitem>
1111                 <listitem>
1112                 <para>
1113                         <emphasis>sw</emphasis> - match the val parameter as 'starts
1114                         with' expression.
1115                 </para>
1116                 </listitem>
1117                 </itemizedlist>
1118                 <para>
1119                         All parameters can be static strings or contain variables.
1120                 </para>
1121                 <para>
1122                         This function can be used from ANY_ROUTE.
1123                 </para>
1124                 <example>
1125                 <title><function>sht_has_name</function> usage</title>
1126                 <programlisting format="linespecific">
1127 ...
1128 if(sht_has_name("ha", "eq", "alice")) {
1129   ...
1130 }
1131 ...
1132 </programlisting>
1133                 </example>
1134         </section>
1135         <section id="htable.f.sht_has_str_value">
1136                 <title>
1137                 <function moreinfo="none">sht_has_str_value(htable, op, mval)</function>
1138                 </title>
1139                 <para>
1140                         Return greater than 0 (true) if the htable has an item that matches
1141                         the string value against the mval parameter.
1142                 </para>
1143                 <para>
1144                         The op parameter can be:
1145                 </para>
1146                 <itemizedlist>
1147                 <listitem>
1148                 <para>
1149                         <emphasis>eq</emphasis> - match the val parameter as string equal
1150                         expression.
1151                 </para>
1152                 </listitem>
1153                 <listitem>
1154                 <para>
1155                         <emphasis>ne</emphasis> - match the val parameter as string not-equal
1156                         expression.
1157                 </para>
1158                 </listitem>
1159                 <listitem>
1160                 <para>
1161                         <emphasis>re</emphasis> - match the val parameter as regular
1162                         expression.
1163                 </para>
1164                 </listitem>
1165                 <listitem>
1166                 <para>
1167                         <emphasis>sw</emphasis> - match the val parameter as 'starts
1168                         with' expression.
1169                 </para>
1170                 </listitem>
1171                 </itemizedlist>
1172                 <para>
1173                         All parameters can be static strings or contain variables.
1174                 </para>
1175                 <para>
1176                         This function can be used from ANY_ROUTE.
1177                 </para>
1178                 <example>
1179                 <title><function>sht_has_name</function> usage</title>
1180                 <programlisting format="linespecific">
1181 ...
1182 if(sht_has_str_value("ha", "eq", "alice")) {
1183   ...
1184 }
1185 ...
1186 </programlisting>
1187                 </example>
1188         </section>
1189         </section>
1190                 <section>
1191                 <title>Exported pseudo-variables</title>
1192                 <itemizedlist>
1193                         <listitem><para>
1194                                 <emphasis>$sht(htable=>key)</emphasis>
1195                         </para></listitem>
1196                         <listitem><para>
1197                                 <emphasis>$shtex(htable=>key)</emphasis>
1198                         </para></listitem>
1199                         <listitem><para>
1200                                 <emphasis>$shtcn(htable=>key)</emphasis>
1201                         </para></listitem>
1202                         <listitem><para>
1203                                 <emphasis>$shtcv(htable=>key)</emphasis>
1204                         </para></listitem>
1205                         <listitem><para>
1206                                 <emphasis>$shtinc(htable=>key)</emphasis>
1207                         </para></listitem>
1208                         <listitem><para>
1209                                 <emphasis>$shtitkey(iname)</emphasis>
1210                         </para></listitem>
1211                         <listitem><para>
1212                                 <emphasis>$shtitval(iname)</emphasis>
1213                         </para></listitem>
1214                         <listitem><para>
1215                                 <emphasis>$shtrecord(attribute)</emphasis>
1216                         </para></listitem>
1217                 </itemizedlist>
1218                 <para>
1219                 Exported pseudo-variables are documented at &kamwikilink;.
1220                 </para>
1221         </section>
1222         <section>
1223         <title>RPC Commands</title>
1224         <section id="htable.rpc.get">
1225                 <title>
1226                 <function moreinfo="none">htable.get htable key</function>
1227                 </title>
1228                 <para>
1229                                         Lists one value in a hash table
1230                 </para>
1231                 <para>
1232                 Name: <emphasis>htable.get</emphasis>
1233                 </para>
1234                 <para>Parameters:</para>
1235                 <itemizedlist>
1236                         <listitem><para>htable : Name of the hash table to dump</para>
1237                         </listitem>
1238                         <listitem><para>key : Key name of the hash table value to dump</para>
1239                         </listitem>
1240
1241                 </itemizedlist>
1242                 <para>
1243                 Example:
1244                 </para>
1245 <programlisting  format="linespecific">
1246 ...
1247 # Dump $sht(students=>alice)
1248 kamcmd htable.get students alice
1249
1250 # Dump first entry in array key course $sht(students=>course[0])
1251 kamcmd htable.get students course[0]
1252 ...
1253 </programlisting>
1254         </section>
1255         <section id="htable.rpc.delete">
1256                 <title>
1257                 <function moreinfo="none">htable.delete htable key</function>
1258                 </title>
1259                 <para>
1260                                         Delete one value in a hash table
1261                 </para>
1262                 <para>
1263                 Name: <emphasis>htable.delete</emphasis>
1264                 </para>
1265                 <para>Parameters:</para>
1266                 <itemizedlist>
1267                         <listitem><para>htable : Name of the hash table to delete</para>
1268                         </listitem>
1269                         <listitem><para>key : Key name of the hash table value to delete</para>
1270                         </listitem>
1271
1272                 </itemizedlist>
1273                 <para>
1274                 Example:
1275                 </para>
1276 <programlisting  format="linespecific">
1277 ...
1278 # Delete $sht(students=>alice)
1279 kamcmd htable.delete students alice
1280
1281 # Delete first entry in array key course $sht(students=>course[0])
1282 kamcmd htable.delete students course[0]
1283 ...
1284 </programlisting>
1285         </section>
1286        <section id="htable.rpc.sets">
1287                 <title>
1288                 <function moreinfo="none">htable.sets htable key value</function>
1289                 </title>
1290                 <para>
1291                                         Set an item in hash table to string value.
1292                 </para>
1293                 <para>
1294                 Name: <emphasis>htable.sets</emphasis>
1295                 </para>
1296                 <para>Parameters:</para>
1297                 <itemizedlist>
1298                         <listitem><para>htable : Name of the hash table</para>
1299                         </listitem>
1300                         <listitem><para>key : Key name in the hash table</para>
1301                         </listitem>
1302                         <listitem><para>Value : String value for the item</para>
1303                         </listitem>
1304
1305                 </itemizedlist>
1306                 <para>
1307                 Example:
1308                 </para>
1309 <programlisting  format="linespecific">
1310 ...
1311 # Set $sht(test=>x) as string
1312 kamcmd htable.sets test x abc
1313
1314 # Set firsti entry in array key x $sht(test=>x[0]) as string
1315 kamcmd htable.sets test x[0] abc
1316 ...
1317 </programlisting>
1318         </section>
1319        <section id="htable.rpc.seti">
1320                 <title>
1321                 <function moreinfo="none">htable.seti htable key value</function>
1322                 </title>
1323                 <para>
1324                                         Set an item in hash table to integer value.
1325                 </para>
1326                 <para>
1327                 Name: <emphasis>htable.seti</emphasis>
1328                 </para>
1329                 <para>Parameters:</para>
1330                 <itemizedlist>
1331                         <listitem><para>htable : Name of the hash table</para>
1332                         </listitem>
1333                         <listitem><para>key : Key name in the hash table</para>
1334                         </listitem>
1335                         <listitem><para>Value : Integer value for the item</para>
1336                         </listitem>
1337
1338                 </itemizedlist>
1339                 <para>
1340                 Example:
1341                 </para>
1342 <programlisting  format="linespecific">
1343 ...
1344 # Set $sht(test=>x) as integer
1345 kamcmd htable.seti test x 123
1346
1347 # Set first entry in array key x $sht(test=>x[0]) as integer
1348 kamcmd htable.sets test x[0] 123
1349 ...
1350 </programlisting>
1351         </section>
1352         <section id="htable.rpc.dump">
1353                 <title>
1354                 <function moreinfo="none">htable.dump htable</function>
1355                 </title>
1356                 <para>
1357                 Lists all the values in a hash table
1358                 </para>
1359                 <para>
1360                 Name: <emphasis>dhtable.dump</emphasis>
1361                 </para>
1362                 <para>Parameters:</para>
1363                 <itemizedlist>
1364                         <listitem><para>htable : Name of the hash table to dump</para>
1365                         </listitem>
1366
1367                 </itemizedlist>
1368                 <para>
1369                 Example:
1370                 </para>
1371 <programlisting  format="linespecific">
1372 ...
1373 kamcmd htable.dump ipban
1374 ...
1375 </programlisting>
1376         </section>
1377         <section id="htable.rpc.reload">
1378                 <title>
1379                 <function moreinfo="none">htable.reload htable</function>
1380                 </title>
1381                 <para>
1382                 Reload hash table from database.
1383                 </para>
1384                 <para>
1385                 Name: <emphasis>dhtable.reload</emphasis>
1386                 </para>
1387                 <para>Parameters:</para>
1388                 <itemizedlist>
1389                         <listitem><para>htable : Name of the hash table to reload</para>
1390                         </listitem>
1391
1392                 </itemizedlist>
1393                 <para>
1394                 Example:
1395                 </para>
1396 <programlisting  format="linespecific">
1397 ...
1398 kamcmd htable.reload ipban
1399 ...
1400 </programlisting>
1401         </section>
1402         <section id="htable.rpc.flush">
1403           <title>
1404                 <function moreinfo="none">htable.flush htable</function>
1405           </title>
1406           <para>
1407             Empty the hash table
1408           </para>
1409           <para>
1410             Name: <emphasis>htable.flush</emphasis>
1411           </para>
1412           <para>Parameters:</para>
1413           <itemizedlist>
1414             <listitem><para>htable : Name of the hash table to flush</para></listitem>
1415           </itemizedlist>
1416           <para>
1417           Example:
1418           </para>
1419 <programlisting  format="linespecific">
1420 ...
1421 kamcmd htable.flush ipban
1422 ...
1423 </programlisting>
1424         </section>
1425         <section id="htable.rpc.listTables">
1426                 <title>
1427                 <function moreinfo="none">htable.listTables</function>
1428                 </title>
1429                 <para>
1430                 Lists all defined tables
1431                 </para>
1432                 <para>
1433                 Name: <emphasis>htable.listTables</emphasis>
1434                 </para>
1435                 <para>Parameters:</para>
1436                 <itemizedlist>
1437                         <listitem><para>None</para>
1438                         </listitem>
1439
1440                 </itemizedlist>
1441                 <para>
1442                 Example:
1443                 </para>
1444 <programlisting  format="linespecific">
1445 ...
1446 kamcmd htable.listTables
1447 ...
1448 </programlisting>
1449         </section>
1450     <section id="htable.rpc.stats">
1451           <title>
1452                 <function moreinfo="none">htable.stats</function>
1453           </title>
1454           <para>
1455                           Get statistics for hash tables - name, number of slots,
1456                           number of items, max number of items per slot, min number
1457                           of items per slot.
1458           </para>
1459                 <para>
1460                 Name: <emphasis>htable.stats</emphasis>
1461                 </para>
1462                 <para>Parameters:</para>
1463                 <itemizedlist>
1464                         <listitem><para>None</para>
1465                         </listitem>
1466
1467                 </itemizedlist>
1468                 <para>
1469                 Example:
1470                 </para>
1471 <programlisting  format="linespecific">
1472 ...
1473 kamcmd htable.stats
1474 ...
1475 </programlisting>
1476         </section>
1477
1478         </section><!-- RPC commands -->
1479
1480         <section>
1481         <title>Event routes</title>
1482         <section>
1483                 <title>
1484                 <function moreinfo="none">htable:mod-init</function>
1485                 </title>
1486                 <para>
1487                         When defined, the module calls event_route[htable:mod-init] after
1488                         all modules have been initialized. A typical use case is to
1489                         initialise items in hash tables. The event route is executed only
1490                         once, after core and module initialization, but before &kamailio; forks any
1491                         child processes.
1492                 </para>
1493 <programlisting  format="linespecific">
1494 ...
1495 event_route[htable:mod-init] {
1496     $sht(a=>x) = 1;
1497 }
1498 ...
1499 </programlisting>
1500         </section>
1501         <section>
1502                 <title>
1503                 <function moreinfo="none">htable:expired:&lt;table&gt;</function>
1504                 </title>
1505                 <para>
1506                         When defined, the module calls event_route[htable:expired:&lt;table&gt;]
1507                         when an entry in the given table expires. In this event route, the key and value
1508                         of the expired record are available with the $shtrecord(key) and $shtrecord(value)
1509                         pseudo-variables.
1510                 </para>
1511 <programlisting  format="linespecific">
1512 ...
1513
1514 event_route[htable:expired:mytable] {
1515     xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
1516 }
1517 ...
1518 </programlisting>
1519         </section>
1520         </section>
1521
1522 </chapter>
1523