name mode size
..
doc 040000
Makefile 100644 406B
README 100644 20.55kB
api.c 100644 3.22kB
api.h 100644 2.1kB
ht_api.c 100644 25.01kB
ht_api.h 100644 2.74kB
ht_db.c 100644 10.59kB
ht_db.h 100644 1.43kB
ht_dmq.c 100644 7kB
ht_dmq.h 100644 1.69kB
ht_var.c 100644 8.07kB
ht_var.h 100644 1.62kB
htable.c 100644 25.21kB
README
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> Edited by Ovidiu Sas <osas@voipembedded.com> Copyright © 2008-2011 http://www.asipto.com __________________________________________________________________ Table of Contents 1. Admin Guide 1.1. Overview 1.2. Dependencies 1.2.1. Kamailio Modules 1.2.2. External Libraries or Applications 1.2.3. Loading from database 1.3. Parameters 1.3.1. htable (str) 1.3.2. db_url (str) 1.3.3. key_name_column (str) 1.3.4. key_type_column (str) 1.3.5. value_type_column (str) 1.3.6. key_value_column (str) 1.3.7. expires_column (str) 1.3.8. array_size_suffix (str) 1.3.9. fetch_rows (integer) 1.3.10. timer_interval (integer) 1.3.11. timer_mode (integer) 1.3.12. db_expires (integer) 1.3.13. enable_dmq (integer) 1.4. Functions 1.4.1. sht_print() 1.4.2. sht_rm_name_re(htable=>regexp) 1.4.3. sht_rm_value_re(htable=>regexp) 1.4.4. sht_lock(htable=>key) 1.4.5. sht_unlock(htable=>key) 1.5. Exported pseudo-variables 1.6. MI Commands 1.6.1. sht_reload 1.6.2. sht_dump 1.6.3. sht_delete 1.7. Exported RPC Commands 1.7.1. htable.get htable key 1.7.2. htable.delete htable key 1.7.3. htable.sets htable key value 1.7.4. htable.seti htable key value 1.7.5. htable.dump htable 1.7.6. htable.reload htable 1.7.7. htable.listTables 1.7.8. htable.stats 1.8. Event routes 1.8.1. htable:mod-init List of Examples 1.1. Accessing $sht(htname=>key) 1.2. Dictionary attack limitation 1.3. Storring array values 1.4. Set hash_size 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 timer_mode parameter 1.15. Set db_expires parameter 1.16. Set enable_dmq parameter 1.17. sht_print usage 1.18. sht_rm_name_re usage 1.19. sht_rm_value_re usage 1.20. sht_lock usage 1.21. sht_unlock usage Chapter 1. Admin Guide 1.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. 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; ... 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 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 administarator's responsability to update the size of the array and any other elements (if required). Example 1.3. Storring 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 } } } 1.2. Dependencies 1.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.. 1.2.2. External Libraries or Applications The following libraries or applications must be installed before running Kamailio with this module loaded: * None. 1.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. 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. 1.3. Parameters 1.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 31, smaller or larger values will be increased to 3 (8 slots) or decreased to 14 (16384 slots). * 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. * 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 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;dmqreplicate= 1;") ... 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") ... 1.3.3. key_name_column (str) The name of the column containing hash table key name. Default value is 'key_name'. Example 1.6. Set key_name_column parameter ... modparam("htable", "key_name_column", "kname") ... 1.3.4. key_type_column (str) The name of the column containing hash table key type. Default value is 'key_type'. Example 1.7. Set key_type_column parameter ... modparam("htable", "key_type_column", "ktype") ... 1.3.5. value_type_column (str) The name of the column containing hash table value type. Default value is 'value_type'. Example 1.8. Set value_type_column parameter ... modparam("htable", "value_type_column", "vtype") ... 1.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") ... 1.3.7. expires_column (str) The name of the column containing expires type. Default value is 'expires'. Example 1.10. Set expires_column parameter ... modparam("htable", "expires", "expiry") ... 1.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") ... 1.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) ... 1.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) ... 1.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.14. Set timer_mode parameter ... modparam("htable", "timer_mode", 1) ... 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.15. Set db_expires parameter ... modparam("htable", "db_expires", 1) ... 1.3.13. 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 psuedo-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. 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.16. Set enable_dmq parameter ... modparam("htable", "enable_dmq", 1) ... 1.4. Functions 1.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.17. sht_print usage ... sht_print(); ... 1.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.18. sht_rm_name_re usage ... sht_rm_name_re("ha=>.*"); ... 1.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.19. sht_rm_value_re usage ... sht_rm_value_re("ha=>.*"); ... 1.4.4. sht_lock(htable=>key) Lock the slot in htable corespoding to the key item. This function can be used from ANY_ROUTE. Example 1.20. sht_lock usage ... sht_lock("ha=>test"); ... 1.4.5. sht_unlock(htable=>key) Unlock the slot in htable corespoding to the key item. This function can be used from ANY_ROUTE. Example 1.21. sht_unlock usage ... sht_lock("ha=>test"); $sht(ha=>test) = $sht(ha=>test) + 10; sht_unlock("ha=>test"); ... 1.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/. 1.6. MI Commands 1.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_ 1.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_ 1.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"' 1.7. Exported RPC Commands 1.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 # Dump first entry in array key course $sht(students=>course[0]) kamcmd htable.get students course[0] ... 1.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.delete students anna # Delete first entry in array key course $sht(students=>course[0]) kamcmd htable.delete students course[0] ... 1.7.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 ... 1.7.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 firsti entry in array key x $sht(test=>x[0]) as integer kamcmd htable.sets test x[0] 123 ... 1.7.5. 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 ... 1.7.6. htable.reload htable Reload hash table from database. Name: dhtable.reload Parameters: * htable : Name of the hash table to reload Example: ... kamcmd htable.reload ipban ... 1.7.7. htable.listTables Lists all defined tables Name: htable.listTables Parameters: * None Example: ... kamcmd htable.listTables ... 1.7.8. 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 ... 1.8. Event routes 1.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; } ...