Migration from 2.4.x to 3.0.0

This section is meant to provide useful help in migrating your OpenSIPS installations from the 2.4.0 version to 3.0.0.

You can find the all the new additions in the 3.0.0 release compiled under this page. The ChangeLog may help your understanding of the migration / update process.

Danger

Make sure you don’t have any Makefile.conf files in your sources’ root before starting the migration. The configuration file generated by ‘menuconfig is not compatible with the one in older version!

---

DB migration

You can migrate your 2.4.x MySQL DB to the 3.0.x format by using the opensips-cli tool :

   $ opensips-cli -x database migrate 2.4_to_3.0 opensips_2_4 opensips_3_0

where :

• opensips_2_4 is the existing DB name corresponding to version 2.4.x format
• opensips_3_0 is the DB name to be created for 3.0.x format

See the opensips-cli documentation for more details.

Note

• the old database will not be deleted, altered or changed - it will not be touched at all
• new database will be created and data from old DB will be imported into it

Note

The migration tool is available only for MYSQL databases!

Note

The default MySQL DB engine is now InnoDB!

---

Script migration

The following is the full list of backwards-incompatible syntax or functional changes in the OpenSIPS configuration script (some of them are fixes):

Global Parameters

Danger

Due to the newly introduced xlog_level global parameter (default value: L_NOTICE (2)), you may need to set an xlog_level = 3 value before any of your xlog(“L_INFO”, …) statements can work as before.

• the children parameter is replaced by udp_workers parameter. The old name is marked as obsolete, but it still can be used (it will be effectively removed in the next release)

• the tcp_children parameter is replaced by tcp_workers parameter. The old name is marked as obsolete, but it still can be used (it will be effectively removed in the next release)

• the use_children option inside the listen parameter is replaced by use_workers. The old name is marked as obsolete, but it still can be used (it will be effectively removed in the next release)

• global parameter xlog_default_level was renamed as xlog_print_level, with no change in its behavior

Module functions

Remove quotes

As a result of the enhancement of the interface for module functions (for generic support of script variables in the parameters), some parameters will have be passed without quotes (like if they are numerical values or returning variables).

For example:

 send_reply( "200", "OK");

is now

 send_reply( 200, "OK");

as the first parameter requires a numerical value.

Also :

 check_source_address( "4", "$avp(ctx)");

is now

 check_source_address( 4, $avp(ctx));

as the first parameter requires a numerical value and the second one requires a returning variable.

Escape ”$” characters in plain-text strings

Since all OpenSIPS strings which get passed to functions have become format strings in 3.0, each singular ”$” sign must be escaped using its ”$$” form, otherwise the parser will expect a variable over there!

For example:

avp_subst("$avp(sdp_ip)", "/^c=IN IP[46] (.*)$/\1/");

becomes:

avp_subst("$avp(sdp_ip)", "/^c=IN IP[46] (.*)$$/\1/");

Other function-related issues

There are many changes as the ones listed above. IF during the startup, while the config file is parsed to get an error like:

 ERROR:core:fix_cmd: Param [n] expected to be an integer or variable
 ERROR:core:fix_actions: Failed to fix command <name_of_function>

it means the n-th parameter of the module function name_of_function changed from string type to integer or variable type.

To do the translation to the right type of parameter, check the documentation of faulty function - there you can find the required type for each parameter. If you have doubts how to pass the certain parameters (depending on their type), please check this documentation.

AUTH_AAA module

• the service_type module parameter was renamed as auth_service_type with the same meaning and values.

AVPOPS module

• avp_insert() was dropped in favour of the equivalent, already existing syntax: $(avp(foo)[append]) = “bar”; (for appending to end-of-list) and $(avp(foo)[3]) = “bar”; (for writing at a specific AVP index)
• buf_size query printing buffer was removed in favour of the new generic format string buffer setting, pv_print_buf_size

DB_MYSQL module

• the tls_client_domain module parameter was removed in favor of a new way of enabling TLS for specific MySQL connections via the DB URL.

CLUSTERER module

