Table of Contents
htable (str)
db_url (str)
key_name_column (str)
key_type_column (str)
value_type_column (str)
key_value_column (str)
expires_column (str)
array_size_suffix (str)
fetch_rows (integer)
timer_interval (integer)
timer_mode (integer)
db_expires (integer)
List of Examples
hash_size parameterdb_url parameterkey_name_column parameterkey_type_column parametervalue_type_column parameterkey_value_column parameterexpires_column parameterarray_size_suffix parameterfetch_rows parametertimer_interval parametertimer_mode parameterdb_expires parametersht_print usagesht_rm_name_re usagesht_rm_value_re usageTable of Contents
htable (str)
db_url (str)
key_name_column (str)
key_type_column (str)
value_type_column (str)
key_value_column (str)
expires_column (str)
array_size_suffix (str)
fetch_rows (integer)
timer_interval (integer)
timer_mode (integer)
db_expires (integer)
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;
}
...
The following modules must be loaded before this module:
No dependencies on other Kamailio modules.
The following libraries or applications must be installed before running Kamailio with this module loaded:
None.
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.
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;")
...
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://openser:openserrw@localhost/openser")
...
The name of the column containing hash table key name.
Default value is 'key_name'.
The name of the column containing hash table key type.
Default value is 'key_type'.
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")
...
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")
...
The name of the column containing expires type.
Default value is 'expires'.
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")
...
How many rows to fetch at once from database.
Default value is 100.
Interval in seconds to check for expired htable values.
Default value is 20.
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.
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.
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.
$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/dokuwiki/.
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_
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_
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"'