18f33865e9924b71cbd3b331abfd8aa75d548892
[sip-router] / 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