mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1286 lines
35 KiB
1286 lines
35 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
The module adds a hash table container to the configuration language. The
|
|
hash table is stored in shared memory and the access to it can be
|
|
done via pseudo-variables: $sht(htname=>name). The module supports
|
|
definition of many hash tables and can load values at startup from
|
|
a database table.
|
|
</para>
|
|
<para>
|
|
A typical use case for the SIP server is to implement a cache system
|
|
in configuration file - if a value is not found in hash table, load
|
|
it from database and store it in hash table so next time the access to
|
|
it is very fast. In the definition of the table you can define the
|
|
default expiration time of cached items. The expiration time can
|
|
be adjusted per item via assignment operation at runtime.
|
|
</para>
|
|
<para>
|
|
Replication between multiple servers is performed automatically (if
|
|
enabled) via the DMQ module.
|
|
</para>
|
|
<para>
|
|
You can read more about hash tables at:
|
|
http://en.wikipedia.org/wiki/Hash_table.
|
|
</para>
|
|
<para>
|
|
The <quote>name</quote> can be a static string or can include pseudo-
|
|
variables that will be replaced at runtime.
|
|
</para>
|
|
<example>
|
|
<title>Accessing $sht(htname=>key)</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "htable", "a=>size=8;")
|
|
...
|
|
$sht(a=>test) = 1;
|
|
$sht(a=>$ci::srcip) = $si;
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Next example shows a way to protect against dictionary attacks. If
|
|
someone fails to authenticate 3 times, it is forbidden for 15min.
|
|
Authenticatiion against database is expensive as it does a select
|
|
on the <quote>subscriberthe</quote> table. By disabling the DB auth for 15min,
|
|
resources on the server are saved and time to discover the password is increased
|
|
substantially. Additional alerting can be done by writing a message
|
|
to syslog or sending email, etc.
|
|
</para>
|
|
<para>
|
|
To implement the logic, two hash table variables are used: one counting
|
|
the failed authentications per user and one for storing the time of
|
|
last authentication attempt. To ensure a unique name per user, the
|
|
hash table uses a combination of authentication username and text
|
|
<quote>::auth_count</quote> and <quote>::last_auth</quote>.
|
|
</para>
|
|
<example>
|
|
<title>Dictionary attack limitation</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "htable", "a=>size=8;")
|
|
...
|
|
if(is_present_hf("Authorization"))
|
|
{
|
|
if($sht(a=>$au::auth_count)==3)
|
|
{
|
|
$var(exp) = $Ts - 900;
|
|
if($sht(a=>$au::last_auth) > $var(exp))
|
|
{
|
|
sl_send_reply("403", "Try later");
|
|
exit;
|
|
} else {
|
|
$sht(a=>$au::auth_count) = 0;
|
|
}
|
|
}
|
|
if(!www_authenticate("$td", "subscriber"))
|
|
{
|
|
switch ($retcode) {
|
|
case -1:
|
|
sl_send_reply("403", "Forbidden");
|
|
exit;
|
|
case -2:
|
|
if($sht(a=>$au::auth_count) == $null)
|
|
$sht(a=>$au::auth_count) = 0;
|
|
$sht(a=>$au::auth_count) = $sht(a=>$au::auth_count) + 1;
|
|
if($sht(a=>$au::auth_count) == 3)
|
|
xlog("auth failed 3rd time - src ip: $si\n");
|
|
$sht(a=>$au::last_auth) = $Ts;
|
|
break;
|
|
}
|
|
www_challenge("$td"/*realm*/,"0"/*qop*/);
|
|
exit;
|
|
}
|
|
$sht(a=>$au::auth_count) = 0;
|
|
} else {
|
|
www_challenge("$td","0");
|
|
exit;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
The module also provides a way to store multiple values for a single key.
|
|
This is emulated by storing individual keys as 'key_name[n]', where n is
|
|
incremented for each key. The total number of keys is stored in a
|
|
dedicated key, by default: 'key_name::size'.
|
|
</para>
|
|
<para>
|
|
The array is built when the table is loaded in memory and afterwards all
|
|
the keys are treated as individual keys.
|
|
If a particular entry in the array is deleted, it is the administrator's
|
|
responsibility to update the size of the array and any other elements
|
|
(if required).
|
|
</para>
|
|
<example>
|
|
<title>Storing array values</title>
|
|
<programlisting format="linespecific">
|
|
# Example of dbtext with multiple keys
|
|
$ cat /usr/local/etc/kamailio/dbtext/htable
|
|
1:key:1:0:value3:0
|
|
2:key:1:0:value2:0
|
|
3:key:1:0:value1:0
|
|
|
|
# The array key will be loaded in memory in the following format:
|
|
$ kamcmd htable.dump htable
|
|
{
|
|
entry: 35
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key[0]
|
|
value: value1
|
|
}
|
|
}
|
|
}
|
|
{
|
|
entry: 50
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key::size
|
|
value: 3
|
|
}
|
|
}
|
|
}
|
|
{
|
|
entry: 67
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key[1]
|
|
value: value2
|
|
}
|
|
}
|
|
}
|
|
{
|
|
entry: 227
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key[2]
|
|
value: value3
|
|
}
|
|
}
|
|
}
|
|
|
|
# Now let's delete a particular entry in the array: key[0].
|
|
$ kamcmd htable.delete htable key[0]
|
|
|
|
# The array key will look like this after a key was deleted:
|
|
$ kamcmd htable.dump htable
|
|
{
|
|
entry: 50
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key::size
|
|
value: 3
|
|
}
|
|
}
|
|
}
|
|
{
|
|
entry: 67
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key[1]
|
|
value: value2
|
|
}
|
|
}
|
|
}
|
|
{
|
|
entry: 227
|
|
size: 1
|
|
slot: {
|
|
item: {
|
|
name: key[2]
|
|
value: value3
|
|
}
|
|
}
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>If DMQ replication is enabled, the DMQ module must be loaded first.</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before running
|
|
&kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>None</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Loading from database</title>
|
|
<para>
|
|
The module is able to load values in a hash table at startup upon
|
|
providing a DB URL and table name.
|
|
</para>
|
|
<para>
|
|
The structure of the table must contain:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>key name</emphasis> - string containing the name of
|
|
the key.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>key type</emphasis> - the type of the key
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>0</emphasis> - simple key - the key is added
|
|
as 'key_name'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>1</emphasis> - array key - the key is added
|
|
as 'key_name[n]' - n is incremented for each key with this
|
|
name to build an array in hash table. In addition, an additional
|
|
key is built to hold the total number of key in the array,
|
|
by default key_name::size (see array_size_suffix parameter).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>value type</emphasis> - the type of the key value
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>0</emphasis> - value is string.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>1</emphasis> - value is integer.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>key value</emphasis> - string containing the value of
|
|
the key.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="htable.p.htable">
|
|
<title><varname>htable</varname> (str)</title>
|
|
<para>
|
|
The definition of a hash table. The value of the parameter may have the
|
|
following format:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
"htname=>size=_number_;autoexpire=_number_;dbtable=_string_"
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
The parameter can be set multiple times to get more hash tables in
|
|
same configuration file.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>htname</emphasis> - string specifying the name of
|
|
the hash table. This string is used by <emphasis>$sht(...)</emphasis>
|
|
to refer to the hash table.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>size</emphasis> - number specifying the size of hash
|
|
table. Larger value means less collisions. The number of entries
|
|
(aka slots or buckets) in the table is 2^size. The possible range
|
|
for this value is from 2 to 31, smaller or larger values will be
|
|
increased to 3 (8 slots) or decreased to 14 (16384 slots).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>autoexpire</emphasis> -time in seconds to delete an item
|
|
from hash table if no update was done to it. If is missing or set
|
|
to 0, the items won't expire.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>dbtable</emphasis> - name of database to be loaded at
|
|
startup in hash table. If empty or missing, no data will be loaded.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>cols</emphasis> - the column names of the database table.
|
|
They must be enclosed in quotes in order to form a valid SIP
|
|
parameter value and be separated by comma. The first column
|
|
corresponds to key_name. When specified, there must be at least
|
|
two columns. If this attribute is not specified, then the global
|
|
module parameters for column names are used. If more than one
|
|
value columns are specified, the hash table will pack the column
|
|
values in a comma separated string, which will be associated
|
|
with the key (string transformation {s.select,...} can be
|
|
used in configuration file to extract a specific column value).
|
|
When cols attribute is present, writing back to database table
|
|
is disabled.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>dbmode</emphasis> - if set to 1, the content of hash
|
|
table is written to database table when the SIP server is stopped
|
|
(i.e., ensure persistency over restarts). Default value is 0 (no
|
|
write back to db table).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>initval</emphasis> - the integer value to be returned
|
|
instead of $null when a requested key is not set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>updateexpire</emphasis> - if set to 1 (default), the time until
|
|
expiration of an item is reset when that item is updated. Certain uses of
|
|
htable may dictate that updates should not reset the expiration timeout, however,
|
|
in which case this attribute can be set to 0.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>dmqreplicate</emphasis> - if set to 1, any actions (set, update, delete
|
|
etc.) performed upon entries in this table will be replicated to other nodes (htable
|
|
peers). Please note, module parameter <quote>enable_dmq</quote> must also be set in
|
|
order for this to apply (see below). Default is 0 (no replication).
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<emphasis>
|
|
Default value is NULL.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>hash_size</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
|
|
modparam("htable", "htable", "b=>size=5;")
|
|
modparam("htable", "htable", "c=>size=4;autoexpire=7200;initval=1;dmqreplicate=1;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.db_url">
|
|
<title><varname>db_url</varname> (str)</title>
|
|
<para>
|
|
The <acronym>URL</acronym> to connect to database for loading values in hash
|
|
table at start up.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is NULL (do not connect).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "db_url", "&defaultdb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.key_name_column">
|
|
<title><varname>key_name_column</varname> (str)</title>
|
|
<para>
|
|
The name of the column containing the hash table key name.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 'key_name'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>key_name_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "key_name_column", "kname")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.key_type_column">
|
|
<title><varname>key_type_column</varname> (str)</title>
|
|
<para>
|
|
The name of the column containing the hash table key type.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 'key_type'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>key_type_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "key_type_column", "ktype")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.value_type_column">
|
|
<title><varname>value_type_column</varname> (str)</title>
|
|
<para>
|
|
The name of the column containing the hash table value type.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 'value_type'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>value_type_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "value_type_column", "vtype")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.key_value_column">
|
|
<title><varname>key_value_column</varname> (str)</title>
|
|
<para>
|
|
The name of the column containing hash table key value.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 'key_value'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>key_value_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "key_value_column", "kvalue")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.expires_column">
|
|
<title><varname>expires_column</varname> (str)</title>
|
|
<para>
|
|
The name of the column containing the expires value.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 'expires'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>expires_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "expires", "expiry")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.array_size_suffix">
|
|
<title><varname>array_size_suffix</varname> (str)</title>
|
|
<para>
|
|
The suffix to be added to store the number of items in an
|
|
array (see key type).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is '::size'.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>array_size_suffix</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "array_size_suffix", "-count")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.fetch_rows">
|
|
<title><varname>fetch_rows</varname> (integer)</title>
|
|
<para>
|
|
How many rows to fetch at once from database.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 100.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>fetch_rows</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "fetch_rows", 1000)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.timer_interval">
|
|
<title><varname>timer_interval</varname> (integer)</title>
|
|
<para>
|
|
Interval in seconds to check for expired htable values.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 20.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_interval</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "timer_interval", 10)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.db_expires">
|
|
<title><varname>db_expires</varname> (integer)</title>
|
|
<para>
|
|
If set to 1, the module will load/save the expires values of the items in
|
|
hash table from/to database. It applies only to hash tables that
|
|
have the auto-expires attribute defined.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_expires</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "db_expires", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.enable_dmq">
|
|
<title><varname>enable_dmq</varname> (integer)</title>
|
|
<para>
|
|
If set to 1, will enable DMQ replication of actions performed upon
|
|
entries in all tables having "dmqreplicate" parameter set. Any update
|
|
action performed via pseudo-variables, MI and RPC commands will be
|
|
repeated on all other nodes. Therefore, it is important to ensure the
|
|
table definition (size, autoexpire etc.) is identical across all instances.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Important: If this parameter is enabled, the DMQ module must be loaded first - otherwise, startup will fail.
|
|
</emphasis>
|
|
</para>
|
|
<para>
|
|
Currently, values are not replicated on load from DB as it is expected
|
|
that in these cases, all servers will load their values from the same DB.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>enable_dmq</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "enable_dmq", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.p.timer_procs">
|
|
<title><varname>timer_procs</varname> (integer)</title>
|
|
<para>
|
|
If set to 1 or greater, the module will create its own timer
|
|
processes to scan for expired items in hash tables. If set to zero,
|
|
it will use the core timer for this task. Set it to 1 if you store
|
|
a lot of items with autoexpire property.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_procs</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("htable", "timer_procs", 4)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="htable.f.sht_print">
|
|
<title>
|
|
<function moreinfo="none">sht_print()</function>
|
|
</title>
|
|
<para>
|
|
Dump content of hash table to L_ERR log level. Intended for debug
|
|
purposes.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
ONREPLY_ROUTE, BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_print</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_print();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_rm_name_re">
|
|
<title>
|
|
<function moreinfo="none">sht_rm_name_re(htable=>regexp)</function>
|
|
</title>
|
|
<para>
|
|
Delete all entries in the htable that match the name against
|
|
regular expression.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
ONREPLY_ROUTE, BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_rm_name_re</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_rm_name_re("ha=>.*");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_rm_value_re">
|
|
<title>
|
|
<function moreinfo="none">sht_rm_value_re(htable=>regexp)</function>
|
|
</title>
|
|
<para>
|
|
Delete all entries in the htable that match the value against
|
|
regular expression.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
ONREPLY_ROUTE, BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_rm_value_re</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_rm_value_re("ha=>.*");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_reset">
|
|
<title>
|
|
<function moreinfo="none">sht_reset(htable)</function>
|
|
</title>
|
|
<para>
|
|
Delete all entries in the htable. The name of the hash table
|
|
can be a dynamic string with variables.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_reset</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_reset("ha$var(x)");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_lock">
|
|
<title>
|
|
<function moreinfo="none">sht_lock(htable=>key)</function>
|
|
</title>
|
|
<para>
|
|
Lock the slot in htable corespoding to the key item. Note that
|
|
the locking is re-entrant for the process, therefore the lock
|
|
and unlock should be done by the same process.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_lock</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_lock("ha=>test");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_unlock">
|
|
<title>
|
|
<function moreinfo="none">sht_unlock(htable=>key)</function>
|
|
</title>
|
|
<para>
|
|
Unlock the slot in htable corespoding to the key item. Note that
|
|
the locking is re-entrant for the process, therefore the lock
|
|
and unlock should be done by the same process.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_unlock</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_lock("ha=>test");
|
|
$sht(ha=>test) = $sht(ha=>test) + 10;
|
|
sht_unlock("ha=>test");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_iterator_start">
|
|
<title>
|
|
<function moreinfo="none">sht_iterator_start(iname, hname)</function>
|
|
</title>
|
|
<para>
|
|
Start an iterator for hash table named by the value of parameter
|
|
hname. The parameter iname is used to identify the iterator. There
|
|
can be up to 4 iterators at the same time, with different name.
|
|
</para>
|
|
<para>
|
|
Both parameters can be dynamic strings with variables.
|
|
</para>
|
|
<para>
|
|
IMPORTANT: the slot of the hash table is left locked when
|
|
retrieving in item. Therefore be sure you do not update the
|
|
content of the hash table in between sht_iterator_start()
|
|
and sht_iterator_end(), because it may end up in dead lock.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_iterator_start</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_iterator_start("i1", "h1");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_iterator_end">
|
|
<title>
|
|
<function moreinfo="none">sht_iterator_end(iname)</function>
|
|
</title>
|
|
<para>
|
|
Close the iterator identified by iname parameter and release
|
|
the hash table slot aquired by the iterator. The iname value
|
|
must be the same used for sht_iterator_start().
|
|
</para>
|
|
<para>
|
|
The parameter can be dynamic string with variables.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_iterator_end</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_iterator_end("i1");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="htable.f.sht_iterator_next">
|
|
<title>
|
|
<function moreinfo="none">sht_iterator_next(iname)</function>
|
|
</title>
|
|
<para>
|
|
Move the iterator to the next item in hash table. It must
|
|
be called also after sht_iterator_start() to get the first
|
|
item in the hash table. Items are returned as they are found
|
|
in the hash table slot, starting with the first slot.
|
|
</para>
|
|
<para>
|
|
The return code is false when there is no (more) item in the
|
|
hash table.
|
|
</para>
|
|
<para>
|
|
The item name and value are accessible via variables:
|
|
$shtitkey(iname) and $shtitval(iname).
|
|
</para>
|
|
<para>
|
|
The parameter can be dynamic string with variables.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>sht_iterator_next</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
sht_iterator_start("i1", "h1");
|
|
while(sht_iterator_next("i1")) {
|
|
xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
|
|
}
|
|
sht_iterator_end("i1");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Exported pseudo-variables</title>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>$sht(htable=>key)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtex(htable=>key)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtcn(htable=>key)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtcv(htable=>key)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtinc(htable=>key)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtitkey(iname)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtitval(iname)</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>$shtrecord(attribute)</emphasis>
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Exported pseudo-variables are documented at &kamwikilink;.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>MI Commands</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">sht_reload</function>
|
|
</title>
|
|
<para>
|
|
Reload a hash table from database.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>sht_reload</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>_hash_table_name_</emphasis> - the name
|
|
of hash table to reload.</para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:sht_reload:_reply_fifo_file_
|
|
_hash_table_name_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">sht_dump</function>
|
|
</title>
|
|
<para>
|
|
Dump content of a hash table via MI.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>sht_dump</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>_hash_table_name_</emphasis> - the name
|
|
of hash table to dump.</para>
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:sht_dump:_reply_fifo_file_
|
|
_hash_table_name_
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">sht_delete</function>
|
|
</title>
|
|
<para>
|
|
Delete a key from a hash table via MI.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>sht_delete</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>_hash_table_name: </emphasis>The table name to delete the key from</para></listitem>
|
|
<listitem><para><emphasis>_key_name: </emphasis>The key to delete from the htable</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
MI FIFO Command Format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:sht_delete:_reply_fifo_file_
|
|
_hash_table_name_
|
|
_key_name_
|
|
_empty_line_
|
|
</programlisting>
|
|
|
|
<para>
|
|
Example (note the quoting when executing it via FIFO):
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
kamctl fifo sht_delete auth '"user@example.org::last_auth"'
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Exported RPC Commands</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.get htable key</function>
|
|
</title>
|
|
<para>
|
|
Lists one value in a hash table
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.get</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table to dump</para>
|
|
</listitem>
|
|
<listitem><para>key : Key name of the hash table value to dump</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# Dump $sht(students=>daniel)
|
|
kamcmd htable.get students daniel
|
|
|
|
# Dump first entry in array key course $sht(students=>course[0])
|
|
kamcmd htable.get students course[0]
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.delete htable key</function>
|
|
</title>
|
|
<para>
|
|
Delete one value in a hash table
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.delete</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table to delete</para>
|
|
</listitem>
|
|
<listitem><para>key : Key name of the hash table value to delete</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# Delete $sht(students=>anna)
|
|
kamcmd htable.delete students anna
|
|
|
|
# Delete first entry in array key course $sht(students=>course[0])
|
|
kamcmd htable.delete students course[0]
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.sets htable key value</function>
|
|
</title>
|
|
<para>
|
|
Set an item in hash table to string value.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.sets</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table</para>
|
|
</listitem>
|
|
<listitem><para>key : Key name in the hash table</para>
|
|
</listitem>
|
|
<listitem><para>Value : String value for the item</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# Set $sht(test=>x) as string
|
|
kamcmd htable.sets test x abc
|
|
|
|
# Set firsti entry in array key x $sht(test=>x[0]) as string
|
|
kamcmd htable.sets test x[0] abc
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.seti htable key value</function>
|
|
</title>
|
|
<para>
|
|
Set an item in hash table to integer value.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.seti</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table</para>
|
|
</listitem>
|
|
<listitem><para>key : Key name in the hash table</para>
|
|
</listitem>
|
|
<listitem><para>Value : Integer value for the item</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# Set $sht(test=>x) as integer
|
|
kamcmd htable.seti test x 123
|
|
|
|
# Set firsti entry in array key x $sht(test=>x[0]) as integer
|
|
kamcmd htable.sets test x[0] 123
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.dump htable</function>
|
|
</title>
|
|
<para>
|
|
Lists all the values in a hash table
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dhtable.dump</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table to dump</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
kamcmd htable.dump ipban
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.reload htable</function>
|
|
</title>
|
|
<para>
|
|
Reload hash table from database.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>dhtable.reload</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>htable : Name of the hash table to reload</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
kamcmd htable.reload ipban
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.listTables</function>
|
|
</title>
|
|
<para>
|
|
Lists all defined tables
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.listTables</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>None</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
kamcmd htable.listTables
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable.stats</function>
|
|
</title>
|
|
<para>
|
|
Get statistics for hash tables - name, number of slots,
|
|
number of items, max number of items per slot, min number
|
|
of items per slot.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>htable.stats</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>None</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
kamcmd htable.stats
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
|
|
</section><!-- RPC commands -->
|
|
|
|
<section>
|
|
<title>Event routes</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable:mod-init</function>
|
|
</title>
|
|
<para>
|
|
When defined, the module calls event_route[htable:mod-init] after
|
|
all modules have been initialized. A typical use case is to
|
|
initialise items in hash tables. The event route is executed only
|
|
once, after core and module initialization, but before &kamailio; forks any
|
|
child processes.
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
event_route[htable:mod-init] {
|
|
$sht(a=>x) = 1;
|
|
}
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">htable:expired:<table></function>
|
|
</title>
|
|
<para>
|
|
When defined, the module calls event_route[htable:expired:<table>]
|
|
when an entry in the given table expires. In this event route, the key and value
|
|
of the expired record are available with the $shtrecord(key) and $shtrecord(value)
|
|
pseudo-variables.
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
|
|
event_route[htable:expired:mytable] {
|
|
xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|
|
|