htable: documented sht_dump MI command

modules_k/htable/README

@@ -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_

modules_k/htable/doc/htable_admin.xml

@@ -526,8 +526,29 @@ sht_rm_value_re("ha=>.*");
 		MI FIFO Command Format:
 		</para>
         <programlisting  format="linespecific">
-		:ds_list:_reply_fifo_file_
-		_hah_table_name_
+		:sht_reload:_reply_fifo_file_
+		_hash_table_name_
+		_empty_line_
+		</programlisting>
+    </section>
+	<section>
+		<title>
+		<function moreinfo="none">sht_dump</function>
+		</title>
+		<para>
+		Dump content of a hash table via MI.
+		</para>
+		<para>
+		Name: <emphasis>sht_dump</emphasis>
+		</para>
+		<para>Parameters: <emphasis>_hash_table_name_</emphasis> - the name
+		of hash table to dump.</para>
+ 		<para>
+		MI FIFO Command Format:
+		</para>
+        <programlisting  format="linespecific">
+		:sht_dump:_reply_fifo_file_
+		_hash_table_name_
 		_empty_line_
 		</programlisting>
     </section>