carrierroute

The following module must be loaded before this module:

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

Url to the database containing the routing data.

Default value is “mysql://opensipsro:opensipsro@localhost/opensips”.

...
modparam("carrierroute", "db_url", "dbdriver://username:password@dbhost/dbname")
...
		

Name of the table where the routing data is stored.

Default value is “carrierroute”.

...
modparam("carrierroute", "db_table", "carrierroute")
...
		    

Name of the column containing the id identifier.

Default value is “id”.

...
modparam("carrierroute", "id_column", "id")
...
		    

Name of the column containing the carrier id.

Default value is “carrier”.

...
modparam("carrierroute", "carrier_column", "carrier")
...
		    

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.

Default value is “scan_prefix”.

...
modparam("carrierroute", "scan_prefix_column", "scan_prefix")
...
		    

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.

Default value is “domain”.

...
modparam("carrierroute", "domain_column", "domain")
...
		    

Name of the column containing the flags.

Default value is “flags”.

...
modparam("carrierroute", "flags_column", "flags")
...
		    

Name of the column containing the flags mask.

Default value is “mask”.

...
modparam("carrierroute", "mask_column", "mask")
...
		    

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.

If all probabilities for a given prefix, tree and domain don't add to 100%, the prefix values will be adjusted according the 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.

Default value is “prob”.

...
modparam("carrierroute", "prob_column", "prob")
...
		    

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.

Default value is “rewrite_host”.

...
modparam("carrierroute", "rewrite_host_column", "rewrite_host")
...
		    

Name of the column containing the number of digits to be stripped of the userpart of an URI before prepending rewrite_prefix.

Default value is “strip”.

...
modparam("carrierroute", "strip_column", "strip")
...
		    

Name of the column containing an optional comment (useful in large routing tables) The comment is also displayed by the fifo cmd "cr_dump_routes".

Default value is “description”.

...
modparam("carrierroute", "comment_column", "description")
...
		    

The name of the table containing the existing carriers, consisting of the ids and corresponding names.

Default value is “route_tree”.

...
modparam("carrierroute", "carrier_table", "route_tree")
...
		    

Name of column containing rewrite prefixes. Here you can define a rewrite prefix for the localpart of the SIP URI.

Default value is “rewrite_prefix”.

...
modparam("carrierroute", "rewrite_prefix_column", "rewrite_prefix")
...
		    

Name of column containing rewrite suffixes. Here you can define a rewrite suffix for the localpart of the SIP URI.

Default value is “rewrite_suffix”.

			    ...
modparam("carrierroute", "rewrite_suffix_column", "rewrite_suffix")
			    ...
		    

The name of the column in the carrier table containing the carrier id.

Default value is “id”.

...
modparam("carrierroute", "carrier_id_col", "id")
...
		    

The name of the column in the carrier table containing the carrier name.

Default value is “carrier”.

...
modparam("carrierroute", "carrier_name_col", "carrier")
...
		    

The name of the table containing the subscribers

Default value is “subscriber”.

...
modparam("carrierroute", "subscriber_table", "subscriber")
...
		    

The name of the column in the subscriber table containing the usernames.

Default value is “username”.

...
modparam("carrierroute", "subscriber_user_col", "username")
...
		    

The name of the column in the subscriber table containing the domain of the subscriber.

Default value is “domain”.

...
modparam("carrierroute", "subscriber_domain_col", "domain")
...
		    

The name of the column in the subscriber table containing the carrier id of the subscriber.

Default value is “cr_preferred_carrier”.

...
modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier")
...
		    

Specifies whether the module loads its config data from a file or from a database. Possible values are file or db.

Default value is “file”.

...
modparam("carrierroute", "config_source", "file")
...
		    

Specifies the path to the config file.

Default value is “/etc/opensips/carrierroute.conf”.

...
modparam("carrierroute", "config_file", "/etc/opensips/carrierroute.conf")
...
		    

The name of the carrier tree used per default (if the current subscriber has no preferred tree)

Default value is “default”.

...
modparam("carrierroute", "default_tree", "default")
...
		    

When using tree lookup per user, this parameter specifies whether to use the domain part for user matching or not.

Default value is “0”.

...
modparam("carrierroute", "use_domain", 0)
...
		    

This parameter defines the behaviour when using user-based tree lookup. If the user has a non-existing tree set and fallback_default is set to 1, the default tree is used. Otherwise, cr_user_rewrite_uri returns an error.

