modules: readme files regenerated - htable ... [skip ci]

src/modules/htable/README

@@ -1 +1,1304 @@
+HTable Module
 
+Elena-Ramona Modroiu
+
+   asipto.com
+   <[email protected]>
+
+Edited by
+
+Elena-Ramona Modroiu
+
+   <[email protected]>
+
+Alex Balashov
+
+   <[email protected]>
+
+Ovidiu Sas
+
+   <[email protected]>
+
+   Copyright © 2008-2011 http://www.asipto.com
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+              2.3. Loading from database
+
+        3. Parameters
+
+              3.1. htable (str)
+              3.2. db_url (str)
+              3.3. key_name_column (str)
+              3.4. key_type_column (str)
+              3.5. value_type_column (str)
+              3.6. key_value_column (str)
+              3.7. expires_column (str)
+              3.8. array_size_suffix (str)
+              3.9. fetch_rows (integer)
+              3.10. timer_interval (integer)
+              3.11. db_expires (integer)
+              3.12. enable_dmq (integer)
+              3.13. dmq_init_sync (integer)
+              3.14. timer_procs (integer)
+              3.15. event_callback (str)
+              3.16. event_callback_mode (int)
+
+        4. Functions
+
+              4.1. sht_print()
+              4.2. sht_rm(htname, itname)
+              4.3. sht_rm_name_re(htable=>regexp)
+              4.4. sht_rm_value_re(htable=>regexp)
+              4.5. sht_rm_name(htable, op, val)
+              4.6. sht_rm_value(htable, op, val)
+              4.7. sht_reset(htable)
+              4.8. sht_lock(htable=>key)
+              4.9. sht_unlock(htable=>key)
+              4.10. sht_iterator_start(iname, hname)
+              4.11. sht_iterator_end(iname)
+              4.12. sht_iterator_next(iname)
+              4.13. sht_iterator_rm(iname)
+              4.14. sht_iterator_sets(iname, sval)
+              4.15. sht_iterator_seti(iname, ival)
+              4.16. sht_iterator_setex(iname, exval)
+              4.17. sht_match_name(htable, op, mval)
+              4.18. sht_has_name(htable, op, mval)
+              4.19. sht_match_str_value(htable, op, mval)
+              4.20. sht_has_str_value(htable, op, mval)
+
+        5. Exported pseudo-variables
+        6. RPC Commands
+
+              6.1. htable.get htable key
+              6.2. htable.delete htable key
+              6.3. htable.sets htable key value
+              6.4. htable.seti htable key value
+              6.5. htable.setex htable key expire
+              6.6. htable.dump htable
+              6.7. htable.reload htable
+              6.8. htable.store htable
+              6.9. htable.flush htable
+              6.10. htable.listTables
+              6.11. htable.stats
+
+        7. Event routes
+
+              7.1. htable:mod-init
+              7.2. htable:expired:<table>
+
+   List of Examples
+
+   1.1. Accessing $sht(htname=>key)
+   1.2. Dictionary attack limitation
+   1.3. Storing array values
+   1.4. Set htable parameter
+   1.5. Set db_url parameter
+   1.6. Set key_name_column parameter
+   1.7. Set key_type_column parameter
+   1.8. Set value_type_column parameter
+   1.9. Set key_value_column parameter
+   1.10. Set expires_column parameter
+   1.11. Set array_size_suffix parameter
+   1.12. Set fetch_rows parameter
+   1.13. Set timer_interval parameter
+   1.14. Set db_expires parameter
+   1.15. Set enable_dmq parameter
+   1.16. Set dmq_init_sync parameter
+   1.17. Set timer_procs parameter
+   1.18. Set event_callback parameter
+   1.19. Set event_callback_mode parameter
+   1.20. sht_print usage
+   1.21. sht_rm usage
+   1.22. sht_rm_name_re usage
+   1.23. sht_rm_value_re usage
+   1.24. sht_rm_name usage
+   1.25. sht_rm_value usage
+   1.26. sht_reset usage
+   1.27. sht_lock usage
+   1.28. sht_unlock usage
+   1.29. sht_iterator_start usage
+   1.30. sht_iterator_end usage
+   1.31. sht_iterator_next usage
+   1.32. sht_iterator_rm usage
+   1.33. sht_iterator_sets usage
+   1.34. sht_iterator_seti usage
+   1.35. sht_iterator_setex usage
+   1.36. sht_match_name usage
+   1.37. sht_match_name usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+        2.3. Loading from database
+
+   3. Parameters
+
+        3.1. htable (str)
+        3.2. db_url (str)
+        3.3. key_name_column (str)
+        3.4. key_type_column (str)
+        3.5. value_type_column (str)
+        3.6. key_value_column (str)
+        3.7. expires_column (str)
+        3.8. array_size_suffix (str)
+        3.9. fetch_rows (integer)
+        3.10. timer_interval (integer)
+        3.11. db_expires (integer)
+        3.12. enable_dmq (integer)
+        3.13. dmq_init_sync (integer)
+        3.14. timer_procs (integer)
+        3.15. event_callback (str)
+        3.16. event_callback_mode (int)
+
+   4. Functions
+
+        4.1. sht_print()
+        4.2. sht_rm(htname, itname)
+        4.3. sht_rm_name_re(htable=>regexp)
+        4.4. sht_rm_value_re(htable=>regexp)
+        4.5. sht_rm_name(htable, op, val)
+        4.6. sht_rm_value(htable, op, val)
+        4.7. sht_reset(htable)
+        4.8. sht_lock(htable=>key)
+        4.9. sht_unlock(htable=>key)
+        4.10. sht_iterator_start(iname, hname)
+        4.11. sht_iterator_end(iname)
+        4.12. sht_iterator_next(iname)
+        4.13. sht_iterator_rm(iname)
+        4.14. sht_iterator_sets(iname, sval)
+        4.15. sht_iterator_seti(iname, ival)
+        4.16. sht_iterator_setex(iname, exval)
+        4.17. sht_match_name(htable, op, mval)
+        4.18. sht_has_name(htable, op, mval)
+        4.19. sht_match_str_value(htable, op, mval)
+        4.20. sht_has_str_value(htable, op, mval)
+
+   5. Exported pseudo-variables
+   6. RPC Commands
+
+        6.1. htable.get htable key
+        6.2. htable.delete htable key
+        6.3. htable.sets htable key value
+        6.4. htable.seti htable key value
+        6.5. htable.setex htable key expire
+        6.6. htable.dump htable
+        6.7. htable.reload htable
+        6.8. htable.store htable
+        6.9. htable.flush htable
+        6.10. htable.listTables
+        6.11. htable.stats
+
+   7. Event routes
+
+        7.1. htable:mod-init
+        7.2. htable:expired:<table>
+
+1. Overview
+
+   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.
+
+   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.
+
+   Replication between multiple servers is performed automatically (if
+   enabled) via the DMQ module.
+
+   You can read more about hash tables at:
+   http://en.wikipedia.org/wiki/Hash_table.
+
+   The “name” can be a static string or can include pseudo- variables that
+   will be replaced at runtime.
+
+   Example 1.1. Accessing $sht(htname=>key)
+...
+modparam("htable", "htable", "a=>size=8;")
+...
+$sht(a=>test) = 1;
+$sht(a=>$ci::srcip) = $si;
+...
+
+   The next example shows a way to protect against dictionary attacks. If
+   someone fails to authenticate 3 times, it is forbidden for 15 minutes.
+   Authentication against database is expensive as it does a select on the
+   “subscriber” table. By disabling the DB auth for 15 minutes, 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.
+
+   To implement the logic, two hash table variables are used: one counting
+   the failed authentications per user and one for storing the time of the
+   last authentication attempt. To ensure a unique name per user, the hash
+   table uses a combination of authentication username and text
+   “::auth_count” and “::last_auth”.
+
+   Example 1.2. Dictionary attack limitation
+...
+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;
+}
+...
+
+   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'.
+
+   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).
+
+   Example 1.3. Storing array values
+# 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
+                }
+        }
+}
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+   2.3. Loading from database
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * If DMQ replication is enabled, the DMQ module must be loaded
+       first..
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * None.
+
+2.3. Loading from database
+
+   The module is able to load values in a hash table at startup upon
+   providing a DB URL and table name.
+
+   The structure of the table must contain:
+     * key name - string containing the name of the key.
+     * key type - the type of the key
+          + 0 - simple key - the key is added as 'key_name'.
+          + 1 - 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).
+     * value type - the type of the key value
+          + 0 - value is string.
+          + 1 - value is integer.
+     * key value - string containing the value of the key.
+
+3. Parameters
+
+   3.1. htable (str)
+   3.2. db_url (str)
+   3.3. key_name_column (str)
+   3.4. key_type_column (str)
+   3.5. value_type_column (str)
+   3.6. key_value_column (str)
+   3.7. expires_column (str)
+   3.8. array_size_suffix (str)
+   3.9. fetch_rows (integer)
+   3.10. timer_interval (integer)
+   3.11. db_expires (integer)
+   3.12. enable_dmq (integer)
+   3.13. dmq_init_sync (integer)
+   3.14. timer_procs (integer)
+   3.15. event_callback (str)
+   3.16. event_callback_mode (int)
+
+3.1. htable (str)
+
+   The definition of a hash table. The value of the parameter may have the
+   following format:
+     * "htname=>size=_number_;autoexpire=_number_;dbtable=_string_"
+
+   The parameter can be set multiple times to get more hash tables in same
+   configuration file.
+     * htname - string specifying the name of the hash table. This string
+       is used by $sht(...) to refer to the hash table.
+     * size - number to control how many slots (buckets) to create for the
+       hash table. Larger value means more slots with higher probability
+       for less collisions. The actual number slots (or buckets) created
+       for 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). Note that each slot can store
+       more than one item, when there are collisions of hash ids computed
+       for keys. The items in the same slot are stored in a linked list.
+       In other words, the size is not setting a limit of how many items
+       can be stored in a hash table, as long as there is enough free
+       shared memory, new items can be added.
+     * autoexpire -time in seconds to delete an item from a hash table if
+       no update was done to it. If is missing or set to 0, the items
+       won't expire.
+     * dbtable - name of database to be loaded at startup in hash table.
+       If empty or missing, no data will be loaded.
+     * cols - 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.
+     * dbmode - 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).
+     * initval - the integer value to be returned instead of $null when a
+       requested key is not set.
+     * updateexpire - 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.
+     * dmqreplicate - 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 “enable_dmq”
+       must also be set in order for this to apply (see below). Default is
+       0 (no replication).
+
+   Default value is NULL.
+
+   Example 1.4. Set htable parameter
+...
+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
+;")
+...
+
+3.2. db_url (str)
+
+   The URL to connect to database for loading values in hash table at
+   start up.
+
+   Default value is NULL (do not connect).
+
+   Example 1.5. Set db_url parameter
+...
+modparam("htable", "db_url", "mysql://kamailio:kamailiorw@localhost/kamailio")
+...
+
+3.3. key_name_column (str)
+
+   The name of the column containing the hash table key name.
+
+   Default value is 'key_name'.
+
+   Example 1.6. Set key_name_column parameter
+...
+modparam("htable", "key_name_column", "kname")
+...
+
+3.4. key_type_column (str)
+
+   The name of the column containing the hash table key type.
+
+   Default value is 'key_type'.
+
+   Example 1.7. Set key_type_column parameter
+...
+modparam("htable", "key_type_column", "ktype")
+...
+
+3.5. value_type_column (str)
+
+   The name of the column containing the hash table value type.
+
+   Default value is 'value_type'.
+
+   Example 1.8. Set value_type_column parameter
+...
+modparam("htable", "value_type_column", "vtype")
+...
+
+3.6. key_value_column (str)
+
+   The name of the column containing hash table key value.
+
+   Default value is 'key_value'.
+
+   Example 1.9. Set key_value_column parameter
+...
+modparam("htable", "key_value_column", "kvalue")
+...
+
+3.7. expires_column (str)
+
+   The name of the column containing the expires value.
+
+   Default value is 'expires'.
+
+   Example 1.10. Set expires_column parameter
+...
+modparam("htable", "expires_column", "expiry")
+...
+
+3.8. array_size_suffix (str)
+
+   The suffix to be added to store the number of items in an array (see
+   key type).
+
+   Default value is '::size'.
+
+   Example 1.11. Set array_size_suffix parameter
+...
+modparam("htable", "array_size_suffix", "-count")
+...
+
+3.9. fetch_rows (integer)
+
+   How many rows to fetch at once from database.
+
+   Default value is 100.
+
+   Example 1.12. Set fetch_rows parameter
+...
+modparam("htable", "fetch_rows", 1000)
+...
+
+3.10. timer_interval (integer)
+
+   Interval in seconds to check for expired htable values.
+
+   Default value is 20.
+
+   Example 1.13. Set timer_interval parameter
+...
+modparam("htable", "timer_interval", 10)
+...
+
+3.11. db_expires (integer)
+
+   If set to 1, the module loads/saves the value for expire of the items
+   in hash table from/to database. It applies only to hash tables that
+   have the auto-expires attribute defined. If set to 0, only the key name
+   and the value are loaded, the expires for each item being set to 0.
+
+   Note that the module is not reloading automatically the items from
+   database when they expire, the reloading can be done only via RPC
+   command.
+
+   Default value is 0.
+
+   Example 1.14. Set db_expires parameter
+...
+modparam("htable", "db_expires", 1)
+...
+
+3.12. enable_dmq (integer)
+
+   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 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.
+
+   Important: If this parameter is enabled, the DMQ module must be loaded
+   first - otherwise, startup will fail.
+
+   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.
+
+   Default value is 0.
+
+   Example 1.15. Set enable_dmq parameter
+...
+modparam("htable", "enable_dmq", 1)
+...
+
+3.13. dmq_init_sync (integer)
+
+   If set to 1, will request synchronization from other nodes at startup.
+   It applies to all tables having the "dmqreplicate" parameter set. As
+   above, it is important to ensure the definition (size, autoexpire etc.)
+   of replicated tables is identical across all instances.
+
+   Default value is 0.
+
+   Example 1.16. Set dmq_init_sync parameter
+...
+modparam("htable", "dmq_init_sync", 1)
+...
+
+3.14. timer_procs (integer)
+
+   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.
+
+   Default value is 0.
+
+   Example 1.17. Set timer_procs parameter
+...
+modparam("htable", "timer_procs", 4)
+...
+
+3.15. event_callback (str)
+
+   The name of the function in the kemi configuration file (embedded
+   scripting language such as Lua, Python, ...) to be executed instead of
+   event_route[...] blocks.
+
+   The function receives a string parameter with the name of the event,
+   the values can be: 'htable:mod-init', 'htable:expired:htname' ('htname'
+   being the name of hash table).
+
+   Default value is 'empty' (no function is executed for events).
+
+   Example 1.18. Set event_callback parameter
+...
+modparam("htable", "event_callback", "ksr_htable_event")
+...
+-- event callback function implemented in Lua
+function ksr_htable_event(evname)
+        KSR.info("===== htable module triggered event: " .. evname .. "\n");
+        return 1;
+end
+...
+
+3.16. event_callback_mode (int)
+
+   Control when event_route[htable:init] is executed: 0 - after all
+   modules were initialized; 1 - in first worker process.
+
+   Set it to 1 if used in a KEMI script or when needing to use database
+   (e.g., via sqlops) inside event_route[htable:init].
+
+   Default value is 0.
+
+   Example 1.19. Set event_callback_mode parameter
+...
+modparam("htable", "event_callback_mode", 1)
+...
+
+4. Functions
+
+   4.1. sht_print()
+   4.2. sht_rm(htname, itname)
+   4.3. sht_rm_name_re(htable=>regexp)
+   4.4. sht_rm_value_re(htable=>regexp)
+   4.5. sht_rm_name(htable, op, val)
+   4.6. sht_rm_value(htable, op, val)
+   4.7. sht_reset(htable)
+   4.8. sht_lock(htable=>key)
+   4.9. sht_unlock(htable=>key)
+   4.10. sht_iterator_start(iname, hname)
+   4.11. sht_iterator_end(iname)
+   4.12. sht_iterator_next(iname)
+   4.13. sht_iterator_rm(iname)
+   4.14. sht_iterator_sets(iname, sval)
+   4.15. sht_iterator_seti(iname, ival)
+   4.16. sht_iterator_setex(iname, exval)
+   4.17. sht_match_name(htable, op, mval)
+   4.18. sht_has_name(htable, op, mval)
+   4.19. sht_match_str_value(htable, op, mval)
+   4.20. sht_has_str_value(htable, op, mval)
+
+4.1.  sht_print()
+
+   Dump content of hash table to L_ERR log level. Intended for debug
+   purposes.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   ONREPLY_ROUTE, BRANCH_ROUTE.
+
+   Example 1.20. sht_print usage
+...
+sht_print();
+...
+
+4.2.  sht_rm(htname, itname)
+
+   Delete the item with the name 'itname' from hash table 'htname'. This
+   API function equivaluent to '$sht(htname=>itname) = $null'.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.21. sht_rm usage
+...
+sht_rm("ha", "test"");
+...
+
+4.3.  sht_rm_name_re(htable=>regexp)
+
+   Delete all entries in the htable that match the name against regular
+   expression.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   ONREPLY_ROUTE, BRANCH_ROUTE.
+
+   Example 1.22. sht_rm_name_re usage
+...
+sht_rm_name_re("ha=>.*");
+...
+
+4.4.  sht_rm_value_re(htable=>regexp)
+
+   Delete all entries in the htable that match the value against regular
+   expression.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   ONREPLY_ROUTE, BRANCH_ROUTE.
+
+   Example 1.23. sht_rm_value_re usage
+...
+sht_rm_value_re("ha=>.*");
+...
+
+4.5.  sht_rm_name(htable, op, val)
+
+   Delete all entries in the htable that match the name against the val
+   parameter.
+
+   The op parameter can be:
+     * re - match the val parameter as regular expression.
+     * sw - match the val parameter as 'starts with'.
+
+   All parameters can be static strings or contain variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.24. sht_rm_name usage
+...
+sht_rm_name("ha", "re", ".*");
+...
+
+4.6.  sht_rm_value(htable, op, val)
+
+   Delete all entries in the htable that match the value against the val
+   parameter.
+
+   The op parameter can be:
+     * re - match the val parameter as regular expression.
+     * sw - match the val parameter as 'starts with'.
+
+   All parameters can be static strings or contain variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.25. sht_rm_value usage
+...
+sht_rm_value("ha", "re", ".*");
+...
+
+4.7.  sht_reset(htable)
+
+   Delete all entries in the htable. The name of the hash table can be a
+   dynamic string with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.26. sht_reset usage
+...
+sht_reset("ha$var(x)");
+...
+
+4.8.  sht_lock(htable=>key)
+
+   Lock the slot in htable corresponding 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.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.27. sht_lock usage
+...
+sht_lock("ha=>test");
+...
+
+4.9.  sht_unlock(htable=>key)
+
+   Unlock the slot in htable corresponding 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.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.28. sht_unlock usage
+...
+sht_lock("ha=>test");
+$sht(ha=>test) = $sht(ha=>test) + 10;
+sht_unlock("ha=>test");
+...
+
+4.10.  sht_iterator_start(iname, hname)
+
+   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.
+
+   Both parameters can be dynamic strings with variables.
+
+   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.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.29. sht_iterator_start usage
+...
+sht_iterator_start("i1", "h1");
+...
+
+4.11.  sht_iterator_end(iname)
+
+   Close the iterator identified by iname parameter and release the hash
+   table slot acquired by the iterator. The iname value must be the same
+   used for sht_iterator_start().
+
+   The parameter can be dynamic string with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.30. sht_iterator_end usage
+...
+sht_iterator_end("i1");
+...
+
+4.12.  sht_iterator_next(iname)
+
+   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.
+
+   The return code is false when there is no (more) item in the hash
+   table.
+
+   The item name and value are accessible via variables: $shtitkey(iname)
+   and $shtitval(iname).
+
+   The parameter can be dynamic string with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.31. sht_iterator_next usage
+...
+    sht_iterator_start("i1", "h1");
+    while(sht_iterator_next("i1")) {
+        xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
+    }
+    sht_iterator_end("i1");
+...
+
+4.13.  sht_iterator_rm(iname)
+
+   Remove the current item in the iterator and move the iterator to the
+   next one.
+
+   The return code is 1 (true) if the item was removed and next item
+   exists; -2 (false) if the item was removed and there is no next item
+   (end of items); other negative value (false) can be returned on error
+   (e.g., iterator or item not found).
+
+   The parameter can be dynamic string with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.32. sht_iterator_rm usage
+...
+    sht_iterator_start("i1", "h1");
+    while(sht_iterator_next("i1")) {
+        while($shtitkey(i1) =~ "xyz" and sht_iterator_rm("i1")) {
+            xdbg("item removed\n");
+        }
+    }
+    sht_iterator_end("i1");
+...
+
+4.14.  sht_iterator_sets(iname, sval)
+
+   Set the value of the current item to the string in the sval.
+
+   The parameters can be dynamic strings with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.33. sht_iterator_sets usage
+...
+    sht_iterator_start("i1", "h1");
+    sht_iterator_next("i1");
+    sht_iterator_sets("i1", "$ci");
+    sht_iterator_end("i1");
+...
+
+4.15.  sht_iterator_seti(iname, ival)
+
+   Set the value of the current item to the integer in the ival.
+
+   The parameters can be dynamic strings or integers with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.34. sht_iterator_seti usage
+...
+    sht_iterator_start("i1", "h1");
+    sht_iterator_next("i1");
+    sht_iterator_seti("i1", "20");
+    sht_iterator_end("i1");
+...
+
+4.16.  sht_iterator_setex(iname, exval)
+
+   Set the expire of the current item to the integer in the exval.
+
+   The parameters can be dynamic strings or integers with variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.35. sht_iterator_setex usage
+...
+    sht_iterator_start("i1", "h1");
+    sht_iterator_next("i1");
+    sht_iterator_setex("i1", "120");
+    sht_iterator_end("i1");
+...
+
+4.17.  sht_match_name(htable, op, mval)
+
+   Return greater than 0 (true) if the htable has an item that matches the
+   name against the mval parameter.
+
+   The op parameter can be:
+     * eq - match the val parameter as string equal expression.
+     * ne - match the val parameter as string not-equal expression.
+     * re - match the val parameter as regular expression.
+     * sw - match the val parameter as 'starts with' expression.
+
+   All parameters can be static strings or contain variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.36. sht_match_name usage
+...
+if(sht_match_name("ha", "eq", "alice")) {
+  ...
+}
+...
+
+4.18.  sht_has_name(htable, op, mval)
+
+   Alias for sht_match_name().
+
+4.19.  sht_match_str_value(htable, op, mval)
+
+   Return greater than 0 (true) if the htable has an item that matches the
+   string value against the mval parameter.
+
+   The op parameter can be:
+     * eq - match the val parameter as string equal expression.
+     * ne - match the val parameter as string not-equal expression.
+     * re - match the val parameter as regular expression.
+     * sw - match the val parameter as 'starts with' expression.
+
+   All parameters can be static strings or contain variables.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.37. sht_match_name usage
+...
+if(sht_match_str_value("ha", "eq", "alice")) {
+  ...
+}
+...
+
+4.20.  sht_has_str_value(htable, op, mval)
+
+   Alias for sht_match_str_value().
+
+5. Exported pseudo-variables
+
+     * $sht(htable=>key)
+     * $shtex(htable=>key)
+     * $shtcn(htable=>key)
+     * $shtcv(htable=>key)
+     * $shtinc(htable=>key)
+     * $shtitkey(iname)
+     * $shtitval(iname)
+     * $shtrecord(attribute)
+
+   Exported pseudo-variables are documented at
+   https://www.kamailio.org/wiki/.
+
+6. RPC Commands
+
+   6.1. htable.get htable key
+   6.2. htable.delete htable key
+   6.3. htable.sets htable key value
+   6.4. htable.seti htable key value
+   6.5. htable.setex htable key expire
+   6.6. htable.dump htable
+   6.7. htable.reload htable
+   6.8. htable.store htable
+   6.9. htable.flush htable
+   6.10. htable.listTables
+   6.11. htable.stats
+
+6.1.  htable.get htable key
+
+   Lists one value in a hash table
+
+   Name: htable.get
+
+   Parameters:
+     * htable : Name of the hash table to dump
+     * key : Key name of the hash table value to dump
+
+   Example:
+...
+# Dump $sht(students=>alice)
+kamcmd htable.get students alice
+
+# Dump first entry in array key course $sht(students=>course[0])
+kamcmd htable.get students course[0]
+...
+
+6.2.  htable.delete htable key
+
+   Delete one value in a hash table
+
+   Name: htable.delete
+
+   Parameters:
+     * htable : Name of the hash table to delete
+     * key : Key name of the hash table value to delete
+
+   Example:
+...
+# Delete $sht(students=>alice)
+kamcmd htable.delete students alice
+
+# Delete first entry in array key course $sht(students=>course[0])
+kamcmd htable.delete students course[0]
+...
+
+6.3.  htable.sets htable key value
+
+   Set an item in hash table to string value.
+
+   Name: htable.sets
+
+   Parameters:
+     * htable : Name of the hash table
+     * key : Key name in the hash table
+     * Value : String value for the item
+
+   Example:
+...
+# 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
+...
+
+6.4.  htable.seti htable key value
+
+   Set an item in hash table to integer value.
+
+   Name: htable.seti
+
+   Parameters:
+     * htable : Name of the hash table
+     * key : Key name in the hash table
+     * Value : Integer value for the item
+
+   Example:
+...
+# Set $sht(test=>x) as integer
+kamcmd htable.seti test x 123
+
+# Set first entry in array key x $sht(test=>x[0]) as integer
+kamcmd htable.seti test x[0] 123
+...
+
+6.5.  htable.setex htable key expire
+
+   Set the expire for an item in hash table.
+
+   Name: htable.setex
+
+   Parameters:
+     * htable : name of the hash table
+     * key : key name in the hash table
+     * expire : integer value for the expire (seconds)
+
+   Example:
+...
+# set  expire for $sht(test=>x) to 120 secs
+kamctl rpc htable.seti test x 120
+...
+
+6.6.  htable.dump htable
+
+   Lists all the values in a hash table
+
+   Name: htable.dump
+
+   Parameters:
+     * htable : Name of the hash table to dump
+
+   Example:
+...
+kamcmd htable.dump ipban
+...
+
+6.7.  htable.reload htable
+
+   Reload hash table from database.
+
+   Name: htable.reload
+
+   Parameters:
+     * htable : Name of the hash table to reload
+
+   Example:
+...
+kamcmd htable.reload ipban
+...
+
+6.8.  htable.store htable
+
+   Store hash table to database.
+
+   Name: htable.store
+
+   Parameters:
+     * htable : Name of the hash table to store
+
+   Example:
+...
+kamcmd htable.store ipban
+...
+
+6.9.  htable.flush htable
+
+   Empty the hash table
+
+   Name: htable.flush
+
+   Parameters:
+     * htable : Name of the hash table to flush
+
+   Example:
+...
+kamcmd htable.flush ipban
+...
+
+6.10.  htable.listTables
+
+   Lists all defined tables
+
+   Name: htable.listTables
+
+   Parameters:
+     * None
+
+   Example:
+...
+kamcmd htable.listTables
+...
+
+6.11.  htable.stats
+
+   Get statistics for hash tables - name, number of slots, number of
+   items, max number of items per slot, min number of items per slot.
+
+   Name: htable.stats
+
+   Parameters:
+     * None
+
+   Example:
+...
+kamcmd htable.stats
+...
+
+7. Event routes
+
+   7.1. htable:mod-init
+   7.2. htable:expired:<table>
+
+7.1.  htable:mod-init
+
+   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.
+
+   Note: do not expect to use functions from all other modules here, even
+   if they are loaded before the htable module, because many of them
+   initialize their runtime structures inside child init callbacks, which
+   are executed after this moment, when forking child processes. For
+   example, sqlops cannot be used, connections to database are initialized
+   in child init. Even more, it is recommended not to use functions from
+   other modules, because it can mess up what they created in mod init
+   callback and expect in child init callback. It should be ok to use
+   functions from htable module or assignment operations.
+...
+event_route[htable:mod-init] {
+    $sht(a=>x) = 1;
+}
+...
+
+7.2.  htable:expired:<table>
+
+   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.
+...
+
+event_route[htable:expired:mytable] {
+    xlog("mytable record expired $shtrecord(key) => $shtrecord(value)\n");
+}
+...