git.sip-router.org Git - sip-router/blob - src/modules/mtree/README

   1 mtree Module
   2
   3 Daniel-Constantin Mierla
   4
   5    asipto.com
   6
   7 Edited by
   8
   9 Daniel-Constantin Mierla
  10
  11    <miconda@gmail.com>
  12
  13 Juha Heinanen
  14
  15    tutpro.com
  16
  17 Edited by
  18
  19 Juha Heinanen
  20
  21    <jh@tutpro.com>
  22
  23    Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
  24
  25    Copyright © 2011 Juha Heinanen
  26      __________________________________________________________________
  27
  28    Table of Contents
  29
  30    1. Admin Guide
  31
  32         1. Overview
  33         2. Dependencies
  34
  35               2.1. Kamailio Modules
  36               2.2. External Libraries or Applications
  37
  38         3. Parameters
  39
  40               3.1. db_url (string)
  41               3.2. db_table (string)
  42               3.3. mtree (string)
  43               3.4. tname_column (string)
  44               3.5. tprefix_column (string)
  45               3.6. tvalue_column (string)
  46               3.7. fetch_rows (integer)
  47               3.8. char_list (string)
  48               3.9. pv_value (string)
  49               3.10. pv_values (string)
  50               3.11. mt_tree_type (integer)
  51               3.12. mt_ignore_duplicates (integer)
  52               3.13. mt_allow_duplicates (integer)
  53
  54         4. Functions
  55
  56               4.1. mt_match(mtree, pv, mode)
  57
  58         5. RPC Commands
  59
  60               5.1. mtree.list
  61               5.2. mtree.summary
  62               5.3. mtree.reload
  63               5.4. mtree.match
  64
  65    List of Examples
  66
  67    1.1. Set db_url parameter
  68    1.2. Set db_table parameter
  69    1.3. Set mtree parameter
  70    1.4. Set tname_column parameter
  71    1.5. Set tprefix_column parameter
  72    1.6. Set tvalue_column parameter
  73    1.7. Set fetch_rows parameter
  74    1.8. Set char_list parameter
  75    1.9. Set pv_value parameter
  76    1.10. Set pv_values parameter
  77    1.11. Set mt_tree_type parameter
  78    1.12. Set mt_ignore_duplicates parameter
  79    1.13. Set mt_allow_duplicates parameter
  80    1.14. mt_match usage
  81    1.15. mtree.list rpc usage
  82
  83 Chapter 1. Admin Guide
  84
  85    Table of Contents
  86
  87    1. Overview
  88    2. Dependencies
  89
  90         2.1. Kamailio Modules
  91         2.2. External Libraries or Applications
  92
  93    3. Parameters
  94
  95         3.1. db_url (string)
  96         3.2. db_table (string)
  97         3.3. mtree (string)
  98         3.4. tname_column (string)
  99         3.5. tprefix_column (string)
 100         3.6. tvalue_column (string)
 101         3.7. fetch_rows (integer)
 102         3.8. char_list (string)
 103         3.9. pv_value (string)
 104         3.10. pv_values (string)
 105         3.11. mt_tree_type (integer)
 106         3.12. mt_ignore_duplicates (integer)
 107         3.13. mt_allow_duplicates (integer)
 108
 109    4. Functions
 110
 111         4.1. mt_match(mtree, pv, mode)
 112
 113    5. RPC Commands
 114
 115         5.1. mtree.list
 116         5.2. mtree.summary
 117         5.3. mtree.reload
 118         5.4. mtree.match
 119
 120 1. Overview
 121
 122    This module loads (prefix, value) records from database and indexes
 123    them in a named memory tree. Name of the tree is specified for each
 124    record or as module parameter.
 125
 126    It exports to configuration file functions to match against in-memory
 127    trees and return the values (raw or precompiled) associated with
 128    matched prefixes.
 129
 130    The maximum size of the prefix is limited internally to 63, database
 131    table definition may enforce lower maximum size.
 132
 133 2. Dependencies
 134
 135    2.1. Kamailio Modules
 136    2.2. External Libraries or Applications
 137
 138 2.1. Kamailio Modules
 139
 140    The following modules must be loaded before this module:
 141      * A Kamailio database module (e.g., mysql).
 142
 143 2.2. External Libraries or Applications
 144
 145    The following libraries or applications must be installed before
 146    running Kamailio with this module loaded:
 147      * None.
 148
 149 3. Parameters
 150
 151    3.1. db_url (string)
 152    3.2. db_table (string)
 153    3.3. mtree (string)
 154    3.4. tname_column (string)
 155    3.5. tprefix_column (string)
 156    3.6. tvalue_column (string)
 157    3.7. fetch_rows (integer)
 158    3.8. char_list (string)
 159    3.9. pv_value (string)
 160    3.10. pv_values (string)
 161    3.11. mt_tree_type (integer)
 162    3.12. mt_ignore_duplicates (integer)
 163    3.13. mt_allow_duplicates (integer)
 164
 165 3.1. db_url (string)
 166
 167    URL of the database server to be used.
 168
 169    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
 170
 171    Example 1.1. Set db_url parameter
 172 ...
 173 modparam("mtree", "db_url", "dbdriver://username:password@dbhost/dbname")
 174 ...
 175
 176 3.2. db_table (string)
 177
 178    Name of database table where data for many trees is stored. It is
 179    ignored if a 'mtree' parameter is defined. The SQL scripts creates a
 180    table named 'mtrees' that can be used for this parameter.
 181
 182    Default value is “” (no table name).
 183
 184    Example 1.2. Set db_table parameter
 185 ...
 186 modparam("mtree", "db_table", "mtrees")
 187 ...
 188
 189 3.3. mtree (string)
 190
 191    Definition of memory tree with using a prameters format string. The
 192    parameter names can be:
 193      * name - the name of the tree to be used for referencing inside
 194        configuration file.
 195      * dbtable - the name of the database table from where to load the
 196        records stored in the tree.
 197      * cols - the column names of the database table. They must be
 198        enclosed in quotes in order to form a valid SIP parameter value and
 199        be separated by comma. The first column corresponds to tprefix.
 200        When specified, there must be at least two columns. If this
 201        attribute is not specified, then the global module parameters for
 202        tprefix and tvalue are used. If more than one value columns are
 203        specified, the tree will pack the column values in a comma
 204        separated string, which will be associated with the prefix (string
 205        transformation {s.select,...) can be used in configuration file to
 206        extract a specific column value).
 207      * type - the type of tree elements (0 = string, 2 = integer). It is
 208        valid only when the (tprefix, tvalue) pairs are loaded (not for
 209        muti-column values).
 210      * multi - tells if dbtable can contain more than one tree (0 = one
 211        tree, 1 = more than one tree identified by tname column). It is
 212        valid only when the (tprefix, tvalue) pairs are loaded (not for
 213        muti-column values).
 214
 215    This parameter can be set many times to add more trees in memory.
 216
 217    Default value is “none”.
 218
 219    Example 1.3. Set mtree parameter
 220 ...
 221 modparam("mtree", "mtree", "name=mytree1;dbtable=routes1;type=0")
 222 modparam("mtree", "mtree", "name=mytree2;dbtable=routes2;type=0;multi=1")
 223 modparam("mtree", "mtree",
 224     "name=mytree1;dbtable=routes1;cols='key1,val1,val2,val3'")
 225 ...
 226
 227 3.4. tname_column (string)
 228
 229    Name of 'tname' column.
 230
 231    Default value is “tname”.
 232
 233    Example 1.4. Set tname_column parameter
 234 ...
 235 modparam("mtree", "tname_column", "name")
 236 ...
 237
 238 3.5. tprefix_column (string)
 239
 240    Name of 'tprefix' column.
 241
 242    Default value is “tprefix”.
 243
 244    Example 1.5. Set tprefix_column parameter
 245 ...
 246 modparam("mtree", "tprefix_column", "prefix")
 247 ...
 248
 249 3.6. tvalue_column (string)
 250
 251    Name of 'tvalue' column.
 252
 253    Default value is “tvalue”.
 254
 255    Example 1.6. Set tvalue_column parameter
 256 ...
 257 modparam("mtree", "tvalue_column", "ipaddr")
 258 ...
 259
 260 3.7. fetch_rows (integer)
 261
 262    Number of rows to be loaded in one step from database.
 263
 264    Default value is 1000.
 265
 266    Example 1.7. Set fetch_rows parameter
 267 ...
 268 modparam("mtree", "fetch_rows", 4000)
 269 ...
 270
 271 3.8. char_list (string)
 272
 273    The list with characters allowed in prefix.
 274
 275    Default value is “0123456789”.
 276
 277    Example 1.8. Set char_list parameter
 278 ...
 279 modparam("mtree", "char_list", "0123456789*+")
 280 ...
 281
 282 3.9. pv_value (string)
 283
 284    The PV spec where to store the matched value. It can be any writable
 285    PV.
 286
 287    Default value is “$avp(s:tvalue)”.
 288
 289    Example 1.9. Set pv_value parameter
 290 ...
 291 modparam("mtree", "pv_value", "$var(mtval)")
 292 ...
 293
 294 3.10. pv_values (string)
 295
 296    The AVP where to store the matched values when mtree is of type 0 or 2
 297    and mode of mt_match() call has value 2.
 298
 299    Default value is “$avp(s:tvalues)”.
 300
 301    Example 1.10. Set pv_values parameter
 302 ...
 303 modparam("mtree", "pv_values", "$avp(mtvals)")
 304 ...
 305
 306 3.11. mt_tree_type (integer)
 307
 308    Default payload type for trees data stored in 'db_table'. Documented
 309    values are 0 for string payloads and 2 for integer payloads.
 310
 311    Default value is 0.
 312
 313    Example 1.11. Set mt_tree_type parameter
 314 ...
 315 modparam("mtree", "mt_tree_type", 2)
 316 ...
 317
 318 3.12. mt_ignore_duplicates (integer)
 319
 320    Ignore duplicated prefixes when loading data.
 321
 322    Default value is 0.
 323
 324    Example 1.12. Set mt_ignore_duplicates parameter
 325 ...
 326 modparam("mtree", "mt_ignore_duplicates", 1)
 327 ...
 328
 329 3.13. mt_allow_duplicates (integer)
 330
 331    Allow duplicate prefixes when loading data.
 332
 333    Default value is 0.
 334
 335    Example 1.13. Set mt_allow_duplicates parameter
 336 ...
 337 modparam("mtree", "mt_allow_duplicates", 1)
 338 ...
 339
 340 4. Functions
 341
 342    4.1. mt_match(mtree, pv, mode)
 343
 344 4.1.  mt_match(mtree, pv, mode)
 345
 346    Match 'pv' value against 'mtree'. If 'mtree' type is 0 or 2 and value
 347    of 'mode' is NOT 2, sets a value of the longest matching prefix to
 348    pseudo variable specified by pv_value parameter. If 'mtree' type is 0
 349    or 2 and value of 'mode' is 2, sets values of all matching prefixes to
 350    avp specified by pv_values parameter so that a value of longest
 351    matching prefix is in avp index 0. Parameter 'mode' can be an integer
 352    constant or a pseudo variable with integer value.
 353
 354    Returns 1 if match succeeded and -1 otherwise.
 355
 356    Example 1.14. mt_match usage
 357 ...
 358 mt_match("mytree", "$rU", "0");
 359 ...
 360
 361 5. RPC Commands
 362
 363    5.1. mtree.list
 364    5.2. mtree.summary
 365    5.3. mtree.reload
 366    5.4. mtree.match
 367
 368 5.1.  mtree.list
 369
 370    List content of one or all trees.
 371
 372    Name: mtree.list
 373
 374    Parameters:
 375      * _mtree_ : name of tree to list (optional).
 376
 377    Example 1.15. mtree.list rpc usage
 378 ...
 379 kamcmd mtree.list
 380 kamcmd mtree.list mytree
 381 ...
 382
 383 5.2.  mtree.summary
 384
 385    List usage summary for all trees or for the tree whose name is given as
 386    parameter.
 387
 388    Parameters:
 389      * _mtree_ - (optional) the name of the tree.
 390
 391 5.3.  mtree.reload
 392
 393    Reload mtree from database to memory.
 394
 395    Parameters:
 396      * _mtree_
 397        - name of mtree or empty string meaning all mtrees
 398
 399 5.4.  mtree.match
 400
 401    Match prefix value against mtree
 402
 403    Parameters:
 404      * _mtree_
 405        - name of mtree
 406      * _prefix_
 407        - match prefix
 408      * _mode_
 409        - matching mode