modules_k/carrierroute/README
867cd3cc
 carrierroute
 
 Jonas Appel
 
    1&1 Internet AG
 
8974005b
 Hardy Kahl
 
    1&1 Internet AG
 
867cd3cc
 Henning Westerholt
 
    1&1 Internet AG
 
2c0290d4
    Copyright � 2007 1&1 Internet AG
d77df08a
    Revision History
9bba7c11
    Revision $Revision: 3912 $ $Date: 2008-03-10 16:13:24 +0100
                               (Mo, 10 Mär 2008) $
e04c7022
      __________________________________________________________
867cd3cc
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
867cd3cc
 
         1.1. Overview
         1.2. Dependencies
 
37e4f522
               1.2.1. Kamailio Modules
867cd3cc
               1.2.2. External Libraries or Applications
 
         1.3. Exported Parameters
 
               1.3.1. db_url (string)
               1.3.2. db_table (string)
               1.3.3. id_column (string)
               1.3.4. carrier_column (string)
               1.3.5. scan_prefix_column (string)
5dd75701
               1.3.6. domain_column (string)
97aefd62
               1.3.7. flags_column (string)
               1.3.8. mask_column (string)
               1.3.9. prob_column (string)
               1.3.10. rewrite_host_column (string)
               1.3.11. strip_column (string)
               1.3.12. comment_column (string)
               1.3.13. carrier_table (string)
               1.3.14. rewrite_prefix_column (string)
               1.3.15. rewrite_suffix_column (string)
               1.3.16. carrier_id_col (string)
               1.3.17. carrier_name_col (string)
               1.3.18. subscriber_table (string)
               1.3.19. subscriber_user_col (string)
               1.3.20. subscriber_domain_col (string)
               1.3.21. subscriber_carrier_col (string)
               1.3.22. config_source (string)
               1.3.23. config_file (string)
               1.3.24. default_tree (string)
               1.3.25. use_domain (int)
               1.3.26. fallback_default (int)
               1.3.27. db_failure_table (string)
               1.3.28. failure_id_column (string)
               1.3.29. failure_carrier_column (string)
               1.3.30. failure_scan_prefix_column (string)
               1.3.31. failure_domain_column (string)
               1.3.32. failure_host_name_column (string)
               1.3.33. failure_reply_code_column (string)
               1.3.34. failure_flags_column (string)
               1.3.35. failure_mask_column (string)
               1.3.36. failure_next_domain_column (string)
               1.3.37. failure_comment_column (string)
867cd3cc
 
         1.4. Exported Functions
 
8974005b
               1.4.1. cr_user_carrier(user, domain, dstavp)
1e4bd3e8
               1.4.2. cr_route(carrier, domain, prefix_matching,
b2046d54
                       rewrite_user, hash_source, dstavp)
 
               1.4.3. cr_prime_route(carrier, domain,
                       prefix_matching, rewrite_user, hash_source,
1e4bd3e8
                       dstavp)
867cd3cc
 
b2046d54
               1.4.4. cr_next_domain(carrier, domain,
97aefd62
                       prefix_matching, host, reply_code, dstavp)
867cd3cc
 
         1.5. MI Commands
 
aa9bfbce
               1.5.1. cr_reload_routes
               1.5.2. cr_dump_routes
               1.5.3. cr_replace_host
               1.5.4. cr_deactivate_host
               1.5.5. cr_activate_host
               1.5.6. cr_add_host
               1.5.7. cr_delete_host
867cd3cc
 
         1.6. Examples
d77df08a
         1.7. Installation and Running
867cd3cc
 
               1.7.1. Database setup
 
    List of Examples
d77df08a
 
    1.1. Set db_url parameter
    1.2. Set db_table parameter
    1.3. Set id_column parameter
    1.4. Set carrier_column parameter
    1.5. Set scan_prefix_column parameter
    1.6. Set domain_column parameter
97aefd62
    1.7. Set flags_column parameter
    1.8. Set mask_column parameter
    1.9. Set prob_column parameter
    1.10. Set rewrite_host_column parameter
    1.11. Set strip_column parameter
    1.12. Set comment_column parameter
    1.13. Set carrier_table parameter
    1.14. Set rewrite_prefix_column parameter
    1.15. Set rewrite_suffix_column parameter
    1.16. Set id_col parameter
    1.17. Set carrier_name_col parameter
    1.18. Set subscriber_table parameter
    1.19. Set subscriber_user_col parameter
    1.20. Set subscriber_domain_col parameter
    1.21. Set subscriber_carrier_col parameter
    1.22. Set config_source parameter
    1.23. Set config_file parameter
    1.24. Set default_tree parameter
    1.25. Set use_domain parameter
    1.26. Set fallback_default parameter
    1.27. Set db_failuretable parameter
    1.28. Set failure_id_column parameter
    1.29. Set failure_carrier_column parameter
    1.30. Set failure_scan_prefix_column parameter
    1.31. Set failure_domain_column parameter
    1.32. Set failure_host_name_column parameter
    1.33. Set failure_reply_code_column parameter
    1.34. Set failure_flags_column parameter
    1.35. Set failure_mask_column parameter
    1.36. Set failure_next_domain_column parameter
    1.37. Set failure_comment_column parameter
    1.38. cr_replace_host usage
    1.39. cr_deactivate_host usage
    1.40. cr_activate_host usage
    1.41. cr_add_host usage
    1.42. cr_delete_host usage
    1.43. Configuration example - Routing to default tree
    1.44. Configuration example - Routing to user tree
    1.45. Configuration example - module configuration
    1.46. Example database content - carrierroute table
    1.47. Example database content - simple carrierfailureroute
1e4bd3e8
           table
 
97aefd62
    1.48. Example database content - more complex
1e4bd3e8
           carrierfailureroute table
 
97aefd62
    1.49. Example database content - route_tree table
    1.50. Necessary extensions for the user table
867cd3cc
 
9fc784c6
 Chapter 1. Admin Guide
