Login | Register

Documentation

Documentation -> Migration -> Migration from 2.4.x to 3.0.0

This page has been visited 14012 times.


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.

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!


1.  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 that the migration tool is available only for MYSQL databases!

NOTE that the default MySQL DB engine is now InnoDB!

Back to Table of Contents


2.  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):

2.1  Global Parameters

  • 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

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

2.3  AUTH_AAA module

2.4  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

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

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

2.7  DIALOG module

2.8  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)

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

2.10  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)

2.11  ENUM module

2.12  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");
}

2.13  LOAD_BALANCER module

2.14  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

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

2.16  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)

2.17  PRESENCE module

2.18  REST_CLIENT module

2.19  SIPMSGOPS module

2.20  SIPCAPTURE module

2.21  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

2.22  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

2.23  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")

2.24  UAC_REDIRECT module

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

2.25  URI module (dropped)


Page last modified on May 04, 2021, at 11:48 AM