Default value is “1”.

...
modparam("carrierroute", "fallback_default", 1)
...
		    

Name of the table where the failure routing data is stored.

Default value is “carrierfailureroute”.

...
modparam("carrierroute", "db_failure_table", "carrierfailureroute")
...
		    

Name of the column containing the id identifier.

Default value is “id”.

...
modparam("carrierroute", "failure_id_column", "id")
...
		    

Name of the column containing the carrier id.

Default value is “carrier”.

...
modparam("carrierroute", "failure_carrier_column", "carrier")
...
		    

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 this, an empty prefix value of “” could be added.

Default value is “scan_prefix”.

...
modparam("carrierroute", "failure_scan_prefix_column", "scan_prefix")
...
		    

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.

Default value is “domain”.

...
modparam("carrierroute", "failure_domain_column", "domain")
...
		    

Name of the column containing the host name of the last routing destination.

Default value is “host_name”.

...
modparam("carrierroute", "failure_host_name_column", "host_name")
...
		    

Name of the column containing the reply code.

Default value is “reply_code”.

...
modparam("carrierroute", "failure_reply_code_column", "reply_code")
...
		    

Name of the column containing the flags.

Default value is “flags”.

...
modparam("carrierroute", "failure_flags_column", "flags")
...
		    

Name of the column containing the flags mask.

Default value is “mask”.

...
modparam("carrierroute", "failure_mask_column", "mask")
...
		    

Name of the column containing the next routing domain.

Default value is “next_domain”.

...
modparam("carrierroute", "failure_next_domain_column", "next_domain")
...
		    

Name of the column containing an optional comment.

Default value is “description”.

...
modparam("carrierroute", "failure_comment_column", "description")
...
		    

The number of the rows to be fetched at once from database when loading the routing data. This value can be used to tune the load time at startup. For 1MB of private memory (default) it should be below 3750. The database driver must support the fetch_result() capability.

Default value is “2000”.

...
modparam("carrierroute", "fetch_rows", 3000)
...
		    

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 of the given user to a certain carrier. The is derived from a database entry belonging to the user parameter. This mapping must be available in the table that is specified in the “subscriber_table” variable. This data is not cached in memory, that means for every execution of this function a database query will be done.

Meaning of the parameters is as follows:

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 standard crc32 algorithm to calculate the hash values.

Meaning of the parameters is as follows:

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:

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

Meaning of the parameters is as follows:

This command reloads the routing data from the data source.

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.

This command prints the route rules on the command line.

This command can replace the rewrite_host of a route rule, it is only usable in file mode. Following options are possible:

Use the "null" prefix to specify an empty prefix.

...
opensipsctl fifo cr_replace_host "-d proxy -p 49 -h proxy1 -t proxy2"
...
		

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:

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 deactivated if the host is activated again.

Use the "null" prefix to specify an empty prefix.

...
opensipsctl fifo cr_deactivate_host "-d proxy -p 49 -h proxy1"
...
		

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:

Use the "null" prefix to specify an empty prefix.

...
opensipsctl fifo cr_activate_host "-d proxy -p 49 -h proxy1"
...
		

This command adds a route rule, it is only usable in file mode. Following options are possible:

Use the "null" prefix to specify an empty prefix.

...
opensipsctl fifo cr_add_host "-d proxy -p 49 -h proxy1 -w 0.25"
...
		

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:

Use the "null" prefix to specify an empty prefix.

...
opensipsctl fifo cr_delete_host "-d proxy -p 49 -h proxy1 -w 0.25"
...
		

Before running OpenSIPS 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 opensips/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, http://www.opensips.org/html/docs/db/db-schema-devel.html. 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.

For a minimal configuration either use the config file given above, or insert some data into the tables of the module.

...
+----+---------+--------+-------------+-------+------+---------------+
| 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” prefix, and a default route for other prefixes over carrier 2 and carrier 1. The gateways for the default carrier will be 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 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.

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.

...
+----+---------+--------+---------------+------------+-------------+
| 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 available, an error will be returned from the “cr_next_domain” function. Not all table colums are show here for brevity.

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.

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

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.

...
+----+----------+
| id | carrier  |
+----+----------+
|  1 | carrier1 |
|  2 | carrier2 |
|  3 | default  |
+----+----------+
...
		

This table contains the mapping of the carrier id to actual names.

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.

...
ALTER TABLE subscriber ADD cr_preferred_carrier int(10) default NULL; 
...