867cd3cc
 
 1.1. Overview
 
    A module which provides routing, balancing and blacklisting
    capabilities.
 
da0cbb99
    The module provides routing, balancing and blacklisting
    capabilities. It reads routing entries from a database source
    or from a config file at OpenSER startup. It can uses one
d0646e6a
    routing tree (for one carrier), or if needed for every user a
    different routing tree (unique for each carrier) for number
    prefix based routing. It supports several route tree domains,
    e.g. for failback routes or different routing rules for VoIP
    and PSTN targets.
 
e04c7022
    Based on the tree, the module decides which number prefixes are
    forwarded to which gateway. It can also distribute the traffic
    by ratio parameters. Furthermore, the requests can be
d0646e6a
    distributed by a hash funcion to predictable destinations. The
    hash source is configurable, two different hash functions are
    available.
da0cbb99
 
b2046d54
    This modules scales up to more than a few million users, and is
ea77ec08
    able to handle more than several hundred thousand routing table
b2046d54
    entries. It should be able to handle more, but this is not that
    much tested at the moment. In load balancing scenarios the
    usage of the config file mode is recommended, to avoid the
    additional complexity that the database driven routing creates.
da0cbb99
 
e04c7022
    Routing tables can be reloaded and edited (in config file mode)
    with the MI interface, the config file is updated according the
    changes. This is not implemented for the db interface, because
    its easier to do the changes directly on the db. But the reload
    and dump functions works of course here too.
da0cbb99
 
68ebb805
    Some module functionality is not fully available in the config
    file mode, as it is not possible to specify all information
    that can be stored in the database tables in the config file.
    Further information about these limitations is given in later
10fb3a4a
    sections. For user based routing or LCR you should use the
    database mode.
68ebb805
 
da0cbb99
    Basically this module could be used as an replacement for the
e04c7022
    lcr and the dispatcher module, if you have certain performance,
    flexibility and/or integration requirements that these modules
    don't handle properly. But for small installations it probably
    make more sense to use the lcr and dispatcher module.
05b15933
 
    If you want to use this module in failure routes, then you need
    to call "append_branch()" after rewriting the request URI in
b2046d54
    order to relay the message to the new target. Its also
    supportes the usage of database derived failure routing
    descisions with the carrierfailureroute table.
867cd3cc
 
 1.2. Dependencies
 
37e4f522
 1.2.1. Kamailio Modules
867cd3cc
 
da0cbb99
    The following module must be loaded before this module:
e04c7022
      * a database module, when a database is used as configuration
05b15933
        data source. Only SQL based databases are supported, as
        this module needs the capability to issue raw queries. Its
        not possible to use the dbtext or db_berkeley module at the
        moment.
8974005b
      * The tm module, when you want to use the $T_reply_code
        pseudo-variable in the "cr_next_domain" function.
867cd3cc
 
 1.2.2. External Libraries or Applications
 
    The following libraries or applications must be installed
37e4f522
    before running Kamailio with this module loaded:
