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.
633 lines
16 KiB
633 lines
16 KiB
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;
|
|
}
|
|
...
|