• the current_id, current_info and neighbor_info module parameters were renamed to my_node_id, my_node_info and neighbor_node_info respectively.

DIALOG module

• the functionality of the old module parameter dlg_sharing_tag is now provided via the clusterer module parameter sharing_tag - note that the syntax is slightly different, refer to docs.
• the functionality of the old MI function dlg_set_sharing_tag_active is now provided via the clusterer module MI function mi_clusterer_shtag_set_active
• the functionality of the old MI function dlg_list_sharing_tags is now provided via the clusterer module MI function mi_clusterer_list_shtags

DIALPLAN module

• dp_translate() parameters have been reworked to be more clear:
  • the composite “partition:id” parameter was split into “id” (mandatory) and “partition” (optional)
  • the composite “src/dest” parameter was split into “input” (mandatory) and “out_var” (optional)

DISPATCHER module

• ds_select_dst() parameters have been reworked to be easier to understand and maintain. Specifically:
  • the “s” (skip destination) flag was dropped (equivalent logic: “$du == NULL && ds_select_dst()”)
  • the “a” (append destination) flag was added, replacing all the complex set / algorithm / flags list-parameter logic in favour of simply calling ds_select_dst() multiple times.
  • the “set” composite parameter was decoupled into two basic parameters: “set” (mandatory) and “partition” (optional)
• ds_select_domain() parameters have been reworked to be easier to understand and maintain. The changes follow the same pattern as ds_select_dst().
• ds_count()‘s complex “set” parameter has been split in two simple parameters: “set” (mandatory) and “partition” (optional).
• ds_is_in_list()‘s complex “set” parameter has been split in two simple parameters: “set” (mandatory) and “partition” (optional).

DROUTING module

• the old module parameter status_replication_cluster was renamed as cluster_id.
• do_routing()‘s composite “[partition:]group_id” parameter has been split in two parameters: “group_id” (mandatory) and “partition” (optional)
• route_to_carrier()‘s composite “[partition:]carrier_id” parameter has been split in two parameters: “carriers” (mandatory) and “partition” (optional)
• route_to_gw()‘s composite “[partition:]gw_id” parameter has been split in two parameters: “gw_id” CSV (mandatory) and “partition” (optional)
• use_next_gw()‘s parameter order has been changed for consistency reasons (“partition” is last now)
• goes_to_gw()‘s parameter order has been changed for consistency reasons (“partition” is last now)
• is_from_gw()‘s parameter order has been changed for consistency reasons (“partition” is last now)
• dr_is_gw()‘s parameter order has been changed for consistency reasons (“partition” is last now)

ENUM module

• enum_pv_query() has been merged into enum_query()

EVENT_ROUTE module

• fetch_event_params() function has been completely dropped - in order to fetch the parameters of an event, you will have to use the $params(name) variable in the route. As an example, the following snippets have the same meaning in the two different versions:

# route used in OpenSIPS 2.4
event_route[E_PIKE_BLOCKED] {
  fetch_event_params("ip=$avp(pike-ip)");
  xlog("IP $avp(pike-ip) has been blocked\n");
}

# route used in OpenSIPS 3.0
event_route[E_PIKE_BLOCKED] {
  xlog("IP $param(ip) has been blocked\n");
}

LOAD_BALANCER module

• the old module parameter status_replication_cluster was renamed as cluster_id.

MI_HTTP module

