kamailio/modules/htable

HTable Module

Elena-Ramona Modroiu

   asipto.com
   <ramona@rosdev.ro>

Edited by

Elena-Ramona Modroiu

   <ramona@rosdev.ro>

Edited by

Alex Balashov

   <abalashov@evaristesys.com>

   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. timer_mode (integer)
              3.12. db_expires (integer)

        4. Functions

              4.1. sht_print()
              4.2. sht_rm_name_re(htable=>regexp)
              4.3. sht_rm_value_re(htable=>regexp)

        5. Exported pseudo-variables
        6. MI Commands

              6.1. sht_reload
              6.2. sht_dump
              6.3. sht_delete

        7. Exported RPC Commands

              7.1. htable.get htable key
              7.2. htable.delete htable key
              7.3. htable.dump htable
              7.4. htable.listTables

        8. Event routes

              8.1. htable:mod-init

   List of Examples

   1.1. Accessing $sht(htname=>key)
   1.2. Dictionary attack limitation
   1.3. Set hash_size parameter
   1.4. Set db_url parameter
   1.5. Set key_name_column parameter
   1.6. Set key_type_column parameter
   1.7. Set value_type_column parameter
   1.8. Set key_value_column parameter
   1.9. Set expires_column parameter
   1.10. Set array_size_suffix parameter
   1.11. Set fetch_rows parameter
   1.12. Set timer_interval parameter
   1.13. Set timer_mode parameter
   1.14. Set db_expires parameter
   1.15. sht_print usage
   1.16. sht_rm_name_re usage
   1.17. sht_rm_value_re 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. timer_mode (integer)
        3.12. db_expires (integer)

   4. Functions

        4.1. sht_print()
        4.2. sht_rm_name_re(htable=>regexp)
        4.3. sht_rm_value_re(htable=>regexp)

   5. Exported pseudo-variables
   6. MI Commands

        6.1. sht_reload
        6.2. sht_dump
        6.3. sht_delete

   7. Exported RPC Commands

        7.1. htable.get htable key
        7.2. htable.delete htable key
        7.3. htable.dump htable
        7.4. htable.listTables

   8. Event routes

        8.1. htable:mod-init

1. Overview

   The module adds a hash table container to 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 itme via assignment operation at runtime.

   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;
...

   Next example shows a way to protect against dictionary attacks. If
   someone fails to authenticate 3 times, it is forbidden for 15min.
   Authenticatin against database is expensive as it does a select on
   subscriber table. By disabling the DB auth for 15min, resources on
   server as 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 user: one counting
   the failed authentications per user and one for storing the time of
   last authentication attempt. To ensure 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;
}
...

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:
     * No dependencies on other Kamailio modules.

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 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.
     * 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. timer_mode (integer)
   3.12. db_expires (integer)

3.1. htable (str)

   The definition of a hash table. The value of the parameter must 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 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
       14, smaller or larger values will be increased or decreased
       respectivly.
     * autoexpire -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.
     * dbtable - name of database to be loaded at startup in hash table.
       If empty or missing, no data will be loaded.
     * 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.

   Default value is NULL.

   Example 1.3. Set hash_size 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;")
...

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.4. 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 hash table key name.

   Default value is 'key_name'.

   Example 1.5. Set key_name_column parameter
...
modparam("htable", "key_name_column", "kname")
...

3.4. key_type_column (str)

   The name of the column containing hash table key type.

   Default value is 'key_type'.

   Example 1.6. Set key_type_column parameter
...
modparam("htable", "key_type_column", "ktype")
...

3.5. value_type_column (str)

   The name of the column containing hash table value type.

   Default value is 'value_type'.

   Example 1.7. 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.8. Set key_value_column parameter
...
modparam("htable", "key_value_column", "kvalue")
...

3.7. expires_column (str)

   The name of the column containing expires type.

   Default value is 'expires'.

   Example 1.9. Set expires_column parameter
...
modparam("htable", "expires", "expiry")
...

3.8. array_size_suffix (str)

   The suffix to be added to store the number of items in an array.

   Default value is '::size'.

   Example 1.10. 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.11. 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.12. Set timer_interval parameter
...
modparam("htable", "timer_interval", 10)
...

3.11. timer_mode (integer)

   If set to 1, will start a new timer process. If set to 0 will use
   default timer process to check for expired htable values.

   Default value is 0.

   Example 1.13. Set timer_mode parameter
...
modparam("htable", "timer_mode", 1)
...

3.12. db_expires (integer)

   If set to 1, will load/save the expires values of the items in hash
   table fromm/to database. It applies only to hash tables that have
   auto-expires attribute defined.

   Default value is 0.

   Example 1.14. Set db_expires parameter
...
modparam("htable", "db_expires", 1)
...

4. Functions

   4.1. sht_print()
   4.2. sht_rm_name_re(htable=>regexp)
   4.3. sht_rm_value_re(htable=>regexp)

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.15. sht_print usage
...
sht_print();
...

4.2. 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.16. sht_rm_name_re usage
...
sht_rm_name_re("ha=>.*");
...

4.3. 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.17. sht_rm_value_re usage
...
sht_rm_value_re("ha=>.*");
...

5. Exported pseudo-variables

     * $sht(htable=>key)
     * $shtex(htable=>key)
     * $shtcn(htable=>key)
     * $shtcv(htable=>key)
     * $shtinc(htable=>key)
     * $shtval(htable=>key)

   Exported pseudo-variables are documented at
   http://www.kamailio.org/wiki/.

6. MI Commands

   6.1. sht_reload
   6.2. sht_dump
   6.3. sht_delete

6.1. sht_reload

   Reload a hash table from database.

   Name: sht_reload

   Parameters: _hash_table_name_ - the name of hash table to reload.

   MI FIFO Command Format:
                :sht_reload:_reply_fifo_file_
                _hash_table_name_
                _empty_line_

6.2. sht_dump

   Dump content of a hash table via MI.

   Name: sht_dump

   Parameters: _hash_table_name_ - the name of hash table to dump.

   MI FIFO Command Format:
                :sht_dump:_reply_fifo_file_
                _hash_table_name_
                _empty_line_

6.3. sht_delete

   Delete a key from a hash table via MI.

   Name: sht_delete

   Parameters:
     * _hash_table_name: The table name to delete the key from
     * _key_name: The key to delete from the htable

   MI FIFO Command Format:
                :sht_delete:_reply_fifo_file_
                _hash_table_name_
                _key_name_
                _empty_line_

   Example (note the quoting when executing it via FIFO):
                kamctl fifo sht_delete auth '"user@example.org::last_auth"'

7. Exported RPC Commands

   7.1. htable.get htable key
   7.2. htable.delete htable key
   7.3. htable.dump htable
   7.4. htable.listTables

7.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=>daniel)
kamcmd htable.get students daniel
...

7.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=>anna)
kamcmd htable.get students anna
...

7.3. htable.dump htable

   Lists all the values in a hash table

   Name: dhtable.dump

   Parameters:
     * htable : Name of the hash table to dump

   Example:
...
kamcmd htable.dump ipban
...

7.4. htable.listTables

   Lists all defined tables

   Name: dhtable.listTables

   Parameters:
     * None

   Example:
...
kamcmd htable.listTables
...

8. Event routes

   8.1. htable:mod-init

8.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.
...
event_route[htable:mod-init] {
    $sht(a=>x) = 1;
}
...