GitList
Browse code

cr: new function 'cr_nofallback_route'

- add new function 'cr_nofallback_route' which behaves exactly like
the existing 'cr_prime_route' function but uses the standard CRC32
hash instead of this prime function to provide an path away from
this function
- mark 'cr_prime_route' function as obselete in docs
- patch from Carsten Gross, carsten dot gross at 1und1 dot de

Henning Westerholt authored on 07/09/2009 08:34:58
Showing 5 changed files
modules/carrierroute/README
History View file @ 8dc53feb5a
... ... 
@@ -14,97 +14,98 @@ Henning Westerholt
14 14
15 15 
    Copyright � 2007 1&1 Internet AG
16 16 
    Revision History
17 
-   Revision $Revision: 4872 $ $Date: 2008-09-09 17:39:38 +0200
18 
-                              (Di, 09 Sep 2008) $
19 
-     __________________________________________________________
17 
+   Revision $Revision$ $Date$
18 
+     __________________________________________________________________
20 19
21 20 
    Table of Contents
22 21
23 22 
    1. Admin Guide
24 23
25 
-        1.1. Overview
26 
-        1.2. Dependencies
24 
+        1. Overview
25 
+        2. Dependencies
27 26
28 
-              1.2.1. Kamailio Modules
29 
-              1.2.2. External Libraries or Applications
27 
+              2.1. Kamailio Modules
28 
+              2.2. External Libraries or Applications
30 29
31 
-        1.3. Exported Parameters
30 
+        3. Exported Parameters
32 31
33 
-              1.3.1. subscriber_table (string)
34 
-              1.3.2. subscriber_user_col (string)
35 
-              1.3.3. subscriber_domain_col (string)
36 
-              1.3.4. subscriber_carrier_col (string)
37 
-              1.3.5. config_source (string)
38 
-              1.3.6. config_file (string)
39 
-              1.3.7. default_tree (string)
40 
-              1.3.8. use_domain (int)
41 
-              1.3.9. fallback_default (int)
42 
-              1.3.10. fetch_rows (integer)
43 
-              1.3.11. match_mode (integer)
32 
+              3.1. subscriber_table (string)
33 
+              3.2. subscriber_user_col (string)
34 
+              3.3. subscriber_domain_col (string)
35 
+              3.4. subscriber_carrier_col (string)
36 
+              3.5. config_source (string)
37 
+              3.6. config_file (string)
38 
+              3.7. default_tree (string)
39 
+              3.8. use_domain (int)
40 
+              3.9. fallback_default (int)
41 
+              3.10. fetch_rows (integer)
42 
+              3.11. match_mode (integer)
44 43
45 
-        1.4. Exported Functions
44 
+        4. Exported Functions
46 45
47 
-              1.4.1. cr_user_carrier(user, domain, dstavp)
48 
-              1.4.2. cr_route(carrier, domain, prefix_matching,
46 
+              4.1. cr_user_carrier(user, domain, dstavp)
47 
+              4.2. cr_route(carrier, domain, prefix_matching,
49 48 
                       rewrite_user, hash_source, descavp)
50 49
51 
-              1.4.3. cr_prime_route(carrier, domain,
52 
-                      prefix_matching, rewrite_user, hash_source,
53 
-                      descavp)
50 
+              4.3. cr_prime_route(carrier, domain, prefix_matching,
51 
+                      rewrite_user, hash_source, descavp)
52 
+
53 
+              4.4. cr_nofallback_route(carrier, domain, prefix_matching,
54 
+                      rewrite_user, hash_source, descavp)
54 55
55 
-              1.4.4. cr_next_domain(carrier, domain,
56 
-                      prefix_matching, host, reply_code, dstavp)
56 
+              4.5. cr_next_domain(carrier, domain, prefix_matching, host,
57 
+                      reply_code, dstavp)
57 58
58 
-        1.5. MI Commands
59 
+        5. MI Commands
59 60
60 
-              1.5.1. cr_reload_routes
61 
-              1.5.2. cr_dump_routes
62 
-              1.5.3. cr_replace_host
63 
-              1.5.4. cr_deactivate_host
64 
-              1.5.5. cr_activate_host
65 
-              1.5.6. cr_add_host
66 
-              1.5.7. cr_delete_host
61 
+              5.1. cr_reload_routes
62 
+              5.2. cr_dump_routes
63 
+              5.3. cr_replace_host
64 
+              5.4. cr_deactivate_host
65 
+              5.5. cr_activate_host
66 
+              5.6. cr_add_host
67 
+              5.7. cr_delete_host
67 68
68 
-        1.6. Configuration examples
69 
-        1.7. Installation and Running
69 
+        6. Configuration examples
70 
+        7. Installation and Running
70 71
71 
-              1.7.1. Database setup
72 
-              1.7.2. Database examples
73 
-              1.7.3. User specific routing
72 
+              7.1. Database setup
73 
+              7.2. Database examples
74 
+              7.3. User specific routing
74 75
75 76 
    2. Module parameter for database access.
76 77
77 
-        2.1. db_url (String)
78 
-        2.2. carrierroute_table (String)
79 
-        2.3. carrierroute_id_col (string)
80 
-        2.4. carrierroute_carrier_col (string)
81 
-        2.5. carrierroute_domain_col (string)
82 
-        2.6. carrierroute_scan_prefix_col (string)
83 
-        2.7. carrierroute_flags_col (string)
84 
-        2.8. carrierroute_mask_col (string)
85 
-        2.9. carrierroute_prob_col (string)
86 
-        2.10. carrierroute_strip_col (string)
87 
-        2.11. carrierroute_rewrite_host_col (string)
88 
-        2.12. carrierroute_rewrite_prefix_col (string)
89 
-        2.13. carrierroute_rewrite_suffix_col (string)
90 
-        2.14. carrierroute_description_col (string)
91 
-        2.15. carrierfailureroute_table (String)
92 
-        2.16. carrierfailureroute_id_col (string)
93 
-        2.17. carrierfailureroute_carrier_col (string)
94 
-        2.18. carrierfailureroute_domain_col (string)
95 
-        2.19. carrierfailureroute_scan_prefix_col (string)
96 
-        2.20. carrierfailureroute_host_name_col (string)
97 
-        2.21. carrierfailureroute_reply_code_col (string)
98 
-        2.22. carrierfailureroute_flags_col (string)
99 
-        2.23. carrierfailureroute_mask_col (string)
100 
-        2.24. carrierfailureroute_next_domain_col (string)
101 
-        2.25. carrierfailureroute_description_col (string)
102 
-        2.26. carrier_name_table (String)
103 
-        2.27. carrier_name_id_col (string)
104 
-        2.28. carrier_name_carrier_col (string)
105 
-        2.29. domain_name_table (String)
106 
-        2.30. domain_name_id_col (string)
107 
-        2.31. domain_name_domain_col (string)
78 
+        1. db_url (String)
79 
+        2. carrierroute_table (String)
80 
+        3. carrierroute_id_col (string)
81 
+        4. carrierroute_carrier_col (string)
82 
+        5. carrierroute_domain_col (string)
83 
+        6. carrierroute_scan_prefix_col (string)
84 
+        7. carrierroute_flags_col (string)
85 
+        8. carrierroute_mask_col (string)
86 
+        9. carrierroute_prob_col (string)
87 
+        10. carrierroute_strip_col (string)
88 
+        11. carrierroute_rewrite_host_col (string)
89 
+        12. carrierroute_rewrite_prefix_col (string)
90 
+        13. carrierroute_rewrite_suffix_col (string)
91 
+        14. carrierroute_description_col (string)
92 
+        15. carrierfailureroute_table (String)
93 
+        16. carrierfailureroute_id_col (string)
94 
+        17. carrierfailureroute_carrier_col (string)
95 
+        18. carrierfailureroute_domain_col (string)
96 
+        19. carrierfailureroute_scan_prefix_col (string)
97 
+        20. carrierfailureroute_host_name_col (string)
98 
+        21. carrierfailureroute_reply_code_col (string)
99 
+        22. carrierfailureroute_flags_col (string)
100 
+        23. carrierfailureroute_mask_col (string)
101 
+        24. carrierfailureroute_next_domain_col (string)
102 
+        25. carrierfailureroute_description_col (string)
103 
+        26. carrier_name_table (String)
104 
+        27. carrier_name_id_col (string)
105 
+        28. carrier_name_carrier_col (string)
106 
+        29. domain_name_table (String)
107 
+        30. domain_name_id_col (string)
108 
+        31. domain_name_domain_col (string)
108 109
109 110 
    List of Examples
110 111
... ... 
@@ -128,12 +129,8 @@ Henning Westerholt
128 129 
    1.18. Configuration example - Routing to user tree
129 130 
    1.19. Configuration example - module configuration
130 131 
    1.20. Example database content - carrierroute table
131 
-   1.21. Example database content - simple carrierfailureroute
132 
-          table
133 
-
134 
-   1.22. Example database content - more complex
135 
-          carrierfailureroute table
136 
-
132 
+   1.21. Example database content - simple carrierfailureroute table
133 
+   1.22. Example database content - more complex carrierfailureroute table
137 134 
    1.23. Example database content - carrier_name table
138 135 
    1.24. Example database content - domain_name table
139 136 
    1.25. Necessary extensions for the user table
... ... 
@@ -171,96 +168,158 @@ Henning Westerholt
171 168
172 169 
 Chapter 1. Admin Guide
173 170
174 
-1.1. Overview
171 
+   Table of Contents
172 
+
173 
+   1. Overview
174 
+   2. Dependencies
175 
+
176 
+        2.1. Kamailio Modules
177 
+        2.2. External Libraries or Applications
178 
+
179 
+   3. Exported Parameters
180 
+
181 
+        3.1. subscriber_table (string)
182 
+        3.2. subscriber_user_col (string)
183 
+        3.3. subscriber_domain_col (string)
184 
+        3.4. subscriber_carrier_col (string)
185 
+        3.5. config_source (string)
186 
+        3.6. config_file (string)
187 
+        3.7. default_tree (string)
188 
+        3.8. use_domain (int)
189 
+        3.9. fallback_default (int)
190 
+        3.10. fetch_rows (integer)
191 
+        3.11. match_mode (integer)
192 
+
193 
+   4. Exported Functions
194 
+
195 
+        4.1. cr_user_carrier(user, domain, dstavp)
196 
+        4.2. cr_route(carrier, domain, prefix_matching, rewrite_user,
197 
+                hash_source, descavp)
198 
+
199 
+        4.3. cr_prime_route(carrier, domain, prefix_matching,
200 
+                rewrite_user, hash_source, descavp)
201 
+
202 
+        4.4. cr_nofallback_route(carrier, domain, prefix_matching,
203 
+                rewrite_user, hash_source, descavp)
204 
+
205 
+        4.5. cr_next_domain(carrier, domain, prefix_matching, host,
206 
+                reply_code, dstavp)
207 
+
208 
+   5. MI Commands
209 
+
210 
+        5.1. cr_reload_routes
211 
+        5.2. cr_dump_routes
212 
+        5.3. cr_replace_host
213 
+        5.4. cr_deactivate_host
214 
+        5.5. cr_activate_host
215 
+        5.6. cr_add_host
216 
+        5.7. cr_delete_host
217 
+
218 
+   6. Configuration examples
219 
+   7. Installation and Running
220 
+
221 
+        7.1. Database setup
222 
+        7.2. Database examples
223 
+        7.3. User specific routing
224 
+
225 
+1. Overview
175 226
176 227 
    A module which provides routing, balancing and blacklisting
177 228 
    capabilities.
178 229
179 
-   The module provides routing, balancing and blacklisting
180 
-   capabilities. It reads routing entries from a database source
181 
-   or from a config file at Kamailio startup. It can uses one
182 
-   routing tree (for one carrier), or if needed for every user a
183 
-   different routing tree (unique for each carrier) for number
184 
-   prefix based routing. It supports several route tree domains,
185 
-   e.g. for failback routes or different routing rules for VoIP
186 
-   and PSTN targets.
230 
+   The module provides routing, balancing and blacklisting capabilities.
231 
+   It reads routing entries from a database source or from a config file
232 
+   at Kamailio startup. It can uses one routing tree (for one carrier), or
233 
+   if needed for every user a different routing tree (unique for each
234 
+   carrier) for number prefix based routing. It supports several route
235 
+   tree domains, e.g. for failback routes or different routing rules for
236 
+   VoIP and PSTN targets.
187 237
188 238 
    Based on the tree, the module decides which number prefixes are
189 
-   forwarded to which gateway. It can also distribute the traffic
190 
-   by ratio parameters. Furthermore, the requests can be
191 
-   distributed by a hash funcion to predictable destinations. The
192 
-   hash source is configurable, two different hash functions are
193 
-   available.
194 
-
195 
-   This modules scales up to more than a few million users, and is
196 
-   able to handle more than several hundred thousand routing table
197 
-   entries. We recieved reports of some setups that used more than
198 
-   a million routing table entries. It also supports a large
199 
-   number of carriers and domains which can be efficiently looked
200 
-   up in most of the cases (see below for more informations). In
201 
-   load balancing scenarios the usage of the config file mode is
202 
-   recommended, to avoid the additional complexity that the
239 
+   forwarded to which gateway. It can also distribute the traffic by ratio
240 
+   parameters. Furthermore, the requests can be distributed by a hash
241 
+   funcion to predictable destinations. The hash source is configurable,
242 
+   two different hash functions are available.
243 
+
244 
+   This modules scales up to more than a few million users, and is able to
245 
+   handle more than several hundred thousand routing table entries. We
246 
+   recieved reports of some setups that used more than a million routing
247 
+   table entries. It also supports a large number of carriers and domains
248 
+   which can be efficiently looked up in most of the cases (see below for
249 
+   more informations). In load balancing scenarios the usage of the config
250 
+   file mode is recommended, to avoid the additional complexity that the
203 251 
    database driven routing creates.
204 252
205 
-   Routing tables can be reloaded and edited (in config file mode)
206 
-   with the MI interface, the config file is updated according the
207 
-   changes. This is not implemented for the db interface, because
208 
-   its easier to do the changes directly on the db. But the reload
209 
-   and dump functions works of course here too.
210 
-
211 
-   Some module functionality is not fully available in the config
212 
-   file mode, as it is not possible to specify all information
213 
-   that can be stored in the database tables in the config file.
214 
-   Further information about these limitations is given in later
215 
-   sections. For user based routing or LCR you should use the
216 
-   database mode.
217 
-
218 
-   In database mode, this module supports names and IDs for the
219 
-   carriers and domains. When using IDs for the routing functions,
220 
-   efficient binary search is used to find the needed data
221 
-   structures. If you are using constant strings as parameter,
222 
-   these will be converted to IDs during the fixup procedure.
223 
-   However, if you are using AVPs as parameter and they contain
224 
-   strings, this cannot be converted to IDs during the fixup
225 
-   procedure. In that case linear search is performed to find the
226 
-   needed data structures. So from a performance point of view it
227 
-   is better to pass only IDs in AVPs to the routing functions.
228 
-
229 
-   Basically this module could be used as an replacement for the
230 
-   lcr and the dispatcher module, if you have certain flexibility,
231 
-   integration and/or performance requirements that can't be
232 
-   satisfied with these modules. But for smaller installations it
233 
-   probably make more sense to use the lcr and dispatcher module.
234 
-
235 
-   If you want to use this module in failure routes, then you need
236 
-   to call "append_branch()" after rewriting the request URI in
237 
-   order to relay the message to the new target. Its also
238 
-   supportes the usage of database derived failure routing
239 
-   descisions with the carrierfailureroute table.
240 
-
241 
-1.2. Dependencies
242 
-
243 
-1.2.1. Kamailio Modules
253 
+   Routing tables can be reloaded and edited (in config file mode) with
254 
+   the MI interface, the config file is updated according the changes.
255 
+   This is not implemented for the db interface, because its easier to do
256 
+   the changes directly on the db. But the reload and dump functions works
257 
+   of course here too.
258 
+
259 
+   Some module functionality is not fully available in the config file
260 
+   mode, as it is not possible to specify all information that can be
261 
+   stored in the database tables in the config file. Further information
262 
+   about these limitations is given in later sections. For user based
263 
+   routing or LCR you should use the database mode.
264 
+
265 
+   In database mode, this module supports names and IDs for the carriers
266 
+   and domains. When using IDs for the routing functions, efficient binary
267 
+   search is used to find the needed data structures. If you are using
268 
+   constant strings as parameter, these will be converted to IDs during
269 
+   the fixup procedure. However, if you are using AVPs as parameter and
270 
+   they contain strings, this cannot be converted to IDs during the fixup
271 
+   procedure. In that case linear search is performed to find the needed
272 
+   data structures. So from a performance point of view it is better to
273 
+   pass only IDs in AVPs to the routing functions.
274 
+
275 
+   Basically this module could be used as an replacement for the lcr and
276 
+   the dispatcher module, if you have certain flexibility, integration
277 
+   and/or performance requirements that can't be satisfied with these
278 
+   modules. But for smaller installations it probably make more sense to
279 
+   use the lcr and dispatcher module.
280 
+
281 
+   If you want to use this module in failure routes, then you need to call
282 
+   "append_branch()" after rewriting the request URI in order to relay the
283 
+   message to the new target. Its also supportes the usage of database
284 
+   derived failure routing descisions with the carrierfailureroute table.
285 
+
286 
+2. Dependencies
287 
+
288 
+   2.1. Kamailio Modules
289 
+   2.2. External Libraries or Applications
290 
+
291 
+2.1. Kamailio Modules
244 292
245 293 
    The following module must be loaded before this module:
246 
-     * a database module, when a database is used as configuration
247 
-       data source. Only SQL based databases are supported, as
248 
-       this module needs the capability to issue raw queries. Its
249 
-       not possible to use the dbtext or db_berkeley module at the
250 
-       moment.
294 
+     * a database module, when a database is used as configuration data
295 
+       source. Only SQL based databases are supported, as this module
296 
+       needs the capability to issue raw queries. Its not possible to use
297 
+       the dbtext or db_berkeley module at the moment.
251 298 
      * The tm module, when you want to use the $T_reply_code
252 299 
        pseudo-variable in the "cr_next_domain" function.
253 300
254 
-1.2.2. External Libraries or Applications
301 
+2.2. External Libraries or Applications
255 302
256 
-   The following libraries or applications must be installed
257 
-   before running Kamailio with this module loaded:
303 
+   The following libraries or applications must be installed before
304 
+   running Kamailio with this module loaded:
258 305 
      * libconfuse, a configuration file parser library. (
259 306 
        http://www.nongnu.org/confuse/ )
260 307
261 
-1.3. Exported Parameters
308 
+3. Exported Parameters
309 
+
310 
+   3.1. subscriber_table (string)
311 
+   3.2. subscriber_user_col (string)
312 
+   3.3. subscriber_domain_col (string)
313 
+   3.4. subscriber_carrier_col (string)
314 
+   3.5. config_source (string)
315 
+   3.6. config_file (string)
316 
+   3.7. default_tree (string)
317 
+   3.8. use_domain (int)
318 
+   3.9. fallback_default (int)
319 
+   3.10. fetch_rows (integer)
320 
+   3.11. match_mode (integer)
262 321
263 
-1.3.1. subscriber_table (string)
322 
+3.1. subscriber_table (string)
264 323
265 324 
    The name of the table containing the subscribers
266 325
... ... 
@@ -271,7 +330,7 @@ Chapter 1. Admin Guide
271 330 
 modparam("carrierroute", "subscriber_table", "subscriber")
272 331 
 ...
273 332
274 
-1.3.2. subscriber_user_col (string)
333 
+3.2. subscriber_user_col (string)
275 334
276 335 
    The name of the column in the subscriber table containing the
277 336 
    usernames.
... ... 
@@ -283,10 +342,10 @@ modparam("carrierroute", "subscriber_table", "subscriber")
283 342 
 modparam("carrierroute", "subscriber_user_col", "username")
284 343 
 ...
285 344
286 
-1.3.3. subscriber_domain_col (string)
345 
+3.3. subscriber_domain_col (string)
287 346
288 
-   The name of the column in the subscriber table containing the
289 
-   domain of the subscriber.
347 
+   The name of the column in the subscriber table containing the domain of
348 
+   the subscriber.
290 349
291 350 
    Default value is "domain".
292 351
... ... 
@@ -295,23 +354,22 @@ modparam("carrierroute", "subscriber_user_col", "username")
295 354 
 modparam("carrierroute", "subscriber_domain_col", "domain")
296 355 
 ...
297 356
298 
-1.3.4. subscriber_carrier_col (string)
357 
+3.4. subscriber_carrier_col (string)
299 358
300 
-   The name of the column in the subscriber table containing the
301 
-   carrier id of the subscriber.
359 
+   The name of the column in the subscriber table containing the carrier
360 
+   id of the subscriber.
302 361
303 362 
    Default value is "cr_preferred_carrier".
304 363
305 364 
    Example 1.4. Set subscriber_carrier_col parameter
306 365 
 ...
307 
-modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier
308 
-")
366 
+modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier")
309 367 
 ...
310 368
311 
-1.3.5. config_source (string)
369 
+3.5. config_source (string)
312 370
313 
-   Specifies whether the module loads its config data from a file
314 
-   or from a database. Possible values are file or db.
371 
+   Specifies whether the module loads its config data from a file or from
372 
+   a database. Possible values are file or db.
315 373
316 374 
    Default value is "file".
317 375
... ... 
@@ -320,7 +378,7 @@ modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier
320 378 
 modparam("carrierroute", "config_source", "file")
321 379 
 ...
322 380
323 
-1.3.6. config_file (string)
381 
+3.6. config_file (string)
324 382
325 383 
    Specifies the path to the config file.
326 384
... ... 
@@ -328,11 +386,10 @@ modparam("carrierroute", "config_source", "file")
328 386
329 387 
    Example 1.6. Set config_file parameter
330 388 
 ...
331 
-modparam("carrierroute", "config_file", "/etc/kamailio/carrierroute.conf
332 
-")
389 
+modparam("carrierroute", "config_file", "/etc/kamailio/carrierroute.conf")
333 390 
 ...
334 391
335 
-1.3.7. default_tree (string)
392 
+3.7. default_tree (string)
336 393
337 394 
    The name of the carrier tree used per default (if the current
338 395 
    subscriber has no preferred tree)
... ... 
@@ -344,10 +401,10 @@ modparam("carrierroute", "config_file", "/etc/kamailio/carrierroute.conf
344 401 
 modparam("carrierroute", "default_tree", "default")
345 402 
 ...
346 403
347 
-1.3.8. use_domain (int)
404 
+3.8. use_domain (int)
348 405
349 
-   When using tree lookup per user, this parameter specifies
350 
-   whether to use the domain part for user matching or not.
406 
+   When using tree lookup per user, this parameter specifies whether to
407 
+   use the domain part for user matching or not.
351 408
352 409 
    Default value is "0".
353 410
... ... 
@@ -356,12 +413,12 @@ modparam("carrierroute", "default_tree", "default")
356 413 
 modparam("carrierroute", "use_domain", 0)
357 414 
 ...
358 415
359 
-1.3.9. fallback_default (int)
416 
+3.9. fallback_default (int)
360 417
361 
-   This parameter defines the behaviour when using user-based tree
362 
-   lookup. If the user has a non-existing tree set and
363 
-   fallback_default is set to 1, the default tree is used.
364 
-   Otherwise, cr_user_rewrite_uri returns an error.
418 
+   This parameter defines the behaviour when using user-based tree lookup.
419 
+   If the user has a non-existing tree set and fallback_default is set to
420 
+   1, the default tree is used. Otherwise, cr_user_rewrite_uri returns an
421 
+   error.
365 422
366 423 
    Default value is "1".
367 424
... ... 
@@ -370,13 +427,12 @@ modparam("carrierroute", "use_domain", 0)
370 427 
 modparam("carrierroute", "fallback_default", 1)
371 428 
 ...
372 429
373 
-1.3.10. fetch_rows (integer)
430 
+3.10. fetch_rows (integer)
374 431
375 
-   The number of the rows to be fetched at once from database when
376 
-   loading the routing data. This value can be used to tune the
377 
-   load time at startup. For 1MB of private memory (default) it
378 
-   should be below 3750. The database driver must support the
379 
-   fetch_result() capability.
432 
+   The number of the rows to be fetched at once from database when loading
433 
+   the routing data. This value can be used to tune the load time at
434 
+   startup. For 1MB of private memory (default) it should be below 3750.
435 
+   The database driver must support the fetch_result() capability.
380 436
381 437 
    Default value is "2000".
382 438
... ... 
@@ -385,15 +441,14 @@ modparam("carrierroute", "fallback_default", 1)
385 441 
 modparam("carrierroute", "fetch_rows", 3000)
386 442 
 ...
387 443
388 
-1.3.11. match_mode (integer)
444 
+3.11. match_mode (integer)
389 445
390 
-   The number of individual characters that are used for matching.
391 
-   Valid values are 10 or 128. When you specifiy 10, only digits
392 
-   will be used for matching, this operation mode is equivalent to
393 
-   the old behaviour. When configured with 128, all standard ascii
394 
-   chars are available for matching. Please be aware that memory
395 
-   requirements for storing the routing tree in shared memory will
396 
-   also increase by a factor of 12.8.
446 
+   The number of individual characters that are used for matching. Valid
447 
+   values are 10 or 128. When you specifiy 10, only digits will be used
448 
+   for matching, this operation mode is equivalent to the old behaviour.
449 
+   When configured with 128, all standard ascii chars are available for
450 
+   matching. Please be aware that memory requirements for storing the
451 
+   routing tree in shared memory will also increase by a factor of 12.8.
397 452
398 453 
    Default value is "10".
399 454
... ... 
@@ -402,11 +457,23 @@ modparam("carrierroute", "fetch_rows", 3000)
402 457 
 modparam("carrierroute", "match_mode", 10)
403 458 
 ...
404 459
405 
-1.4. Exported Functions
460 
+4. Exported Functions
461 
+
462 
+   4.1. cr_user_carrier(user, domain, dstavp)
463 
+   4.2. cr_route(carrier, domain, prefix_matching, rewrite_user,
464 
+          hash_source, descavp)
465 
+
466 
+   4.3. cr_prime_route(carrier, domain, prefix_matching, rewrite_user,
467 
+          hash_source, descavp)
468 
+
469 
+   4.4. cr_nofallback_route(carrier, domain, prefix_matching,
470 
+          rewrite_user, hash_source, descavp)
471 
+
472 
+   4.5. cr_next_domain(carrier, domain, prefix_matching, host, reply_code,
473 
+          dstavp)
406 474
407 
-   Previous versions of carrierroute had some more function. All
408 
-   the old semantics can be achieved by using the few new
409 
-   functions like this:
475 
+   Previous versions of carrierroute had some more function. All the old
476 
+   semantics can be achieved by using the few new functions like this:
410 477 
 cr_rewrite_uri(domain, hash_source)
411 478 
 -> cr_route("default", domain, "$rU", "$rU", hash_source)
412 479
... ... 
@@ -432,178 +499,217 @@ cr_user_rewrite_uri(uri, domain)
432 499 
 cr_tree_rewrite_uri(tree, domain)
433 500 
 -> cr_route(tree, domain, "$rU", "$rU", "call_id")
434 501
435 
-1.4.1.  cr_user_carrier(user, domain, dstavp)
502 
+4.1.  cr_user_carrier(user, domain, dstavp)
436 503
437 
-   This function loads the carrier and stores it in an AVP. It
438 
-   cannot be used in the config file mode, as it needs a mapping
439 
-   of the given user to a certain carrier. The is derived from a
440 
-   database entry belonging to the user parameter. This mapping
441 
-   must be available in the table that is specified in the
442 
-   "subscriber_table" variable. This data is not cached in memory,
443 
-   that means for every execution of this function a database
504 
+   This function loads the carrier and stores it in an AVP. It cannot be
505 
+   used in the config file mode, as it needs a mapping of the given user
506 
+   to a certain carrier. The is derived from a database entry belonging to
507 
+   the user parameter. This mapping must be available in the table that is
508 
+   specified in the "subscriber_table" variable. This data is not cached
509 
+   in memory, that means for every execution of this function a database
444 510 
    query will be done.
445 511
446 512 
    Meaning of the parameters is as follows:
447 
-     * user - Name of the user for the carrier tree lookup.
448 
-       Additional to a string any pseudo-variable could be used as
449 
-       input.
450 
-     * domain - Name of the routing domain to be used. Additional
451 
-       to a string any pseudo-variable could be used as input.
513 
+     * user - Name of the user for the carrier tree lookup. Additional to
514 
+       a string any pseudo-variable could be used as input.
515 
+     * domain - Name of the routing domain to be used. Additional to a
516 
+       string any pseudo-variable could be used as input.
452 517 
      * dstavp - Name of the AVP where to store the carrier id.
453 518
454 
-1.4.2.  cr_route(carrier, domain, prefix_matching, rewrite_user,
455 
-hash_source, descavp)
456 
-
457 
-   This function searches for the longest match for the user given
458 
-   in prefix_matching at the given domain in the given carrier
459 
-   tree. The Request URI is rewritten using rewrite_user and the
460 
-   given hash source and algorithm. Returns -1 if there is no data
461 
-   found or an empty rewrite host on the longest match is found.
462 
-   On sucess also the description is stored in the given AVP (if
463 
-   obmitted, nothing is stored in an AVP). This is useful if you
464 
-   need some additional informations that belongs to each gw, like
465 
-   the destination or the number of channels.
466 
-
467 
-   This function is only usable with rewrite_user and
468 
-   prefix_matching containing a valid string. This string needs to
469 
-   be numerical if the match_mode parameter is set to 10. It uses
470 
-   the standard CRC32 algorithm to calculate the hash values.
471 
-
472 
-   If flags and masks values are specified in the routing rule,
473 
-   they will be compared by this function to the message flags.
474 
-   Specify a flag and mask value of "0" to match to all possible
475 
-   message flags (this is the default value). If flags and mask
476 
-   are not zero, and no match to the message flags is possible, no
477 
-   routing will be done. The calculation of the hash and the
478 
-   load-balancing is done after the flags matching.
519 
+4.2.  cr_route(carrier, domain, prefix_matching, rewrite_user, hash_source,
520 
+descavp)
521 
+
522 
+   This function searches for the longest match for the user given in
523 
+   prefix_matching at the given domain in the given carrier tree. The
524 
+   Request URI is rewritten using rewrite_user and the given hash source
525 
+   and algorithm. Returns -1 if there is no data found or an empty rewrite
526 
+   host on the longest match is found. On sucess also the description is
527 
+   stored in the given AVP (if obmitted, nothing is stored in an AVP).
528 
+   This is useful if you need some additional informations that belongs to
529 
+   each gw, like the destination or the number of channels.
530 
+
531 
+   This function is only usable with rewrite_user and prefix_matching
532 
+   containing a valid string. This string needs to be numerical if the
533 
+   match_mode parameter is set to 10. It uses the standard CRC32 algorithm
534 
+   to calculate the hash values.
535 
+
536 
+   If flags and masks values are specified in the routing rule, they will
537 
+   be compared by this function to the message flags. Specify a flag and
538 
+   mask value of "0" to match to all possible message flags (this is the
539 
+   default value). If flags and mask are not zero, and no match to the
540 
+   message flags is possible, no routing will be done. The calculation of
541 
+   the hash and the load-balancing is done after the flags matching.
479 542
480 543 
    Meaning of the parameters is as follows:
481 
-     * carrier - The routing tree to be used. Additional to a
544 
+     * carrier - The routing tree to be used. Additional to a string any
545 
+       pseudo-variable could be used as input.
546 
+     * domain - Name of the routing domain to be used. Additional to a
482 547 
        string any pseudo-variable could be used as input.
483 
-     * domain - Name of the routing domain to be used. Additional
548 
+     * prefix_matching - User name to be used for prefix matching in the
549 
+       routing tree. Additional to a string any pseudo-variable could be
550 
+       used as input.
551 
+     * rewrite_user - The user name to be used for applying the rewriting
552 
+       rule. Usually this is the user part of the request URI. Additional
484 553 
        to a string any pseudo-variable could be used as input.
485 
-     * prefix_matching - User name to be used for prefix matching
486 
-       in the routing tree. Additional to a string any
487 
-       pseudo-variable could be used as input.
488 
-     * rewrite_user - The user name to be used for applying the
489 
-       rewriting rule. Usually this is the user part of the
490 
-       request URI. Additional to a string any pseudo-variable
491 
-       could be used as input.
492 
-     * hash_source - The hash values of the destination set must
493 
-       be a contiguous range starting at 1, limited by the
494 
-       configuration parameter max_targets. Possible values for
495 
-       hash_source are: call_id, from_uri, from_user, to_uri and
496 
-       to_user and rand.
497 
-     * decsavp - Name of the AVP where to store the description.
498 
-       This parameter is optional.
499 
-
500 
-1.4.3.  cr_prime_route(carrier, domain, prefix_matching,
501 
-rewrite_user, hash_source, descavp)
502 
-
503 
-   This function searches for the longest match for the user given
504 
-   in prefix_matching at the given domain in the given carrier
505 
-   tree. The Request URI is rewritten using rewrite_user and the
506 
-   given hash source and algorithm. Returns -1 if there is no data
507 
-   found or an empty rewrite host on the longest match is found.
508 
-   On success also the description is stored in the given AVP (if
509 
-   obmitted, nothing is stored in an AVP). This is useful if you
510 
-   need some additional informations that belongs to each gw, like
511 
-   the destination or the number of channels. This function is
512 
-   only usable with rewrite_user and prefix_matching containing a
513 
-   valid string. This string needs to be numerical if the
514 
-   match_mode parameter is set to 10.
515 
-
516 
-   It uses the prime hash algorithm to calculate the hash values.
517 
-   This means that the fuction behaves different then the normal
518 
-   routing function. If you don't know what this prime
519 
-   functionality is, you should just use the cr_route function.
520 
-   The prime routing algorithm not use the configured
521 
-   probabilities in order to route requests, it just uses a fixed
522 
-   hash distribution. If one of the hash targets is not available,
523 
-   and no backup rule is configured, the function will return -1.
554 
+     * hash_source - The hash values of the destination set must be a
555 
+       contiguous range starting at 1, limited by the configuration
556 
+       parameter max_targets. Possible values for hash_source are:
557 
+       call_id, from_uri, from_user, to_uri, to_user and rand
558 
+     * decsavp - Name of the AVP where to store the description. This
559 
+       parameter is optional.
560 
+
561 
+4.3.  cr_prime_route(carrier, domain, prefix_matching, rewrite_user,
562 
+hash_source, descavp)
563 
+
564 
+   This function searches for the longest match for the user given in
565 
+   prefix_matching at the given domain in the given carrier tree. The
566 
+   Request URI is rewritten using rewrite_user and the given hash source
567 
+   and algorithm. Returns -1 if there is no data found or an empty rewrite
568 
+   host on the longest match is found. On success also the description is
569 
+   stored in the given AVP (if obmitted, nothing is stored in an AVP).
570 
+   This is useful if you need some additional informations that belongs to
571 
+   each gw, like the destination or the number of channels. This function
572 
+   is only usable with rewrite_user and prefix_matching containing a valid
573 
+   string. This string needs to be numerical if the match_mode parameter
574 
+   is set to 10.
575 
+
576 
+   It uses the prime hash algorithm to calculate the hash values. This
577 
+   means that the fuction behaves different then the normal routing
578 
+   function. If you don't know what this prime functionality is, you
579 
+   should just use the cr_route function. The prime routing algorithm not
580 
+   use the configured probabilities in order to route requests, it just
581 
+   uses a fixed hash distribution. If one of the hash targets is not
582 
+   available, and no backup rule is configured, the function will return
583 
+   -1.
584 
+
585 
+   Please not that this function is deprecated and will be removed in the
586 
+   next stable release. Please consider using the cr_nofallback_route
587 
+   function instead.
524 588
525 589 
    Meaning of the parameters is as follows:
526 
-     * carrier - The routing tree to be used. Additional to a
590 
+     * carrier - The routing tree to be used. Additional to a string any
591 
+       pseudo-variable could be used as input.
592 
+     * domain - Name of the routing domain to be used. Additional to a
527 593 
        string any pseudo-variable could be used as input.
528 
-     * domain - Name of the routing domain to be used. Additional
594 
+     * prefix_matching - User name to be used for prefix matching in the
595 
+       routing tree. Additional to a string any pseudo-variable could be
596 
+       used as input.
597 
+     * rewrite_user - The user name to be used for applying the rewriting
598 
+       rule. Usually this is the user part of the request URI. Additional
529 599 
        to a string any pseudo-variable could be used as input.
530 
-     * prefix_matching - User name to be used for prefix matching
531 
-       in the routing tree. Additional to a string any
532 
-       pseudo-variable could be used as input.
533 
-     * rewrite_user - The user name to be used for applying the
534 
-       rewriting rule. Usually this is the user part of the
535 
-       request URI. Additional to a string any pseudo-variable
536 
-       could be used as input.
537 
-     * hash_source - The hash values of the destination set must
538 
-       be a contiguous range starting at 1, limited by the
539 
-       configuration parameter max_targets. Possible values for
540 
-       hash_source are: call_id, from_uri, from_user, to_uri ,
541 
-       to_user and rand
542 
-     * descavp - Name of the AVP where to store the description.
543 
-       This parameter is optional.
544 
-
545 
-1.4.4.  cr_next_domain(carrier, domain, prefix_matching, host,
546 
-reply_code, dstavp)
547 
-
548 
-   This function searches for the longest match for the user given
549 
-   in prefix_matching at the given domain in the given carrier
550 
-   failure tree. It tries to find a next domain matching the given
551 
-   host, reply_code and the message flags. The matching is done in
552 
-   this order: host, reply_code and then flags. The more wildcards
553 
-   in reply_code and the more bits used in flags, the lower the
554 
-   priority. Returns -1 if there is no data found or an empty
555 
-   next_domain on the longest match is found. Otherwise the next
556 
-   domain is stored in the given AVP. This function is only usable
557 
-   with rewrite_user and prefix_matching containing a valid
558 
-   string. This string needs to be numerical if the match_mode
559 
-   parameter is set to 10.
600 
+     * hash_source - The hash values of the destination set must be a
601 
+       contiguous range starting at 1, limited by the configuration
602 
+       parameter max_targets. Possible values for hash_source are:
603 
+       call_id, from_uri, from_user, to_uri to_user and rand
604 
+     * descavp - Name of the AVP where to store the description. This
605 
+       parameter is optional.
606 
+
607 
+4.4.  cr_nofallback_route(carrier, domain, prefix_matching, rewrite_user,
608 
+hash_source, descavp)
609 
+
610 
+   This function searches for the longest match for the user given in
611 
+   prefix_matching at the given domain in the given carrier tree. The
612 
+   Request URI is rewritten using rewrite_user and the given hash source
613 
+   and algorithm. Returns -1 if there is no data found or an empty rewrite
614 
+   host on the longest match is found. On success also the description is
615 
+   stored in the given AVP (if obmitted, nothing is stored in an AVP).
616 
+   This is useful if you need some additional informations that belongs to
617 
+   each gw, like the destination or the number of channels. This function
618 
+   is only usable with rewrite_user and prefix_matching containing a valid
619 
+   string. This string needs to be numerical if the match_mode parameter
620 
+   is set to 10.
621 
+
622 
+   It uses the standard CRC32 algorithm to calculate the hash values. In
623 
+   contrast to the normal cr_route function the backup rules of
624 
+   cr_prime_route is used. This means not the configured probabilities
625 
+   will be used, only a fixed hash distribution. This makes sense to
626 
+   distribute incoming register requests e.g. to a bunch of registrar
627 
+   servers. If one of the hash targets is not available and backup rule is
628 
+   configured, the function will return -1.
560 629
561 630 
    Meaning of the parameters is as follows:
562 
-     * carrier - The routing tree to be used. Additional to a
631 
+     * carrier - The routing tree to be used. Additional to a string any
632 
+       pseudo-variable could be used as input.
633 
+     * domain - Name of the routing domain to be used. Additional to a
563 634 
        string any pseudo-variable could be used as input.
564 
-     * domain - Name of the routing domain to be used. Additional
635 
+     * prefix_matching - User name to be used for prefix matching in the
636 
+       routing tree. Additional to a string any pseudo-variable could be
637 
+       used as input.
638 
+     * rewrite_user - The user name to be used for applying the rewriting
639 
+       rule. Usually this is the user part of the request URI. Additional
565 640 
        to a string any pseudo-variable could be used as input.
566 
-     * prefix_matching - User name to be used for prefix matching
567 
-       in the routing tree. Additional to a string any
641 
+     * hash_source - The hash values of the destination set must be a
642 
+       contiguous range starting at 1, limited by the configuration
643 
+       parameter max_targets. Possible values for hash_source are:
644 
+       call_id, from_uri, from_user, to_uri and to_user.
645 
+     * descavp - Name of the AVP where to store the description. This
646 
+       parameter is optional.
647 
+
648 
+4.5.  cr_next_domain(carrier, domain, prefix_matching, host, reply_code,
649 
+dstavp)
650 
+
651 
+   This function searches for the longest match for the user given in
652 
+   prefix_matching at the given domain in the given carrier failure tree.
653 
+   It tries to find a next domain matching the given host, reply_code and
654 
+   the message flags. The matching is done in this order: host, reply_code
655 
+   and then flags. The more wildcards in reply_code and the more bits used
656 
+   in flags, the lower the priority. Returns -1 if there is no data found
657 
+   or an empty next_domain on the longest match is found. Otherwise the
658 
+   next domain is stored in the given AVP. This function is only usable
659 
+   with rewrite_user and prefix_matching containing a valid string. This
660 
+   string needs to be numerical if the match_mode parameter is set to 10.
661 
+
662 
+   Meaning of the parameters is as follows:
663 
+     * carrier - The routing tree to be used. Additional to a string any
568 664 
        pseudo-variable could be used as input.
569 
-     * host - The host name to be used for failure route rule
570 
-       matching. Usually this is the last tried routing
571 
-       destination stored in an avp by cr_route. Additional to a
665 
+     * domain - Name of the routing domain to be used. Additional to a
572 666 
        string any pseudo-variable could be used as input.
573 
-     * reply_code - The reply code to be used for failure route
574 
-       rule matching. Additional to a string any pseudo-variable
575 
-       could be used as input.
576 
-     * dstavp - Name of the AVP where to store the next routing
577 
-       domain.
578 
-
579 
-1.5. MI Commands
580 
-
581 
-   All commands understand the "-?" parameter to print a short
582 
-   help message. The options have to be quoted as one string to be
583 
-   passed to MI interface. Each option except host and new host
584 
-   can be wildcarded by * (but only * and not things like "-d
585 
-   prox*").
586 
-
587 
-1.5.1. cr_reload_routes
667 
+     * prefix_matching - User name to be used for prefix matching in the
668 
+       routing tree. Additional to a string any pseudo-variable could be
669 
+       used as input.
670 
+     * host - The host name to be used for failure route rule matching.
671 
+       Usually this is the last tried routing destination stored in an avp
672 
+       by cr_route. Additional to a string any pseudo-variable could be
673 
+       used as input.
674 
+     * reply_code - The reply code to be used for failure route rule
675 
+       matching. Additional to a string any pseudo-variable could be used
676 
+       as input.
677 
+     * dstavp - Name of the AVP where to store the next routing domain.
678 
+
679 
+5. MI Commands
680 
+
681 
+   5.1. cr_reload_routes
682 
+   5.2. cr_dump_routes
683 
+   5.3. cr_replace_host
684 
+   5.4. cr_deactivate_host
685 
+   5.5. cr_activate_host
686 
+   5.6. cr_add_host
687 
+   5.7. cr_delete_host
688 
+
689 
+   All commands understand the "-?" parameter to print a short help
690 
+   message. The options have to be quoted as one string to be passed to MI
691 
+   interface. Each option except host and new host can be wildcarded by *
692 
+   (but only * and not things like "-d prox*").
693 
+
694 
+5.1. cr_reload_routes
588 695
589 696 
    This command reloads the routing data from the data source.
590 697
591 
-   Important: When new domains have been added, a restart of the
592 
-   server must be done, because the mapping of the ids used in the
593 
-   config script cannot be updated at runtime at the moment. So a
594 
-   reload could result in a wrong routing behaviour, because the
595 
-   ids used in the script could differ from the one used
596 
-   internally from the server. Modifying of already existing
597 
-   domains is no problem.
698 
+   Important: When new domains have been added, a restart of the server
699 
+   must be done, because the mapping of the ids used in the config script
700 
+   cannot be updated at runtime at the moment. So a reload could result in
701 
+   a wrong routing behaviour, because the ids used in the script could
702 
+   differ from the one used internally from the server. Modifying of
703 
+   already existing domains is no problem.
598 704
599 
-1.5.2. cr_dump_routes
705 
+5.2. cr_dump_routes
600 706
601 707 
    This command prints the route rules on the command line.
602 708
603 
-1.5.3. cr_replace_host
709 
+5.3. cr_replace_host
604 710
605 
-   This command can replace the rewrite_host of a route rule, it
606 
-   is only usable in file mode. Following options are possible:
711 
+   This command can replace the rewrite_host of a route rule, it is only
712 
+   usable in file mode. Following options are possible:
607 713 
      * -d - the domain containing the host
608 714 
      * -p - the prefix containing the host
609 715 
      * -h - the host to be replaced
... ... 
@@ -616,20 +722,19 @@ reply_code, dstavp)
616 722 
 kamctl fifo cr_replace_host "-d proxy -p 49 -h proxy1 -t proxy2"
617 723 
 ...
618 724
619 
-1.5.4. cr_deactivate_host
725 
+5.4. cr_deactivate_host
620 726
621 
-   This command deactivates the specified host, i.e. it sets its
622 
-   status to 0. It is only usable in file mode. Following options
623 
-   are possible:
727 
+   This command deactivates the specified host, i.e. it sets its status to
728 
+   0. It is only usable in file mode. Following options are possible:
624 729 
      * -d - the domain containing the host
625 730 
      * -p - the prefix containing the host
626 731 
      * -h - the host to be deactivated
627 732 
      * -t - the new host used as backup
628 733
629 734 
    When -t (new_host) is specified, the portion of traffic for the
630 
-   deactivated host is routed to the host given by -t. This is
631 
-   indicated in the output of dump_routes. The backup route is
632 
-   deactivated if the host is activated again.
735 
+   deactivated host is routed to the host given by -t. This is indicated
736 
+   in the output of dump_routes. The backup route is deactivated if the
737 
+   host is activated again.
633 738
634 739 
    Use the "null" prefix to specify an empty prefix.
635 740
... ... 
@@ -638,11 +743,10 @@ kamctl fifo cr_replace_host "-d proxy -p 49 -h proxy1 -t proxy2"
638 743 
 kamctl fifo cr_deactivate_host "-d proxy -p 49 -h proxy1"
639 744 
 ...
640 745
641 
-1.5.5. cr_activate_host
746 
+5.5. cr_activate_host
642 747
643 
-   This command activates the specified host, i.e. it sets its
644 
-   status to 1. It is only usable in file mode. Following options
645 
-   are possible:
748 
+   This command activates the specified host, i.e. it sets its status to
749 
+   1. It is only usable in file mode. Following options are possible:
646 750 
      * -d - the domain containing the host
647 751 
      * -p - the prefix containing the host
648 752 
      * -h - the host to be activated
... ... 
@@ -654,7 +758,7 @@ kamctl fifo cr_deactivate_host "-d proxy -p 49 -h proxy1"
654 758 
 kamctl fifo cr_activate_host "-d proxy -p 49 -h proxy1"
655 759 
 ...
656 760
657 
-1.5.6. cr_add_host
761 
+5.6. cr_add_host
658 762
659 763 
    This command adds a route rule, it is only usable in file mode.
660 764 
    Following options are possible:
... ... 
@@ -674,11 +778,11 @@ kamctl fifo cr_activate_host "-d proxy -p 49 -h proxy1"
674 778 
 kamctl fifo cr_add_host "-d proxy -p 49 -h proxy1 -w 0.25"
675 779 
 ...
676 780
677 
-1.5.7. cr_delete_host
781 
+5.7. cr_delete_host
678 782
679 
-   This command delete the specified hosts or rules, i.e. remove
680 
-   them from the route tree. It is only usable in file mode.
681 
-   Following options are possible:
783 
+   This command delete the specified hosts or rules, i.e. remove them from
784 
+   the route tree. It is only usable in file mode. Following options are
785 
+   possible:
682 786 
      * -d - the domain containing the host
683 787 
      * -p - the prefix containing the host
684 788 
      * -h - the host to be added
... ... 
@@ -695,7 +799,7 @@ kamctl fifo cr_add_host "-d proxy -p 49 -h proxy1 -w 0.25"
695 799 
 kamctl fifo cr_delete_host "-d proxy -p 49 -h proxy1 -w 0.25"
696 800 
 ...
697 801
698 
-1.6. Configuration examples
802 
+6. Configuration examples
699 803
700 804 
    Example 1.17. Configuration example - Routing to default tree
701 805 
 ...
... ... 
@@ -730,7 +834,6 @@ failure_route[2] {
730 834 
         # further processing
731 835 
 }
732 836
733 
-
734 837 
    Example 1.18. Configuration example - Routing to user tree
735 838 
 ...
736 839 
 route[1] {
... ... 
@@ -755,8 +858,7 @@ route[1] {
755 858 
 failure_route[1] {
756 859 
         revert_uri();
757 860 
         if (!cr_next_domain("$avp(s:carrier)", "$avp(s:domain)", "$rU",
758 
-                        "$avp(s:host)", "$T_reply_code", "$avp(s:domain)
759 
-")) {
861 
+                        "$avp(s:host)", "$T_reply_code", "$avp(s:domain)")) {
760 862 
                 xlog("L_ERR", "cr_next_domain failed\n");
761 863 
                 exit;
762 864 
         }
... ... 
@@ -777,24 +879,22 @@ failure_route[1] {
777 879
778 880 
    Example 1.19. Configuration example - module configuration
779 881
780 
-   The following config file specifies within the default carrier
781 
-   two domains, each with an prefix that contains two hosts. It is
782 
-   not possible to specify another carrier if you use the config
783 
-   file as data source.
784 
-
785 
-   All traffic will be equally distributed between the hosts, both
786 
-   are active. The hash algorithm will working over the [1,2] set,
787 
-   messages hashed to one will go to the first host, the other to
788 
-   the second one. Don't use a hash index value of zero. If you
789 
-   ommit the hash completly, the module gives them a autogenerated
790 
-   value, starting from one.
791 
-
792 
-   Use the "NULL" prefix to specify an empty prefix in the config
793 
-   file. Please note that the prefix is matched against the
794 
-   request URI (or to URI), if they did not contain a valid
795 
-   (numerical) URI, no match is possible. So for loadbalancing
796 
-   purposes e.g. for your registrars, you should use an empty
797 
-   prefix.
882 
+   The following config file specifies within the default carrier two
883 
+   domains, each with an prefix that contains two hosts. It is not
884 
+   possible to specify another carrier if you use the config file as data
885 
+   source.
886 
+
887 
+   All traffic will be equally distributed between the hosts, both are
888 
+   active. The hash algorithm will working over the [1,2] set, messages
889 
+   hashed to one will go to the first host, the other to the second one.
890 
+   Don't use a hash index value of zero. If you ommit the hash completly,
891 
+   the module gives them a autogenerated value, starting from one.
892 
+
893 
+   Use the "NULL" prefix to specify an empty prefix in the config file.
894 
+   Please note that the prefix is matched against the request URI (or to
895 
+   URI), if they did not contain a valid (numerical) URI, no match is
896 
+   possible. So for loadbalancing purposes e.g. for your registrars, you
897 
+   should use an empty prefix.
798 898 
 ...
799 899 
 domain proxy {
800 900 
    prefix 49 {
... ... 
@@ -833,29 +933,32 @@ domain register {
833 933 
 }
834 934 
 ...
835 935
836 
-1.7. Installation and Running
936 
+7. Installation and Running
937 
+
938 
+   7.1. Database setup
939 
+   7.2. Database examples
940 
+   7.3. User specific routing
837 941
838 
-1.7.1. Database setup
942 
+7.1. Database setup
839 943
840 
-   Before running Kamailio with carrierroute, you have to setup
841 
-   the database table where the module will store the routing
842 
-   data. For that, if the table was not created by the
843 
-   installation script or you choose to install everything by
844 
-   yourself you can use the carrierroute-create.sql SQL script in
845 
-   the database directories in the kamailio/scripts folder as
846 
-   template. Database and table name can be set with module
847 
-   parameters so they can be changed, but the name of the columns
848 
-   must be as they are in the SQL script. You can also find the
944 
+   Before running Kamailio with carrierroute, you have to setup the
945 
+   database table where the module will store the routing data. For that,
946 
+   if the table was not created by the installation script or you choose
947 
+   to install everything by yourself you can use the
948 
+   carrierroute-create.sql SQL script in the database directories in the
949 
+   kamailio/scripts folder as template. Database and table name can be set
950 
+   with module parameters so they can be changed, but the name of the
951 
+   columns must be as they are in the SQL script. You can also find the
849 952 
    complete database documentation on the project webpage,
850 
-   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
851 
-   The flags and mask columns have the same function as in the
852 
-   carrierfailureroute table. A zero value in the flags and mask
853 
-   column means that any message flags will match this rule.
953 
+   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html. The
954 
+   flags and mask columns have the same function as in the
955 
+   carrierfailureroute table. A zero value in the flags and mask column
956 
+   means that any message flags will match this rule.
854 957
855 
-   For a minimal configuration either use the config file given
856 
-   above, or insert some data into the tables of the module.
958 
+   For a minimal configuration either use the config file given above, or
959 
+   insert some data into the tables of the module.
857 960
858 
-1.7.2. Database examples
961 
+7.2. Database examples
859 962
860 963 
    Example 1.20. Example database content - carrierroute table
861 964 
 ...
... ... 
@@ -878,26 +981,24 @@ domain register {
878 981 
 +----+---------+--------+-------------+-------+------+---------------+
879 982 
 ...
880 983
881 
-   This table contains three routes to two gateways for the "49"
882 
-   prefix, and a default route for other prefixes over carrier 2
883 
-   and carrier 1. The gateways for the default carrier will be
884 
-   used for functions that don't support the user specific carrier
885 
-   lookup. The routing rules for carrier 1 and carrier 2 for the
886 
-   "49" prefix contains a additional rule with the domain 2, that
887 
-   can be used for example as fallback if the gateways in domain 1
888 
-   are not reachable. Two more fallback rules (domain 3 and 4) for
889 
-   carrier 1 are also supplied to support the functionality of the
890 
-   carrierfailureroute table example that is provided in the next
984 
+   This table contains three routes to two gateways for the "49" prefix,
985 
+   and a default route for other prefixes over carrier 2 and carrier 1.
986 
+   The gateways for the default carrier will be used for functions that
987 
+   don't support the user specific carrier lookup. The routing rules for
988 
+   carrier 1 and carrier 2 for the "49" prefix contains a additional rule
989 
+   with the domain 2, that can be used for example as fallback if the
990 
+   gateways in domain 1 are not reachable. Two more fallback rules (domain
991 
+   3 and 4) for carrier 1 are also supplied to support the functionality
992 
+   of the carrierfailureroute table example that is provided in the next
891 993 
    section.
892 994
893 
-   This table provides also a "carrier 1" routing rule for the
894 
-   "49" prefix, that is only choosen if some message flags are
895 
-   set. If this flags are not set, the other two rules are used.
896 
-   The "strip", "mask" and "comment" colums are omitted for
897 
-   brevity.
995 
+   This table provides also a "carrier 1" routing rule for the "49"
996 
+   prefix, that is only choosen if some message flags are set. If this
997 
+   flags are not set, the other two rules are used. The "strip", "mask"
998 
+   and "comment" colums are omitted for brevity.
898 999
899 
-   Example 1.21. Example database content - simple
900 
-   carrierfailureroute table
1000 
+   Example 1.21. Example database content - simple carrierfailureroute
1001 
+   table
901 1002 
 ...
902 1003 
 +----+---------+--------+---------------+------------+-------------+
903 1004 
 | id | carrier | domain | host_name     | reply_code | next_domain |
... ... 
@@ -907,16 +1008,16 @@ domain register {
907 1008 
 +----+---------+--------+---------------+------------+-------------+
908 1009 
 ...
909 1010
910 
-   This table contains two failure routes for the "gw.carrier1-1"
911 
-   and "-2" gateways. For any (failure) reply code the respective
912 
-   next domain is choosen. After that no more failure routes are
913 
-   available, an error will be returned from the "cr_next_domain"
914 
-   function. Not all table colums are show here for brevity.
1011 
+   This table contains two failure routes for the "gw.carrier1-1" and "-2"
1012 
+   gateways. For any (failure) reply code the respective next domain is
1013 
+   choosen. After that no more failure routes are available, an error will
1014 
+   be returned from the "cr_next_domain" function. Not all table colums
1015 
+   are show here for brevity.
915 1016
916 1017 
    For each failure route domain and carrier that is added to the
917 
-   carrierfailureroute table there must be at least one
918 
-   corresponding entry in the carrierroute table, otherwise the
919 
-   module will not load the routing data.
1018 
+   carrierfailureroute table there must be at least one corresponding
1019 
+   entry in the carrierroute table, otherwise the module will not load the
1020 
+   routing data.
920 1021
921 1022 
    Example 1.22. Example database content - more complex
922 1023 
    carrierfailureroute table
... ... 
@@ -931,19 +1032,17 @@ domain register {
931 1032 
 +----+---------+-----------+------------+-------+------+-------------+
932 1033 
 ...
933 1034
934 
-   This table contains four failure routes that shows the usage of
935 
-   more advanced features. The first route matches to a 408, and
936 
-   to some flag for example that indicates that ringing has
937 
-   happened. If this flag is set, there will be no further
938 
-   forwarding, because next_domain is empty. In the second and
939 
-   third routes are certain gateway errors matched, if this errors
940 
-   have occured, then the next domain will be choosen. The last
941 
-   route does forwarding according some flags, e.g. the customer
942 
-   came from a certain carrier, and has call-forwarding
943 
-   deactivated. In order to use the routing that is specified
944 
-   above, a matching carrierroute table must be provided, that
945 
-   holds domain entries for this routing rules. Not all table
946 
-   colums are show here for brevity.
1035 
+   This table contains four failure routes that shows the usage of more
1036 
+   advanced features. The first route matches to a 408, and to some flag
1037 
+   for example that indicates that ringing has happened. If this flag is
1038 
+   set, there will be no further forwarding, because next_domain is empty.
1039 
+   In the second and third routes are certain gateway errors matched, if
1040 
+   this errors have occured, then the next domain will be choosen. The
1041 
+   last route does forwarding according some flags, e.g. the customer came
1042 
+   from a certain carrier, and has call-forwarding deactivated. In order
1043 
+   to use the routing that is specified above, a matching carrierroute
1044 
+   table must be provided, that holds domain entries for this routing
1045 
+   rules. Not all table colums are show here for brevity.
947 1046
948 1047 
    Example 1.23. Example database content - carrier_name table
949 1048 
 ...
... ... 
@@ -956,8 +1055,7 @@ domain register {
956 1055 
 +----+----------+
957 1056 
 ...
958 1057
959 
-   This table contains the mapping of the carrier id to actual
960 
-   names.
1058 
+   This table contains the mapping of the carrier id to actual names.
961 1059
962 1060 
    Example 1.24. Example database content - domain_name table
963 1061 
 ...
... ... 
@@ -970,15 +1068,14 @@ domain register {
970 1068 
 +----+----------+
971 1069 
 ...
972 1070
973 
-   This table contains the mapping of the domain id to actual
974 
-   names.
1071 
+   This table contains the mapping of the domain id to actual names.
975 1072
976 
-1.7.3. User specific routing
1073 
+7.3. User specific routing
977 1074
978 
-   For a functional routing the "cr_preferred_carrier" column must
979 
-   be added to the subscriber table (or to the table and column
980 
-   that you specified as modul parameter) to choose the actual
981 
-   carrier for the users.
1075 
+   For a functional routing the "cr_preferred_carrier" column must be
1076 
+   added to the subscriber table (or to the table and column that you
1077 
+   specified as modul parameter) to choose the actual carrier for the
1078 
+   users.
982 1079
983 1080 
    Example 1.25. Necessary extensions for the user table
984 1081
... ... 
@@ -989,20 +1086,52 @@ ALTER TABLE subscriber ADD cr_preferred_carrier int(10) default NULL;
989 1086
990 1087 
 Chapter 2. Module parameter for database access.
991 1088
992 
-2.1. db_url (String)
1089 
+   Table of Contents
1090 
+
1091 
+   1. db_url (String)
1092 
+   2. carrierroute_table (String)
1093 
+   3. carrierroute_id_col (string)
1094 
+   4. carrierroute_carrier_col (string)
1095 
+   5. carrierroute_domain_col (string)
1096 
+   6. carrierroute_scan_prefix_col (string)
1097 
+   7. carrierroute_flags_col (string)
1098 
+   8. carrierroute_mask_col (string)
1099 
+   9. carrierroute_prob_col (string)
1100 
+   10. carrierroute_strip_col (string)
1101 
+   11. carrierroute_rewrite_host_col (string)
1102 
+   12. carrierroute_rewrite_prefix_col (string)
1103 
+   13. carrierroute_rewrite_suffix_col (string)
1104 
+   14. carrierroute_description_col (string)
1105 
+   15. carrierfailureroute_table (String)
1106 
+   16. carrierfailureroute_id_col (string)
1107 
+   17. carrierfailureroute_carrier_col (string)
1108 
+   18. carrierfailureroute_domain_col (string)
1109 
+   19. carrierfailureroute_scan_prefix_col (string)
1110 
+   20. carrierfailureroute_host_name_col (string)
1111 
+   21. carrierfailureroute_reply_code_col (string)
1112 
+   22. carrierfailureroute_flags_col (string)
1113 
+   23. carrierfailureroute_mask_col (string)
1114 
+   24. carrierfailureroute_next_domain_col (string)
1115 
+   25. carrierfailureroute_description_col (string)
1116 
+   26. carrier_name_table (String)
1117 
+   27. carrier_name_id_col (string)
1118 
+   28. carrier_name_carrier_col (string)
1119 
+   29. domain_name_table (String)
1120 
+   30. domain_name_id_col (string)
1121 
+   31. domain_name_domain_col (string)
1122 
+
1123 
+1. db_url (String)
993 1124
994 1125 
    URL to the database containing the data.
995 1126
996 
-   Default value is
997 
-   "mysql://openserro:openserro@localhost/openser".
1127 
+   Default value is "mysql://openserro:openserro@localhost/openser".
998 1128
999 1129 
    Example 2.1. Set db_url parameter
1000 1130 
 ...
1001 
-modparam("carrierroute", "db_url", "dbdriver://username:password@dbhost/
1002 
-dbname")
1131 
+modparam("carrierroute", "db_url", "dbdriver://username:password@dbhost/dbname")
1003 1132 
 ...
1004 1133
1005 
-2.2. carrierroute_table (String)
1134 
+2. carrierroute_table (String)
1006 1135
1007 1136 
    Name of the carrierroute table for the carrierroute module.
1008 1137
... ... 
@@ -1013,7 +1142,7 @@ dbname")
1013 1142 
 modparam("carrierroute", "carrierroute_table", "carrierroute")
1014 1143 
 ...
1015 1144
1016 
-2.3. carrierroute_id_col (string)
1145 
+3. carrierroute_id_col (string)
1017 1146
1018 1147 
    Name of the column contains the unique identifier of a route.
1019 1148
... ... 
@@ -1022,7 +1151,7 @@ modparam("carrierroute", "carrierroute_table", "carrierroute")
1022 1151 
 modparam("carrierroute", "carrierroute_id_col", "id")
1023 1152 
 ...
1024 1153
1025 
-2.4. carrierroute_carrier_col (string)
1154 
+4. carrierroute_carrier_col (string)
1026 1155
1027 1156 
    This column contains the carrier id.
1028 1157
... ... 
@@ -1031,33 +1160,31 @@ modparam("carrierroute", "carrierroute_id_col", "id")
1031 1160 
 modparam("carrierroute", "carrierroute_carrier_col", "carrier")
1032 1161 
 ...
1033 1162
1034 
-2.5. carrierroute_domain_col (string)
1163 
+5. carrierroute_domain_col (string)
1035 1164
1036 
-   This column contains the routing domain id. You can define
1037 
-   several routing domains to have different routing rules. Maybe
1038 
-   you use domain 0 for normal routing and domain 1 if domain 0
1039 
-   failed.
1165 
+   This column contains the routing domain id. You can define several
1166 
+   routing domains to have different routing rules. Maybe you use domain 0
1167 
+   for normal routing and domain 1 if domain 0 failed.
1040 1168
1041 1169 
    Example 2.5. Set carrierroute_domain_col parameter
1042 1170 
 ...
1043 1171 
 modparam("carrierroute", "carrierroute_domain_col", "domain")
1044 1172 
 ...
1045 1173
1046 
-2.6. carrierroute_scan_prefix_col (string)
1174 
+6. carrierroute_scan_prefix_col (string)
1047 1175
1048 
-   Name of column contains the scan prefixes. Scan prefixes define
1049 
-   the matching portion of a phone number, e.g. when we have the
1050 
-   scan prefixes 49721 and 49, the called number is 49721913740,
1051 
-   it matches 49721, because the longest match is taken. If no
1052 
-   prefix matches, the number is not routed. To prevent this, an
1053 
-   empty prefix value of could be added.
1176 
+   Name of column contains the scan prefixes. Scan prefixes define the
1177 
+   matching portion of a phone number, e.g. when we have the scan prefixes
1178 
+   49721 and 49, the called number is 49721913740, it matches 49721,
1179 
+   because the longest match is taken. If no prefix matches, the number is
1180 
+   not routed. To prevent this, an empty prefix value of could be added.
1054 1181
1055 1182 
    Example 2.6. Set carrierroute_scan_prefix_col parameter
1056 1183 
 ...
1057 1184 
 modparam("carrierroute", "carrierroute_scan_prefix_col", "scan_prefix")
1058 1185 
 ...
1059 1186
1060 
-2.7. carrierroute_flags_col (string)
1187 
+7. carrierroute_flags_col (string)
1061 1188
1062 1189 
    This column contains the flags used for rule matching.
1063 1190
... ... 
@@ -1066,106 +1193,99 @@ modparam("carrierroute", "carrierroute_scan_prefix_col", "scan_prefix")
1066 1193 
 modparam("carrierroute", "ca