|
|
@@ -12,42 +12,43 @@ Elena-Ramona Modroiu
|
|
|
<[email protected]>
|
|
|
|
|
|
Copyright © 2008 http://www.asipto.com
|
|
|
- __________________________________________________________
|
|
|
+ __________________________________________________________________
|
|
|
|
|
|
Table of Contents
|
|
|
|
|
|
1. Admin Guide
|
|
|
|
|
|
- 1.1. Overview
|
|
|
- 1.2. Dependencies
|
|
|
+ 1. Overview
|
|
|
+ 2. Dependencies
|
|
|
|
|
|
- 1.2.1. Kamailio Modules
|
|
|
- 1.2.2. External Libraries or Applications
|
|
|
- 1.2.3. Loading from database
|
|
|
+ 2.1. Kamailio Modules
|
|
|
+ 2.2. External Libraries or Applications
|
|
|
+ 2.3. Loading from database
|
|
|
|
|
|
- 1.3. Exported Parameters
|
|
|
+ 3. Exported 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. array_size_suffix (str)
|
|
|
- 1.3.8. fetch_rows (integer)
|
|
|
- 1.3.9. timer_interval (integer)
|
|
|
- 1.3.10. timer_mode (integer)
|
|
|
+ 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. array_size_suffix (str)
|
|
|
+ 3.8. fetch_rows (integer)
|
|
|
+ 3.9. timer_interval (integer)
|
|
|
+ 3.10. timer_mode (integer)
|
|
|
|
|
|
- 1.4. Exported Functions
|
|
|
+ 4. Exported Functions
|
|
|
|
|
|
- 1.4.1. sht_print()
|
|
|
- 1.4.2. sht_rm_name_re(htable=>regexp)
|
|
|
- 1.4.3. sht_rm_value_re(htable=>regexp)
|
|
|
+ 4.1. sht_print()
|
|
|
+ 4.2. sht_rm_name_re(htable=>regexp)
|
|
|
+ 4.3. sht_rm_value_re(htable=>regexp)
|
|
|
|
|
|
- 1.5. Exported pseudo-variables
|
|
|
- 1.6. Exported MI Functions
|
|
|
+ 5. Exported pseudo-variables
|
|
|
+ 6. Exported MI Functions
|
|
|
|
|
|
- 1.6.1. sht_reload
|
|
|
+ 6.1. sht_reload
|
|
|
+ 6.2. sht_dump
|
|
|
|
|
|
List of Examples
|
|
|
|
|
|
@@ -69,15 +70,48 @@ Elena-Ramona Modroiu
|
|
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
|
|
-1.1. Overview
|
|
|
+ Table of Contents
|
|
|
+
|
|
|
+ 1. Overview
|
|
|
+ 2. Dependencies
|
|
|
+
|
|
|
+ 2.1. Kamailio Modules
|
|
|
+ 2.2. External Libraries or Applications
|
|
|
+ 2.3. Loading from database
|
|
|
+
|
|
|
+ 3. Exported 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. array_size_suffix (str)
|
|
|
+ 3.8. fetch_rows (integer)
|
|
|
+ 3.9. timer_interval (integer)
|
|
|
+ 3.10. timer_mode (integer)
|
|
|
+
|
|
|
+ 4. Exported Functions
|
|
|
|
|
|
- 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).
|
|
|
+ 4.1. sht_print()
|
|
|
+ 4.2. sht_rm_name_re(htable=>regexp)
|
|
|
+ 4.3. sht_rm_value_re(htable=>regexp)
|
|
|
|
|
|
- The "name" can be a static string or can include pseudo-
|
|
|
- variables that will be replaced at runtime.
|
|
|
+ 5. Exported pseudo-variables
|
|
|
+ 6. Exported MI Functions
|
|
|
+
|
|
|
+ 6.1. sht_reload
|
|
|
+ 6.2. sht_dump
|
|
|
+
|
|
|
+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 "name" can be a static string or can include pseudo- variables that
|
|
|
+ will be replaced at runtime.
|
|
|
|
|
|
Example 1.1. Accessing $sht(htname=>key)
|
|
|
...
|
|
|
@@ -87,20 +121,19 @@ $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.
|
|
|
+ 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".
|
|
|
+ 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
|
|
|
...
|
|
|
@@ -144,20 +177,24 @@ if(is_present_hf("Authorization"))
|
|
|
}
|
|
|
...
|
|
|
|
|
|
-1.2. Dependencies
|
|
|
+2. Dependencies
|
|
|
+
|
|
|
+ 2.1. Kamailio Modules
|
|
|
+ 2.2. External Libraries or Applications
|
|
|
+ 2.3. Loading from database
|
|
|
|
|
|
-1.2.1. Kamailio Modules
|
|
|
+2.1. Kamailio Modules
|
|
|
|
|
|
The following modules must be loaded before this module:
|
|
|
* No dependencies on other Kamailio modules.
|
|
|
|
|
|
-1.2.2. External Libraries or Applications
|
|
|
+2.2. External Libraries or Applications
|
|
|
|
|
|
- The following libraries or applications must be installed
|
|
|
- before running Kamailio with this module loaded:
|
|
|
+ The following libraries or applications must be installed before
|
|
|
+ running Kamailio with this module loaded:
|
|
|
* None.
|
|
|
|
|
|
-1.2.3. Loading from database
|
|
|
+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.
|
|
|
@@ -166,59 +203,66 @@ if(is_present_hf("Authorization"))
|
|
|
* 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.
|
|
|
+ + 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.
|
|
|
|
|
|
-1.3. Exported 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. The number
|
|
|
- of entries in the table is 2^size
|
|
|
- * 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.
|
|
|
+3. Exported 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. array_size_suffix (str)
|
|
|
+ 3.8. fetch_rows (integer)
|
|
|
+ 3.9. timer_interval (integer)
|
|
|
+ 3.10. timer_mode (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. The number of
|
|
|
+ entries in the table is 2^size
|
|
|
+ * 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.
|
|
|
|
|
|
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", "a=>size=4;autoexpire=7200;dbtable=htable_a
|
|
|
-;")
|
|
|
+modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
|
|
|
+modparam("htable", "htable", "a=>size=4;autoexpire=7200;dbtable=htable_a;")
|
|
|
...
|
|
|
|
|
|
-1.3.2. db_url (str)
|
|
|
+3.2. db_url (str)
|
|
|
|
|
|
- The URL to connect to database for loading values in hash table
|
|
|
- at start up.
|
|
|
+ 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/opense
|
|
|
-r")
|
|
|
+modparam("htable", "db_url", "mysql://openser:openserrw@localhost/openser")
|
|
|
...
|
|
|
|
|
|
-1.3.3. key_name_column (str)
|
|
|
+3.3. key_name_column (str)
|
|
|
|
|
|
The name of the column containing hash table key name.
|
|
|
|
|
|
@@ -229,7 +273,7 @@ r")
|
|
|
modparam("htable", "key_name_column", "kname")
|
|
|
...
|
|
|
|
|
|
-1.3.4. key_type_column (str)
|
|
|
+3.4. key_type_column (str)
|
|
|
|
|
|
The name of the column containing hash table key type.
|
|
|
|
|
|
@@ -240,7 +284,7 @@ modparam("htable", "key_name_column", "kname")
|
|
|
modparam("htable", "key_type_column", "ktype")
|
|
|
...
|
|
|
|
|
|
-1.3.5. value_type_column (str)
|
|
|
+3.5. value_type_column (str)
|
|
|
|
|
|
The name of the column containing hash table value type.
|
|
|
|
|
|
@@ -251,7 +295,7 @@ modparam("htable", "key_type_column", "ktype")
|
|
|
modparam("htable", "value_type", "vtype")
|
|
|
...
|
|
|
|
|
|
-1.3.6. key_value_column (str)
|
|
|
+3.6. key_value_column (str)
|
|
|
|
|
|
The name of the column containing hash table key value.
|
|
|
|
|
|
@@ -262,10 +306,9 @@ modparam("htable", "value_type", "vtype")
|
|
|
modparam("htable", "key_value", "kvalue")
|
|
|
...
|
|
|
|
|
|
-1.3.7. array_size_suffix (str)
|
|
|
+3.7. array_size_suffix (str)
|
|
|
|
|
|
- The suffix to be added to store the number of items in an
|
|
|
- array.
|
|
|
+ The suffix to be added to store the number of items in an array.
|
|
|
|
|
|
Default value is '::size'.
|
|
|
|
|
|
@@ -274,7 +317,7 @@ modparam("htable", "key_value", "kvalue")
|
|
|
modparam("htable", "array_size_suffix", "-count")
|
|
|
...
|
|
|
|
|
|
-1.3.8. fetch_rows (integer)
|
|
|
+3.8. fetch_rows (integer)
|
|
|
|
|
|
How many rows to fetch at once from database.
|
|
|
|
|
|
@@ -285,7 +328,7 @@ modparam("htable", "array_size_suffix", "-count")
|
|
|
modparam("htable", "fetch_rows", 1000)
|
|
|
...
|
|
|
|
|
|
-1.3.9. timer_interval (integer)
|
|
|
+3.9. timer_interval (integer)
|
|
|
|
|
|
Interval in seconds to check for expired htable values.
|
|
|
|
|
|
@@ -296,10 +339,10 @@ modparam("htable", "fetch_rows", 1000)
|
|
|
modparam("htable", "timer_interval", 10)
|
|
|
...
|
|
|
|
|
|
-1.3.10. timer_mode (integer)
|
|
|
+3.10. 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.
|
|
|
+ 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.
|
|
|
|
|
|
@@ -308,12 +351,16 @@ modparam("htable", "timer_interval", 10)
|
|
|
modparam("htable", "timer_mode", 1)
|
|
|
...
|
|
|
|
|
|
-1.4. Exported Functions
|
|
|
+4. Exported Functions
|
|
|
+
|
|
|
+ 4.1. sht_print()
|
|
|
+ 4.2. sht_rm_name_re(htable=>regexp)
|
|
|
+ 4.3. sht_rm_value_re(htable=>regexp)
|
|
|
|
|
|
-1.4.1. sht_print()
|
|
|
+4.1. sht_print()
|
|
|
|
|
|
- Dump content of hash table to L_ERR log level. Intended for
|
|
|
- debug purposes.
|
|
|
+ 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.
|
|
|
@@ -323,10 +370,10 @@ modparam("htable", "timer_mode", 1)
|
|
|
sht_print();
|
|
|
...
|
|
|
|
|
|
-1.4.2. sht_rm_name_re(htable=>regexp)
|
|
|
+4.2. sht_rm_name_re(htable=>regexp)
|
|
|
|
|
|
- Delete all entries in the htable that match the name against
|
|
|
- regular expression.
|
|
|
+ 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.
|
|
|
@@ -336,10 +383,10 @@ sht_print();
|
|
|
sht_rm_name_re("ha=>.*");
|
|
|
...
|
|
|
|
|
|
-1.4.3. sht_rm_value_re(htable=>regexp)
|
|
|
+4.3. sht_rm_value_re(htable=>regexp)
|
|
|
|
|
|
- Delete all entries in the htable that match the value against
|
|
|
- regular expression.
|
|
|
+ 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.
|
|
|
@@ -349,7 +396,7 @@ sht_rm_name_re("ha=>.*");
|
|
|
sht_rm_value_re("ha=>.*");
|
|
|
...
|
|
|
|
|
|
-1.5. Exported pseudo-variables
|
|
|
+5. Exported pseudo-variables
|
|
|
|
|
|
* $sht(htable=>key)
|
|
|
* $shtex(htable=>key)
|
|
|
@@ -357,18 +404,33 @@ sht_rm_value_re("ha=>.*");
|
|
|
Exported pseudo-variables are documented at
|
|
|
http://www.kamailio.org/dokuwiki/.
|
|
|
|
|
|
-1.6. Exported MI Functions
|
|
|
+6. Exported MI Functions
|
|
|
|
|
|
-1.6.1. sht_reload
|
|
|
+ 6.1. sht_reload
|
|
|
+ 6.2. sht_dump
|
|
|
+
|
|
|
+6.1. sht_reload
|
|
|
|
|
|
Reload a hash table from database.
|
|
|
|
|
|
Name: sht_reload
|
|
|
|
|
|
- Parameters: _hash_table_name_ - the name of hash table to
|
|
|
- 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:
|
|
|
- :ds_list:_reply_fifo_file_
|
|
|
- _hah_table_name_
|
|
|
+ :sht_dump:_reply_fifo_file_
|
|
|
+ _hash_table_name_
|
|
|
_empty_line_
|
Elena-Ramona Modroiu