Documentation -> Migration -> Migration from 2.2.x to 2.3.0

This page has been visited 6369 times.

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

You can find the all the new additions in the 2.3.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.2.x MySQL DB to the 2.3.0 format by using the opensipsdbctl tool :

   # opensipsdbctl migrate opensips_2_2 opensips_2_3

where :

• opensips_2_2 is the existing DB name corresponding to version 2.2.x format
• opensips_2_3 is the DB name to be created for 2.3 format

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  Core

• re.subst transformation requires a double-escaping characters for { and } matching

2.2  ACC module

• extra parameter changed format; *_extra paremeter(log_extra, db_extra etc.) changed to extra_fields; before the definition was in the format of log_name=variable where the log_name is backend specific(AVPs for AAA, column names for databases etc). Now the definition for extra_values parameter includes the backend, the log_name and a tag in the following format backend: tag[->log_name][;tag->log_name]. The backend can be one of the following: log, db, aaa, evi. The tag will be used in the script to set extra values using acc_extra variable(e.g. $acc_extra(tag)=<value>). If the log_name is missing, it's name shall be considered to be the same as the tag. All *_extra_bye variable were removed, since now the extra variable is visible during the whole accounting process( if cdr accounting is used, the variable will be visible the whole dialog);
• leg parameter changed format; the modparam leg_fields definition is the same as for extra_fields. Using $acc_leg(tag) in the script will reference the last leg(the current one). A new leg can be created using acc_new_leg(). The value of the current leg can be used in the script using acc_current_leg pseudo-variable. The acc_leg script variable can be indexed both with positive values(0 is the first leg created) and negative values(-1 will get the value for the latest created leg);
• diameter support was removed from the module;

2.3  CACHEDB_LOCAL

• cache_table_size parameter was removed; in current version multiple collections can be defined, each having it's own size using cache_collections module parameter; there is a default collection which is created every time, which has a hash size of 512; if size change needed default collection has to be redefined using cache_collections

2.4  CLUSTERER

• server_id parameter renamed to current_id (same meaning)
• persistent_mode parameter removed; persistency is new required by the new topology discovery mechanism and the DB is periodically updated
• column name parameters removed:
  • clusterer_id_col
  • machine_id_col
  • failed_attempts_col
  • last_attempt_col
  • duration_col
  • no_tries_col
• column name parameters added:
  • node_id_col
  • ls_seq_no_col
  • top_seq_no_col
  • no_ping_retries_col
  • priority_col
  • sip_addr_col
  • id_col
• clusterer_set_status MI command has now only two parameters: cluster_id and status (0 - Disabled, 1 - Enabled)

2.5  DISPATCHER

• weight column type has changed from INTEGER to CHAR, to accomodate dynamically calculated weights using a communication socket (covered by the opensipsdbctl table migration)

2.6  SIPTRACE

• sip_trace function now has a new parameter in 3rd position which allows to specify the types of messages to be traced; trace attributes parameter now moved in 4th position;
• hep trace_ids must now be defined using | hep_id module parameter from proto_hep module and only the name of the id from hep module shall be used in siptrace;

2.7  PROTO_HEP

• in order to trace the HEP messages in the old style( plain text ) homer5_on module parameter must be set; now, by default, the payload of the message shall be sent in JSON format; there is also the posibility to specify the delimiter between multiple payload tokens;

2.8  REST_CLIENT

• return codes of rest_get() and rest_post() are now positive (instead of negative) when receiving a HTTP error response code. (CURLOPT_FAILONERROR is now set to 0)

2.9  SIPMSGOPSS

• replaced the removed filter_body() and strip_body() functions with the new remove_body_part() function
• replaced the outdated has_body() function (not yet removed) with the new has_body_part() function
• replace the removed add_body() function with the new add_body_part() function. IMPORTANT: add_body() was removing the existing body before adding the new one; as working with body parts (and not with the body as a whole), add_body_part() adds a new body part without removing the existing parts. So, the replicate the old behavior, you should first use remove_body_part() to remove the existing part.

2.10  RTPPROXY

• The deprecated engage_rtp_proxy, unforce_rtp_proxy, start_recording functions have been completely removed. You have to replace them in your script with rtpproxy_engage, rtpproxy_unforce and rtpproxy_start_recording.

2.11  TLS_MGM

• For all module parameters accepting a TLS domain ID in their value, the syntax was changed : "tls_dom:value" was replaced with "[tls_dom]value", to avoid any conflicts between the separator and the actual value. For example, modparam("tls_mgm", "tls_method", "dom1:tlsv1") is replaced by modparam("tls_mgm", "tls_method", "[dom1]tlsv1").
• the syntax for client_domain parameter was changed when defining name based domains from dom_id=dom_name to dom_name
• As we migrated to full DB support (no files are used anymore for TLS provisioning), the following DB-related changes need to be performed:
  • id_col module parameter was renamed as domain_col
  • the old id DB column was renamed as domain (TLS domain) and represents the domain name
  • new id column added as auto increment primary key (integer)
  • the columns certificate, private_key, ca_list and dh_params, are now holding the actual data (as BLOB) instead of keeping the path to the files; you will need to perform an LOAD_FILE('/path/to/file') on this fields in order to populate them.
  • the NOT NULL restriction was removed on the address column
  • an unique constraint was added for the (domain,type) pair of columns
  • NOTE: the DB migration does not copy any records for this table.

2.12  TM

• $bavp(name) (branch AVPs) could not be deleted until this version. Therefore, the line $bavp(name) = NULL was a NOP, resulting in an error. From this version, $bavp(name) = NULL deletes any value stored in the BAVP, similar to how AVPs work.

3.  External tool migration

3.1  PERMISSIONS

• output of the address_dump and subnet_dump MI commands with the JSON backend has been changed to allow easier parsing (see commit 5fcd7db0)