• the mi_http module has been renamed to mi_html module. you have to replace your modparam("mi_http"... lines with modparam("mi_html"... lines

MI_JSON module

• the mi_json module has been renamed to mi_http module. you have to replace your modparam("mi_json"... lines with modparam("mi_http"... lines
• as the protocol for MI interaction has been shifted to JSON-RPC, you must now use POST instead of GET as HTTP request method.

PERMISSIONS module

• check_address()‘s composite “[partition:]group_id” parameter has been split in two parameters: “group_id” (mandatory) and “partition” (optional)
• check_source_address()‘s composite “[partition:]group_id” parameter has been split in two parameters: “group_id” (mandatory) and “partition” (optional)
• get_source_group()‘s composite “[partition:]var” parameter has been split in two parameters: “var” (mandatory) and “partition” (optional)

PRESENCE module

• the functionality of the old module parameter cluster_sharing_tags is now provided via the clusterer module parameter sharing_tag - note that the syntax is slightly different, refer to docs.
• the functionality of the old MI function pres_set_sharing_tag_active is now provided via the clusterer module MI function mi_clusterer_shtag_set_active
• the functionality of the old MI function pres_list_sharing_tags is now provided via the clusterer module MI function mi_clusterer_list_shtags

REST_CLIENT module

• The parameter of the rest_init_client_tls function now only takes the TLS domain name.
• extensive return codes for rest_get(), rest_post() and rest_put()

SIPMSGOPS module

• remove_hf() was split into remove_hf(), remove_hf_re() and remove_hf_glob(). As a result, the “flags” parameter was dropped.

SIPCAPTURE module

• report_capture() parameter order has changed
• hep_set() parameter order has changed
• hep_get() parameter order has changed

SIPTRACE module

• the siptrace module has been renamed to tracer module. you have to replace your modparam("siptrace"... lines with modparam("tracer"... lines
• function sip_trace() was renamed in the new module to trace()
• MI function sip_trace was renamed in the new module to trace

TLS_MGM module

• the address column from the tls_mgm table was removed and the TLS domain matching is now driven by two new columns: match_ip_address and match_sip_domain
• the syntax for the server_domain and client_domain parameters now only accepts the TLS domain name
• the client_domain_avp module parameter was renamed to client_tls_domain_avp

UAC module

• the “uac_replace_xxx()” functions requires now 2 parameters (display and URI), where the first one may be optional. Instead of uac_replace_from(“URI”), simply use uac_replace_from( , “URI”)

UAC_REDIRECT module

• get_redirects() -> the deprecated “reason” parameter, along with the accounting logic behind it have been completely dropped

URI module (dropped)

• function has_totag() was moved in SIPMSGOPS module under the same name.
• function is_user() was removed, it can simply be replaced with the script test $au==$var(my_username).
• function uri_param() was moved in SIPMSGOPS module under the ruri_has_param() name.
• function add_uri_param() was moved in SIPMSGOPS module under the ruri_add_param() name.
• function del_uri_param() was moved in SIPMSGOPS module under the ruri_del_param() name.
• function tel2sip() was moved in SIPMSGOPS module under the ruri_tel2sip() name.
• function is_uri_user_e164() was moved in SIPMSGOPS module under the same name.
• function db_check_to() was replaced by the AUTH_DB module with:
  • if use_uri_table was set, use db_is_to_authorized(“uri”)
  • if use_uri_table was not set, imply replace it with the $au==$tU script test.
• function db_check_from() was replaced by the AUTH_DB module with:
  • if use_uri_table was set, use db_is_from_authorized(“uri”)
  • if use_uri_table was not set, simply replace it with the $au==$fU script test.
• function db_does_uri_exist() was replaced by the AUTH_DB module with:
  • if use_uri_table was not set, use db_does_uri_exist(“$ru”,“subscriber”)
  • if use_uri_table was set (very unlikely setup), you can still achieve it by use db_get_auth_id(“uri”,“$ru”,“$avp(auser)”,“$avp(arealm)”)
• function db_get_auth_id() was moved in AUTH_DB module under the same name but an extra first parameter set to “uri” value, like db_get_auth_id(“uri”,…).
• the parameter user_column was moved in AUTH_DB module under the uri_user_column name.
• the parameter domain_column was moved in AUTH_DB module under the uri_domain_column name.
• the parameter uriuser_column was moved in AUTH_DB module under the uri_uriuser_column name.
• the service_type module parameter was moved to URI module as check_service_type with the same meaning and values.
• function aaa_does_uri_exist() was moved to the AUTH_AAA module under the same name and behavior.
• function aaa_does_uri_user_exist() was moved to the AUTH_AAA module under the same name and behavior.