a0881e4b
      * libconfuse, a configuration file parser library. (
        http://www.nongnu.org/confuse/ )
867cd3cc
 
 1.3. Exported Parameters
 
 1.3.1. db_url (string)
 
    Url to the database containing the routing data.
 
c36fcce4
    Default value is
    "mysql://openserro:openserro@localhost/openser".
867cd3cc
 
d77df08a
    Example 1.1. Set db_url parameter
867cd3cc
 ...
c36fcce4
 modparam("carrierroute", "db_url", "dbdriver://username:password@dbhost/
 dbname")
867cd3cc
 ...
 
 1.3.2. db_table (string)
 
    Name of the table where the routing data is stored.
 
e04c7022
    Default value is "carrierroute".
867cd3cc
 
d77df08a
    Example 1.2. Set db_table parameter
867cd3cc
 ...
 modparam("carrierroute", "db_table", "carrierroute")
 ...
 
 1.3.3. id_column (string)
 
    Name of the column containing the id identifier.
 
e04c7022
    Default value is "id".
867cd3cc
 
d77df08a
    Example 1.3. Set id_column parameter
867cd3cc
 ...
 modparam("carrierroute", "id_column", "id")
 ...
 
 1.3.4. carrier_column (string)
 
    Name of the column containing the carrier id.
 
e04c7022
    Default value is "carrier".
867cd3cc
 
d77df08a
    Example 1.4. Set carrier_column parameter
867cd3cc
 ...
 modparam("carrierroute", "carrier_column", "carrier")
 ...
 
 1.3.5. scan_prefix_column (string)
 
741f4e94
    Name of column containing the scan prefixes. Scan prefixes
    define the matching portion of a phone number, e.g. when we
    have the scan prefixes 49721 and 49, the called number is
    49721913740, it matches 49721, because the longest match is
    taken. If no prefix matches, the number is not routed. To
    prevent this, an empty prefix value of "" could be added.
867cd3cc
 
e04c7022
    Default value is "scan_prefix".
867cd3cc
 
d77df08a
    Example 1.5. Set scan_prefix_column parameter
867cd3cc
 ...
 modparam("carrierroute", "scan_prefix_column", "scan_prefix")
 ...
 
5dd75701
 1.3.6. domain_column (string)
867cd3cc
 
5dd75701
    Name of column containing the rule domain. You can define
    several routing domains to have different routing rules. Maybe
    you use domain 0 for normal routing and domain 1 if domain 0
867cd3cc
    failed.
 
e04c7022
    Default value is "domain".
867cd3cc
 
d77df08a
    Example 1.6. Set domain_column parameter
867cd3cc
 ...
5dd75701
 modparam("carrierroute", "domain_column", "domain")
867cd3cc
 ...
 
97aefd62
 1.3.7. flags_column (string)
 
    Name of the column containing the flags.
 
    Default value is "flags".
 
    Example 1.7. Set flags_column parameter
 ...
 modparam("carrierroute", "flags_column", "flags")
 ...
 
 1.3.8. mask_column (string)
 
    Name of the column containing the flags mask.
 
    Default value is "mask".
 
    Example 1.8. Set mask_column parameter
 ...
 modparam("carrierroute", "mask_column", "mask")
 ...
 
 1.3.9. prob_column (string)
867cd3cc
 
e04c7022
    Name of column containing probability. The probability value is
    used to distribute the traffic between several gateways. Let's
    say 70 % of the traffic shall be routed to gateway A, the other
    30 % shall be routed to gateway B, we define a rule for gateway
    A with a prob value of 0.7 and a rule for gateway B with a prob
    value of 0.3.
867cd3cc
 
5dd75701
    If all probabilities for a given prefix, tree and domain don't
68ebb805
    add to 100%, the prefix values will be adjusted according the
e04c7022
    given prob values. E.g. if three hosts with prob values of 0.5,
    0.5 and 0.4 are defined, the resulting probabilities are
    35.714, 35.714 and 28.571%. But its better to choose meaningful
    values in the first place because of clarity.
68ebb805
 
e04c7022
    Default value is "prob".
867cd3cc
 
97aefd62
    Example 1.9. Set prob_column parameter
867cd3cc
 ...
 modparam("carrierroute", "prob_column", "prob")
 ...
 
97aefd62
 1.3.10. rewrite_host_column (string)
867cd3cc
 
    Name of column containing rewrite host value. An empty field
    represents a blacklist entry, anything else is put as domain
    part into the Request URI of the SIP message.
 
e04c7022
    Default value is "rewrite_host".
867cd3cc
 
97aefd62
    Example 1.10. Set rewrite_host_column parameter
867cd3cc
 ...
 modparam("carrierroute", "rewrite_host_column", "rewrite_host")
 ...
 
97aefd62
 1.3.11. strip_column (string)
867cd3cc
 
    Name of the column containing the number of digits to be
    stripped of the userpart of an URI before prepending
    rewrite_prefix.
 
e04c7022
    Default value is "strip".
867cd3cc
 
97aefd62
    Example 1.11. Set strip_column parameter
867cd3cc
 ...
 modparam("carrierroute", "strip_column", "strip")
 ...
 
97aefd62
 1.3.12. comment_column (string)
867cd3cc
 
    Name of the column containing an optional comment (useful in
e04c7022
    large routing tables) The comment is also displayed by the fifo
    cmd "cr_dump_routes".
867cd3cc
 
0b9f434e
    Default value is "description".
867cd3cc
 
97aefd62
    Example 1.12. Set comment_column parameter
867cd3cc
 ...
0b9f434e
 modparam("carrierroute", "comment_column", "description")
867cd3cc
 ...
 
97aefd62
 1.3.13. carrier_table (string)
867cd3cc
 
d0646e6a
    The name of the table containing the existing carriers,
    consisting of the ids and corresponding names.
867cd3cc
 
e04c7022
    Default value is "route_tree".
867cd3cc
 
97aefd62
    Example 1.13. Set carrier_table parameter
867cd3cc
 ...
 modparam("carrierroute", "carrier_table", "route_tree")
 ...
 
97aefd62
 1.3.14. rewrite_prefix_column (string)
867cd3cc
 
e04c7022
    Name of column containing rewrite prefixes. Here you can define
    a rewrite prefix for the localpart of the SIP URI.
867cd3cc
 
e04c7022
    Default value is "rewrite_prefix".
867cd3cc
 
97aefd62
    Example 1.14. Set rewrite_prefix_column parameter
867cd3cc
 ...
10b11dac
 modparam("carrierroute", "rewrite_prefix_column", "rewrite_prefix")
867cd3cc
 ...
 
97aefd62
 1.3.15. rewrite_suffix_column (string)
867cd3cc
 
e04c7022
    Name of column containing rewrite suffixes. Here you can define
    a rewrite suffix for the localpart of the SIP URI.
867cd3cc
 
e04c7022
    Default value is "rewrite_suffix".
867cd3cc
 
97aefd62
    Example 1.15. Set rewrite_suffix_column parameter
867cd3cc
                             ...
ea77ec08
 modparam("carrierroute", "rewrite_suffix_column", "rewrite_suffix")
867cd3cc
                             ...
 
97aefd62
 1.3.16. carrier_id_col (string)
867cd3cc
 
    The name of the column in the carrier table containing the
    carrier id.
 
e04c7022
    Default value is "id".
867cd3cc
 
97aefd62
    Example 1.16. Set id_col parameter
867cd3cc
 ...
 modparam("carrierroute", "carrier_id_col", "id")
 ...
 
97aefd62
 1.3.17. carrier_name_col (string)
867cd3cc
 
    The name of the column in the carrier table containing the
    carrier name.
 
e04c7022
    Default value is "carrier".
867cd3cc
 
97aefd62
    Example 1.17. Set carrier_name_col parameter
867cd3cc
 ...
 modparam("carrierroute", "carrier_name_col", "carrier")
 ...
 
97aefd62
 1.3.18. subscriber_table (string)
867cd3cc
 
    The name of the table containing the subscribers
 
e04c7022
    Default value is "subscriber".
867cd3cc
 
97aefd62
    Example 1.18. Set subscriber_table parameter
867cd3cc
 ...
 modparam("carrierroute", "subscriber_table", "subscriber")
 ...
 
97aefd62
 1.3.19. subscriber_user_col (string)
867cd3cc
 
    The name of the column in the subscriber table containing the
    usernames.
 
e04c7022
    Default value is "username".
867cd3cc
 
97aefd62
    Example 1.19. Set subscriber_user_col parameter
867cd3cc
 ...
07661cfc
 modparam("carrierroute", "subscriber_user_col", "username")
867cd3cc
 ...
 
97aefd62
 1.3.20. subscriber_domain_col (string)
867cd3cc
 
    The name of the column in the subscriber table containing the
    domain of the subscriber.
 
e04c7022
    Default value is "domain".
867cd3cc
 
97aefd62
    Example 1.20. Set subscriber_domain_col parameter
867cd3cc
 ...
 modparam("carrierroute", "subscriber_domain_col", "domain")
 ...
 
97aefd62
 1.3.21. subscriber_carrier_col (string)
867cd3cc
 
    The name of the column in the subscriber table containing the
    carrier id of the subscriber.
 
e04c7022
    Default value is "cr_preferred_carrier".
867cd3cc
 
97aefd62
    Example 1.21. Set subscriber_carrier_col parameter
867cd3cc
 ...
e04c7022
 modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier
 ")
867cd3cc
 ...
 
97aefd62
 1.3.22. config_source (string)
867cd3cc
 
    Specifies whether the module loads its config data from a file
    or from a database. Possible values are file or db.
 
e04c7022
    Default value is "file".
867cd3cc
 
97aefd62
    Example 1.22. Set config_source parameter
867cd3cc
 ...
 modparam("carrierroute", "config_source", "file")
 ...
 
97aefd62
 1.3.23. config_file (string)
867cd3cc
 
    Specifies the path to the config file.
 
e04c7022
    Default value is "/etc/openser/carrierroute.conf".
867cd3cc
 
97aefd62
    Example 1.23. Set config_file parameter
867cd3cc
 ...
e04c7022
 modparam("carrierroute", "config_file", "/etc/openser/carrierroute.conf"
 )
867cd3cc
 ...
 
97aefd62
 1.3.24. default_tree (string)
867cd3cc
 
    The name of the carrier tree used per default (if the current
    subscriber has no preferred tree)
 
e04c7022
    Default value is "default".
867cd3cc
 
97aefd62
    Example 1.24. Set default_tree parameter
867cd3cc
 ...
 modparam("carrierroute", "default_tree", "default")
 ...
 
97aefd62
 1.3.25. use_domain (int)
867cd3cc
 
    When using tree lookup per user, this parameter specifies
    whether to use the domain part for user matching or not.
 
e04c7022
    Default value is "0".
867cd3cc
 
97aefd62
    Example 1.25. Set use_domain parameter
867cd3cc
 ...
2da5a59e
 modparam("carrierroute", "use_domain", 0)
867cd3cc
 ...
 
97aefd62
 1.3.26. fallback_default (int)
867cd3cc
 
e04c7022
    This parameter defines the behaviour when using user-based tree
    lookup. If the user has a non-existing tree set and
867cd3cc
    fallback_default is set to 1, the default tree is used.
    Otherwise, cr_user_rewrite_uri returns an error.
 
e04c7022
    Default value is "1".
867cd3cc
 
97aefd62
    Example 1.26. Set fallback_default parameter
867cd3cc
 ...
2da5a59e
 modparam("carrierroute", "fallback_default", 1)
867cd3cc
 ...
 
97aefd62
 1.3.27. db_failure_table (string)
1e4bd3e8
 
    Name of the table where the failure routing data is stored.
867cd3cc
 
1e4bd3e8
    Default value is "carrierfailureroute".
 
97aefd62
    Example 1.27. Set db_failuretable parameter
1e4bd3e8
 ...
 modparam("carrierroute", "db_failuretable", "carrierfailureroute")
 ...
68ebb805
 
97aefd62
 1.3.28. failure_id_column (string)
867cd3cc
 
1e4bd3e8
    Name of the column containing the id identifier.
867cd3cc
 
1e4bd3e8
    Default value is "id".
867cd3cc
 
97aefd62
    Example 1.28. Set failure_id_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_id_column", "id")
 ...
867cd3cc
 
97aefd62
 1.3.29. failure_carrier_column (string)
867cd3cc
 
1e4bd3e8
    Name of the column containing the carrier id.
867cd3cc
 
1e4bd3e8
    Default value is "carrier".
867cd3cc
 
97aefd62
    Example 1.29. Set failure_carrier_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_carrier_column", "carrier")
 ...
867cd3cc
 
97aefd62
 1.3.30. failure_scan_prefix_column (string)
867cd3cc
 
1e4bd3e8
    Name of column containing the scan prefixes. Scan prexies
    define the matching portion of a phone number, e.g. we have the
    scan prefixes 49721 and 49, the called number is 49721913740,
    it matches 49721, because the longest match is taken. If no
    prefix matches, the number is not failure routed. To prevent
8efaf823
    this, an empty prefix value of "" could be added.
867cd3cc
 
1e4bd3e8
    Default value is "scan_prefix".
867cd3cc
 
97aefd62
    Example 1.30. Set failure_scan_prefix_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_scan_prefix_column", "scan_prefix")
 ...
867cd3cc
 
97aefd62
 1.3.31. failure_domain_column (string)
867cd3cc
 
1e4bd3e8
    Name of column containing the rule domain. You can define
    several routing domains to have different routing rules. Maybe
    you use domain 0 for normal routing and domain 1 if domain 0
    failed.
867cd3cc
 
1e4bd3e8
    Default value is "domain".
867cd3cc
 
97aefd62
    Example 1.31. Set failure_domain_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_domain_column", "domain")
 ...
 
97aefd62
 1.3.32. failure_host_name_column (string)
1e4bd3e8
 
    Name of the column containing the host name of the last routing
    destination.
 
    Default value is "host_name".
 
97aefd62
    Example 1.32. Set failure_host_name_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_host_name_column", "host_name")
 ...
 
97aefd62
 1.3.33. failure_reply_code_column (string)
1e4bd3e8
 
    Name of the column containing the reply code.
 
    Default value is "reply_code".
 
97aefd62
    Example 1.33. Set failure_reply_code_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_reply_code_column", "reply_code")
 ...
867cd3cc
 
97aefd62
 1.3.34. failure_flags_column (string)
b449fe73
 
1e4bd3e8
    Name of the column containing the flags.
 
    Default value is "flags".
 
97aefd62
    Example 1.34. Set failure_flags_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_flags_column", "flags")
 ...
 
97aefd62
 1.3.35. failure_mask_column (string)
1e4bd3e8
 
    Name of the column containing the flags mask.
 
    Default value is "mask".
 
97aefd62
    Example 1.35. Set failure_mask_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_mask_column", "mask")
 ...
 
97aefd62
 1.3.36. failure_next_domain_column (string)
1e4bd3e8
 
    Name of the column containing the next routing domain.
 
    Default value is "next_domain".
 
97aefd62
    Example 1.36. Set failure_next_domain_column parameter
1e4bd3e8
 ...
 modparam("carrierroute", "failure_next_domain_column", "next_domain")
 ...
 
97aefd62
 1.3.37. failure_comment_column (string)
1e4bd3e8
 
    Name of the column containing an optional comment.
 
0b9f434e
    Default value is "description".
1e4bd3e8
 
97aefd62
    Example 1.37. Set failure_comment_column parameter
1e4bd3e8
 ...
0b9f434e
 modparam("carrierroute", "failure_comment_column", "description")
1e4bd3e8
 ...
 
 1.4. Exported Functions
 
    Previous versions of carriertree had some more function. All
    the old semantics can be achieved by using the few new
    functions like this:
 cr_rewrite_uri(domain, hash_source)
9bba7c11
 -> cr_route("default", domain, "$rU", "$rU", hash_source)
1e4bd3e8
 
 cr_prime_balance_uri(domain, hash_source)
9bba7c11
 -> cr_prime_route("default", domain, "$rU", "$rU", hash_source)
1e4bd3e8
 
 cr_rewrite_by_to(domain, hash_source)
9bba7c11
 -> cr_route("default", domain, "$tU", "$rU", hash_source)
1e4bd3e8
 
 cr_prime_balance_by_to(domain, hash_source)
9bba7c11
 -> cr_prime_route("default", domain, "$tU", "$rU", hash_source)
1e4bd3e8
 
 cr_rewrite_by_from(domain, hash_source)
9bba7c11
 -> cr_route("default", domain, "$fU", "$rU", hash_source)
1e4bd3e8
 
 cr_prime_balance_by_from(domain, hash_source)
9bba7c11
 -> cr_prime_route("default", domain, "$fU", "$rU", hash_source)
1e4bd3e8
 
 cr_user_rewrite_uri(uri, domain)
8974005b
 -> cr_user_carrier(user, domain, "$avp(tree_avp)")
9bba7c11
 -> cr_route("$avp(tree_avp)", domain, "$rU", "$rU", "call_id")
1e4bd3e8
 
 cr_tree_rewrite_uri(tree, domain)
9bba7c11
 -> cr_route(tree, domain, "$rU", "$rU", "call_id")
1e4bd3e8
 
d77df08a
 1.4.1.  cr_user_carrier(user, domain, dstavp)
1e4bd3e8
 
    This function loads the carrier and stores it in an AVP. It
    cannot be used in the config file mode, as it needs a mapping
8efaf823
    of the given user to a certain carrier. This mapping must be
    available in the table that is specified in the
    "subscriber_table" variable.
b449fe73
 
    Meaning of the parameters is as follows:
1e4bd3e8
      * user - Name of the user for the carrier tree lookup.
        Additional to a string any pseudo-variable could be used as
        input.
      * domain - Name of the routing domain to be used. Additional
        to a string any pseudo-variable could be used as input.
      * dstavp - Name of the AVP where to store the carrier id.
b449fe73
 
d77df08a
 1.4.2.  cr_route(carrier, domain, prefix_matching, rewrite_user,
b2046d54
 hash_source, dstavp)
867cd3cc
 
1e4bd3e8
    This function searches for the longest match for the user given
    in prefix_matching at the given domain in the given carrier
    tree. The Request URI is rewritten using rewrite_user and the
    given hash source and algorithm. Returns -1 if there is no data
    found or an empty rewrite host on the longest match is found.
    Otherwise the rewritten host is stored in the given AVP (if
    obmitted, the host is not stored in an AVP). This function is
    only usable with rewrite_user and prefix_matching containing a
b2046d54
    valid numerical only string. It uses the standard crc32
    algorithm to calculate the hash values.
867cd3cc
 
    Meaning of the parameters is as follows:
1e4bd3e8
      * carrier - The routing tree to be used. Additional to a
        string any pseudo-variable could be used as input.
      * domain - Name of the routing domain to be used. Additional
        to a string any pseudo-variable could be used as input.
      * prefix_matching - User name to be used for prefix matching
        in the routing tree. Additional to a string any
        pseudo-variable could be used as input.
      * rewrite_user - The user name to be used for applying the
        rewriting rule. Usually this is the user part of the
        request URI. Additional to a string any pseudo-variable
        could be used as input.
      * hash_source - The hash values of the destination set must
        be a contiguous range starting at 1, limited by the
        configuration parameter max_targets. Possible values for
        hash_source are: call_id, from_uri, from_user, to_uri and
        to_user.
      * dstavp - Name of the AVP where to store the rewritten host.
b2046d54
        This parameter is optional.
867cd3cc
 
d77df08a
 1.4.3.  cr_prime_route(carrier, domain, prefix_matching,
 rewrite_user, hash_source, dstavp)
b2046d54
 
    This function searches for the longest match for the user given
    in prefix_matching at the given domain in the given carrier
    tree. The Request URI is rewritten using rewrite_user and the
    given hash source and algorithm. Returns -1 if there is no data
    found or an empty rewrite host on the longest match is found.
    Otherwise the rewritten host is stored in the given AVP (if
    obmitted, the host is not stored in an AVP). This function is
    only usable with rewrite_user and prefix_matching containing a
    valid numerical only string. It uses the prime hash algorithm
    to calculate the hash values.
 
    Meaning of the parameters is as follows:
      * carrier - The routing tree to be used. Additional to a
        string any pseudo-variable could be used as input.
      * domain - Name of the routing domain to be used. Additional
        to a string any pseudo-variable could be used as input.
      * prefix_matching - User name to be used for prefix matching
        in the routing tree. Additional to a string any
        pseudo-variable could be used as input.
      * rewrite_user - The user name to be used for applying the
        rewriting rule. Usually this is the user part of the
        request URI. Additional to a string any pseudo-variable
        could be used as input.
      * hash_source - The hash values of the destination set must
        be a contiguous range starting at 1, limited by the
        configuration parameter max_targets. Possible values for
        hash_source are: call_id, from_uri, from_user, to_uri and
        to_user.
      * dstavp - Name of the AVP where to store the rewritten host.
        This parameter is optional.
 
d77df08a
 1.4.4.  cr_next_domain(carrier, domain, prefix_matching, host,
97aefd62
 reply_code, dstavp)
867cd3cc
 
1e4bd3e8
    This function searches for the longest match for the user given
    in prefix_matching at the given domain in the given carrier
    failure tree. It tries to find a next domain matching the given
97aefd62
    host, reply_code and the message flags. The matching is done in
    this order: host, reply_code and then flags. The more wildcards
    in reply_code and the more bits used in flags, the lower the
1e4bd3e8
    priority. Returns -1 if there is no data found or an empty
    next_domain on the longest match is found. Otherwise the next
    domain is stored in the given AVP. This function is only usable
    with prefix_matching containing a valid numerical only string.
867cd3cc
 
    Meaning of the parameters is as follows:
1e4bd3e8
      * carrier - The routing tree to be used. Additional to a
        string any pseudo-variable could be used as input.
      * domain - Name of the routing domain to be used. Additional
        to a string any pseudo-variable could be used as input.
      * prefix_matching - User name to be used for prefix matching
        in the routing tree. Additional to a string any
        pseudo-variable could be used as input.
      * host - The host name to be used for failure route rule
        matching. Usually this is the last tried routing
        destination stored in an avp by cr_route. Additional to a
        string any pseudo-variable could be used as input.
      * reply_code - The reply code to be used for failure route
        rule matching. Additional to a string any pseudo-variable
        could be used as input.
      * dstavp - Name of the AVP where to store the next routing
        domain.
867cd3cc
 
 1.5. MI Commands
 
16ddad1c
    All commands understand the "-?" parameter to print a short
e04c7022
    help message. The options have to be quoted as one string to be
    passed to MI interface. Each option except host and new host
    can be wildcarded by * (but only * and not things like "-d
    prox*").
16ddad1c
 
aa9bfbce
 1.5.1. cr_reload_routes
867cd3cc
 
    This command reloads the routing data from the data source.
e04c7022
 
    Important: When new domains have been added, a restart of the
    server must be done, because the mapping of the ids used in the
    config script cannot be updated at runtime at the moment. So a
    reload could result in a wrong routing behaviour, because the
    ids used in the script could differ from the one used
    internally from the server. Modifying of already existing
    domains is no problem.
867cd3cc
 
aa9bfbce
 1.5.2. cr_dump_routes
867cd3cc
 
    This command prints the route rules on the command line.
 
aa9bfbce
 1.5.3. cr_replace_host
867cd3cc
 
    This command can replace the rewrite_host of a route rule, it
    is only usable in file mode. Following options are possible:
      * -d - the domain containing the host
      * -p - the prefix containing the host
      * -h - the host to be replaced
      * -t - the new host
 
2c0290d4
    Use the "null" prefix to specify an empty prefix.
867cd3cc
 
97aefd62
    Example 1.38. cr_replace_host usage
867cd3cc
 ...
bb30e4a8
 kamctl fifo cr_replace_host "-d proxy -p 49 -h proxy1 -t proxy2"
867cd3cc
 ...
 
aa9bfbce
 1.5.4. cr_deactivate_host
867cd3cc
 
    This command deactivates the specified host, i.e. it sets its
    status to 0. It is only usable in file mode. Following options
    are possible:
      * -d - the domain containing the host
      * -p - the prefix containing the host
      * -h - the host to be deactivated
16ddad1c
      * -t - the new host used as backup
 
e04c7022
    When -t (new_host) is specified, the portion of traffic for the
    deactivated host is routed to the host given by -t. This is
    indicated in the output of dump_routes. The backup route is
16ddad1c
    deactivated if the host is activated again.
867cd3cc
 
2c0290d4
    Use the "null" prefix to specify an empty prefix.
867cd3cc
 
97aefd62
    Example 1.39. cr_deactivate_host usage
867cd3cc
 ...
bb30e4a8
 kamctl fifo cr_deactivate_host "-d proxy -p 49 -h proxy1"
867cd3cc
 ...
 
aa9bfbce
 1.5.5. cr_activate_host
867cd3cc
 
    This command activates the specified host, i.e. it sets its
    status to 1. It is only usable in file mode. Following options
    are possible:
      * -d - the domain containing the host
      * -p - the prefix containing the host
      * -h - the host to be activated
 
2c0290d4
    Use the "null" prefix to specify an empty prefix.
867cd3cc
 
97aefd62
    Example 1.40. cr_activate_host usage
867cd3cc
 ...
bb30e4a8
 kamctl fifo cr_activate_host "-d proxy -p 49 -h proxy1"
867cd3cc
 ...
 
aa9bfbce
 1.5.6. cr_add_host
867cd3cc
 
e04c7022
    This command adds a route rule, it is only usable in file mode.
    Following options are possible:
867cd3cc
      * -d - the domain containing the host
      * -p - the prefix containing the host
      * -h - the host to be added
      * -w - the weight of the rule
      * -P - an optional rewrite prefix
      * -S - an optional rewrite suffix
      * -i - an optional hash index
      * -s - an optional strip value
 
2c0290d4
    Use the "null" prefix to specify an empty prefix.
867cd3cc
 
97aefd62
    Example 1.41. cr_add_host usage
867cd3cc
 ...
bb30e4a8
 kamctl fifo cr_add_host "-d proxy -p 49 -h proxy1 -w 0.25"
867cd3cc
 ...
 
aa9bfbce
 1.5.7. cr_delete_host
867cd3cc
 
    This command delete the specified hosts or rules, i.e. remove
    them from the route tree. It is only usable in file mode.
    Following options are possible:
      * -d - the domain containing the host
      * -p - the prefix containing the host
      * -h - the host to be added
      * -w - the weight of the rule
      * -P - an optional rewrite prefix
      * -S - an optional rewrite suffix
      * -i - an optional hash index
      * -s - an optional strip value
 
2c0290d4
    Use the "null" prefix to specify an empty prefix.
f201f072
 
97aefd62
    Example 1.42. cr_delete_host usage
f201f072
 ...
bb30e4a8
 kamctl fifo cr_delete_host "-d proxy -p 49 -h proxy1 -w 0.25"
f201f072
 ...
867cd3cc
 
 1.6. Examples
 
97aefd62
    Example 1.43. Configuration example - Routing to default tree
867cd3cc
 ...
12203b18
 route {
         # route calls based on hash over callid
5dd75701
         # choose route domain 0 of the default carrier
1e4bd3e8
 
         if(!cr_route("default", "0", "$rU", "$rU", "call_id", "crc32")){
12203b18
                 sl_send_reply("403", "Not allowed");
         } else {
                 # In case of failure, re-route the request
                 t_on_failure("1");
                 # Relay the request to the gateway
                 t_relay();
         }
 }
 
1fefdad1
 failure_route[1] {
12203b18
         # In case of failure, send it to an alternative route:
         if (t_check_status("408|5[0-9][0-9]")) {
5dd75701
                 #choose route domain 1 of the default carrier
1e4bd3e8
         if(!cr_route("default", "1", "$rU", "$rU", "call_id", "crc32")){
12203b18
                         t_reply("403", "Not allowed");
                 } else {
                         t_on_failure("2");
                         t_relay();
                 }
         }
 }
 
1fefdad1
 failure_route[2] {
12203b18
         # further processing
867cd3cc
 }
1e4bd3e8
 
 
97aefd62
    Example 1.44. Configuration example - Routing to user tree
1e4bd3e8
 ...
 route[1] {
8efaf823
         cr_user_carrier("$fU", "$fd", "$avp(s:carrier)");
1e4bd3e8
 
8efaf823
         # just an example domain
         $avp(s:domain)="start";
         if (!cr_route("$avp(s:carrier)", "$avp(s:domain)", "$rU", "$rU",
                         "call_id", "$avp(s:host)")) {
1e4bd3e8
                 xlog("L_ERR", "cr_route failed\n");
                 exit;
         }
         t_on_failure("1");
                 if (!t_relay()) {
                         sl_reply_error();
         };
 }
 
 failure_route[1] {
         revert_uri();
8efaf823
         if (!cr_next_domain("$avp(s:carrier)", "$avp(s:domain)", "$rU",
                         "$avp(s:host)", "$T_reply_code", "$avp(s:domain)
 ")) {
8974005b
                 xlog("L_ERR", "cr_next_domain failed\n");
                 exit;
         }
8efaf823
         if (!cr_route("$avp(s:carrier)", "$avp(s:domain)", "$rU", "$rU",
                         "call_id", "$avp(s:host)")) {
8974005b
                 xlog("L_ERR", "cr_route failed\n");
                 exit;
         }
         t_on_failure("1");
         append_branch();
         if (!t_relay()) {
                 xlog("L_ERR", "t_relay failed\n");
                 exit;
         };
1e4bd3e8
 }
867cd3cc
 ...
 
97aefd62
    Example 1.45. Configuration example - module configuration
2c0290d4
 
68ebb805
    The following config file specifies within the default carrier
e04c7022
    two domains, each with an prefix that contains two hosts. It is
    not possible to specify another carrier if you use the config
    file as data source.
ebf78933
 
e04c7022
    All traffic will be equally distributed between the hosts, both
    are active. The hash algorithm will working over the [1,2] set,
    messages hashed to one will go to the first host, the other to
    the second one. Don't use a hash index value of zero. If you
    ommit the hash completly, the module gives them a autogenerated
    value, starting from one.
ebf78933
 
741f4e94
    Use the "NULL" prefix to specify an empty prefix in the config
1fefdad1
    file. Please note that the prefix is matched against the
    request URI (or to URI), if they did not contain a valid
    numerical URI, no match is possible. So for loadbalancing
    purposes e.g. for your registrars, you should use an empty
    prefix.
867cd3cc
 ...
 domain proxy {
    prefix 49 {
e2c9212f
      max_targets = 2
68ebb805
       target proxy1.localdomain {
          prob = 0.500000
          hash_index = 1
          status = 1
          comment = "test target 1"
       }
       target proxy2.localdomain {
          prob = 0.500000
          hash_index = 2
          status = 1
          comment = "test target 2"
       }
    }
 }
 
 domain register {
1fefdad1
    prefix NULL {
e2c9212f
      max_targets = 2
68ebb805
       target register1.localdomain {
867cd3cc
          prob = 0.500000
          hash_index = 1
          status = 1
          comment = "test target 1"
       }
68ebb805
       target register2.localdomain {
867cd3cc
          prob = 0.500000
          hash_index = 2
          status = 1
          comment = "test target 2"
       }
    }
 }
 ...
 
d77df08a
 1.7. Installation and Running
867cd3cc
 
 1.7.1. Database setup
 
37e4f522
    Before running Kamailio with carrierroute, you have to setup
    the database table where the module will store the routing
    data. For that, if the table was not created by the
    installation script or you choose to install everything by
    yourself you can use the carrierroute-create.sql SQL script in
    the database directories in the openser/scripts folder as
    template. Database and table name can be set with module
    parameters so they can be changed, but the name of the columns
    must be as they are in the SQL script. You can also find the
    complete database documentation on the project webpage,
9cbd0164
    http://www.kamailio.org/docs/db-tables/openser-db-devel.html.
97aefd62
    The flags and mask columns have the same function as in the
    carrierfailureroute table. A zero value in the flags and mask
    column means that any message flags will match this rule.
867cd3cc
 
    For a minimal configuration either use the config file given
    above, or insert some data into the tables of the module.
 
97aefd62
    Example 1.46. Example database content - carrierroute table
 ...
 +----+---------+--------+-------------+-------+------+---------------+
 | id | carrier | domain | scan_prefix | flags | prob | rewrite_host  |
 +----+---------+--------+-------------+-------+------+---------------+
 | 1  |       1 |      0 | 49          |     0 |  0.5 | de-1.carrier1 |
 | 2  |       1 |      0 | 49          |     0 |  0.5 | de-2.carrier1 |
 | 3  |       1 |      0 | 49          |    16 |    1 | de-3.carrier1 |
 | 4  |       1 |      0 |             |     0 |    1 | gw.carrier1-1 |
 | 5  |       1 |      1 | 49          |     0 |    1 | gw.carrier1-1 |
 | 6  |       1 |      2 |             |     0 |    1 | gw.carrier1-2 |
 | 7  |       1 |      3 |             |     0 |    1 | gw.carrier1-3 |
 | 8  |       2 |      0 | 49          |     0 |  0.5 | de-1.carrier2 |
 | 9  |       2 |      0 | 49          |     0 |  0.5 | de-2.carrier2 |
 | 10 |       2 |      0 |             |     0 |    1 | gw.carrier2   |
 | 11 |       2 |      1 | 49          |     0 |    1 | gw.carrier2   |
 | 12 |       3 |  start | 49          |     0 |    1 | de-gw.default |
 | 13 |       3 |  start |             |     0 |    1 | gw.default    |
 +----+---------+--------+-------------+-------+------+---------------+
 ...
 
    This table contains three routes to two gateways for the "49"
74eda4b0
    prefix, and a default route for other prefixes over carrier 2
    and carrier 1. The gateways for the default carrier will be
e04c7022
    used for functions that don't support the user specific carrier
    lookup. The routing rules for carrier 1 and carrier 2 for the
    "49" prefix contains a additional rule with the domain 1, that
    can be used for example as fallback if the gateways in domain 0
1e4bd3e8
    are not reachable. Two more fallback rules (domain 2 and 3) for
    carrier 1 are also supplied to support the functionality of the
    carrierfailureroute table example that is provided in the next
    section. The usage of strings for the domains is also possible,
    for example at carrier 3.
 
97aefd62
    This table provides also a "carrier1" routing rule for the "49"
    prefix, that is only choosen if some message flags are set. If
    this flags are not set, the other two rules are used. The
    "strip", "mask" and "comment" colums are omitted for brevity.
 
    Example 1.47. Example database content - simple
1e4bd3e8
    carrierfailureroute table
 ...
 +----+---------+--------+---------------+------------+-------------+
 | id | carrier | domain | host_name     | reply_code | next_domain |
 +----+---------+--------+---------------+------------+-------------+
 |  1 |       1 | 0      | gw.carrier1-2 | ...        | 3           |
 |  2 |       1 | 0      | gw.carrier1-3 | ...        | 2           |
 +----+---------+--------+---------------+------------+-------------+
 ...
 
    This table contains two failure routes for the "gw.carrier1-1"
    and "-2" gateways. For any (failure) reply code the respective
    next domain is choosen. After that no more failure routes are
8974005b
    available, an error will be returned from the "cr_next_domain"
    function. Not all table colums are show here for brevity.
1e4bd3e8
 
b2046d54
    For each failure route domain and carrier that is added to the
    carrierfailureroute table there must be at least one
    corresponding entry in the carrierroute table, otherwise the
    module will not load the routing data.
 
97aefd62
    Example 1.48. Example database content - more complex
1e4bd3e8
    carrierfailureroute table
 ...
 +----+---------+-----------+------------+--------+-----+-------------+
 | id | domain  | host_name | reply_code | flags | mask | next_domain |
 +----+---------+-----------+------------+-------+------+-------------+
 |  1 |      99 |           | 408        |    16 |   16 |             |
 |  2 |      99 | gw1       | 404        |     0 |    0 | 100         |
 |  3 |      99 | gw2       | 50.        |     0 |    0 | 100         |
 |  4 |      99 |           | 404        |  2048 | 2112 | asterisk-1  |
532d1682
 +----+---------+-----------+------------+-------+------+-------------+
1e4bd3e8
 ...
 
    This table contains four failure routes that shows the usage of
    more advanced features. The first route matches to a 408, and
    to some flag for example that indicates that ringing has
    happened. If this flag is set, there will be no further
    forwarding, because next_domain is empty. In the second and
    third routes are certain gateway errors matched, if this errors
    have occured, then the next domain will be choosen. The last
    route does forwarding according some flags, e.g. the customer
    came from a certain carrier, and has call-forwarding
    deactivated. In order to use the routing that is specified
    above, a matching carrierroute table must be provided, that
    holds domain entries for this routing rules. Not all table
    colums are show here for brevity.
 
97aefd62
    Example 1.49. Example database content - route_tree table
867cd3cc
 ...
 +----+----------+
 | id | carrier  |
 +----+----------+
 |  1 | carrier1 |
 |  2 | carrier2 |
 |  3 | default  |
 +----+----------+
 ...
 
    This table contains the mapping of the carrier id to actual
68ebb805
    names.
 
e04c7022
    For a functional routing the "cr_preferred_carrier" column must
    be added to the subscriber table (or to the table and column
    that you specified as modul parameter) to choose the actual
    carrier for the users.
32b5027f
 
97aefd62
    Example 1.50. Necessary extensions for the user table
32b5027f
 
    Suggested changes:
 ...
 ALTER TABLE subscriber ADD cr_preferred_carrier int(10) default NULL;
 ...