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