Migration from 3.6.x to 4.0.x

This section is meant to provide useful help in migrating your OpenSIPS installations from the 3.6.x version to 4.0.x.

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

Danger

Make sure you don’t carry a left-over Makefile.conf file in your OpenSIPS source tree if migrating to a new branch! This configuration file, generated by make menuconfig, is usually not compatible with the one of a previous major release!

---

DB migration

You can migrate your 3.6.x MySQL DB to the 4.0.x format using the opensips-cli tool :

   $ opensips-cli -x database migrate 3.6_to_4.0 opensips_3_6 opensips_4_0

where :

• opensips_3_6 is the existing DB name corresponding to version 3.6.x format
• opensips_4_0 is the DB name to be created for 4.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

---

MI naming logic

• Canonical format: all MI commands are exported as module:command.
• Legacy names: old MI names are kept as aliases where available.
• Unqualified call: calling only command works only if the name is unambiguous.
• Ambiguous call: ambiguous unqualified calls fail with JSON-RPC code -32001 (Method ambiguous).
• Alias limit: each MI command can define up to 4 aliases.
• Group listing: which command=module: lists all commands from that module/group.

MI commands not listed in the table keep the same local command name and are migrated by prefixing it with the owning MI group, using the group:command format. For example, trace becomes tracer:trace and address_reload becomes permissions:address_reload. Protocol modules use the protocol name as MI group, without the proto_ prefix, so proto_ws exports ws:*, proto_tls exports tls:*, etc.

The following table summarizes the MI function migration changes:

Module	Old MI function	New MI function
core	add_blacklist_rule	blacklists:add_rule
core	cache_fetch	cache:fetch
core	cache_remove	cache:remove
core	cache_store	cache:store
core	check_blacklist	blacklists:check
core	check_blacklists	blacklists:check_all
core	del_blacklist_rule	blacklists:del_rule
core	event_subscribe	evi:subscribe
core	events_list	evi:list
core	get_statistics	statistics:get
core	list_blacklists	blacklists:list
core	list_statistics	statistics:list
core	list_tcp_conns	tcp:list
core	mem_pkg_dump	mem:pkg_dump
core	mem_rpm_dump	mem:rpm_dump
core	mem_shm_check	mem:shm_check
core	mem_shm_dump	mem:shm_dump
core	raise_event	evi:raise
core	reset_all_statistics	statistics:reset_all
core	reset_statistics	statistics:reset
core	sr_get_status	status_report:get
core	sr_list_identifiers	status_report:identifiers
core	sr_list_reports	status_report:reports
core	sr_list_status	status_report:status
core	subscribers_list	evi:subscribers
auth_aka	aka_av_add	auth_aka:av_add
auth_aka	aka_av_drop	auth_aka:av_drop
auth_aka	aka_av_drop_all	auth_aka:av_drop_all
auth_aka	aka_av_fail	auth_aka:av_fail
b2b_entities	b2be_list	b2b_entities:list
b2b_entities	ua_session_client_start	b2b_entities:ua_session_client_start
b2b_entities	ua_session_list	b2b_entities:ua_session_list
b2b_entities	ua_session_reply	b2b_entities:ua_session_reply
b2b_entities	ua_session_terminate	b2b_entities:ua_session_terminate
b2b_entities	ua_session_update	b2b_entities:ua_session_update
b2b_logic	b2b_bridge	b2b_logic:bridge
b2b_logic	b2b_list	b2b_logic:list
b2b_logic	b2b_terminate_call	b2b_logic:terminate_call
b2b_logic	b2b_trigger_scenario	b2b_logic:trigger_scenario
b2b_sca	sca_list	b2b_sca:list
benchmark	bm_enable_global	benchmark:enable_global
benchmark	bm_enable_timer	benchmark:enable_timer
benchmark	bm_granularity	benchmark:granularity
benchmark	bm_loglevel	benchmark:loglevel
benchmark	bm_poll_results	benchmark:poll_results
bins	tls_trace	bins:trace
cachedb_local	cache_fetch_chunk	cachedb_local:fetch_chunk
cachedb_local	cache_remove_chunk	cachedb_local:remove_chunk
call_center	cc_agent_login	call_center:agent_login
call_center	cc_dispatch_call_to_agent	call_center:dispatch_call_to_agent
call_center	cc_internal_call_dispatching	call_center:internal_call_dispatching
call_center	cc_list_agents	call_center:list_agents
call_center	cc_list_calls	call_center:list_calls
call_center	cc_list_flows	call_center:list_flows
call_center	cc_list_queue	call_center:list_queue
call_center	cc_reload	call_center:reload
call_center	cc_reset_stats	call_center:reset_stats
callops	call_hold	callops:hold
callops	call_transfer	callops:transfer
callops	call_unhold	callops:unhold
carrierroute	cr_activate_host	carrierroute:activate_host
carrierroute	cr_add_host	carrierroute:add_host
carrierroute	cr_deactivate_host	carrierroute:deactivate_host
carrierroute	cr_delete_host	carrierroute:delete_host
carrierroute	cr_dump_routes	carrierroute:dump_routes
carrierroute	cr_reload_routes	carrierroute:reload_routes
carrierroute	cr_replace_host	carrierroute:replace_host
clusterer	cluster_broadcast_mi	clusterer:broadcast_mi
clusterer	cluster_send_mi	clusterer:send_mi
clusterer	clusterer_list	clusterer:list
clusterer	clusterer_list_cap	clusterer:list_cap
clusterer	clusterer_list_shtags	clusterer:list_shtags
clusterer	clusterer_list_topology	clusterer:list_topology
clusterer	clusterer_reload	clusterer:reload
clusterer	clusterer_remove_node	clusterer:remove_node
clusterer	clusterer_set_cap_status	clusterer:set_cap_status
clusterer	clusterer_set_status	clusterer:set_status
clusterer	clusterer_shtag_set_active	clusterer:shtag_set_active
config	config_flush	config:flush
config	config_list	config:list
config	config_push	config:push
config	config_push_bulk	config:push_bulk
config	config_reload	config:reload
cfgutils	check_config_hash	cfgutils:check_config_hash
cfgutils	get_config_hash	cfgutils:get_config_hash
cfgutils	rand_get_prob	cfgutils:rand_get_prob
cfgutils	rand_reset_prob	cfgutils:rand_reset_prob
cfgutils	rand_set_prob	cfgutils:rand_set_prob
cfgutils	shv_get	cfgutils:shv_get
cfgutils	shv_set	cfgutils:shv_set
cpl_c	GET_CPL	cpl_c:get
cpl_c	LOAD_CPL	cpl_c:load
cpl_c	REMOVE_CPL	cpl_c:remove
db_berkeley	bdb_reload	db_berkeley:reload
db_flatstore	flat_rotate	db_flatstore:rotate
db_text	dbt_dump	db_text:dump
db_text	dbt_reload	db_text:reload
db_virtual	db_get	db_virtual:get
db_virtual	db_set	db_virtual:set
dialog	dlg_cluster_sync	dialog:cluster_sync
dialog	dlg_db_sync	dialog:db_sync
dialog	dlg_end_dlg	dialog:end_dlg
dialog	dlg_list	dialog:list
dialog	dlg_list_ctx	dialog:list_ctx
dialog	dlg_push_var	dialog:push_var
dialog	dlg_restore_db	dialog:restore_db
dialog	dlg_send_sequential	dialog:send_sequential
dialog	dlg_set_profile	dialog:set_profile
dialog	dlg_unset_profile	dialog:unset_profile
dialog	list_all_profiles	dialog:list_all_profiles
dialog	profile_end_dlgs	dialog:profile_end_dlgs
dialog	profile_get_size	dialog:profile_get_size
dialog	profile_get_values	dialog:profile_get_values
dialog	profile_list_dlgs	dialog:profile_list_dlgs
dialog	set_dlg_profile	dialog:set_profile
dialog	unset_dlg_profile	dialog:unset_profile
dialplan	dp_reload	dialplan:reload
dialplan	dp_show_partition	dialplan:show_partition
dialplan	dp_translate	dialplan:translate
dispatcher	ds_list	dispatcher:list
dispatcher	ds_push_script_attrs	dispatcher:push_script_attrs
dispatcher	ds_reload	dispatcher:reload
dispatcher	ds_set_state	dispatcher:set_state
domain	domain_dump	domain:dump
domain	domain_reload	domain:reload
drouting	dr_carrier_status	drouting:carrier_status
drouting	dr_enable_probing	drouting:enable_probing
drouting	dr_gw_status	drouting:gw_status
drouting	dr_number_routing	drouting:number_routing
drouting	dr_reload	drouting:reload
drouting	dr_reload_status	drouting:reload_status
event_flatstore	evi_flat_rotate	event_flatstore:rotate
fraud_detection	fraud_reload	fraud_detection:reload
fraud_detection	show_fraud_stats	fraud_detection:show_stats
freeswitch_scripting	fs_list	freeswitch_scripting:list
freeswitch_scripting	fs_reload	freeswitch_scripting:reload
freeswitch_scripting	fs_subscribe	freeswitch_scripting:subscribe
freeswitch_scripting	fs_unsubscribe	freeswitch_scripting:unsubscribe
gflags	get_gflags	gflags:get
gflags	is_gflag	gflags:check
gflags	reset_gflag	gflags:reset
gflags	set_gflag	gflags:set
httpd	httpd_list_root_path	httpd:list_root_path
imc	imc_list_members	imc:list_members
imc	imc_list_rooms	imc:list_rooms
load_balancer	lb_list	load_balancer:list
load_balancer	lb_reload	load_balancer:reload
load_balancer	lb_resize	load_balancer:resize
load_balancer	lb_status	load_balancer:status
lua	watch	lua:watch
media_exchange	media_exchange_from_call_to_uri	media_exchange:from_call_to_uri
media_exchange	media_exchange_from_call_to_uri_body	media_exchange:from_call_to_uri_body
media_exchange	media_fork_from_call_to_uri	media_exchange:fork_from_call_to_uri
media_exchange	media_terminate	media_exchange:terminate
mqueue	mq_fetch	mqueue:fetch
mqueue	mq_get_size	mqueue:get_size
mqueue	mq_get_sizes	mqueue:get_sizes
msrp	msrp_trace	msrp:trace
msrp_gateway	msrp_gw_end_session	msrp_gateway:end_session
msrp_gateway	msrp_gw_list_sessions	msrp_gateway:list_sessions
msrp_ua	msrp_ua_end_session	msrp_ua:end_session
msrp_ua	msrp_ua_list_sessions	msrp_ua:list_sessions
msrp_ua	msrp_ua_send_message	msrp_ua:send_message
msrp_ua	msrp_ua_start_session	msrp_ua:start_session
nathelper	nh_enable_ping	nathelper:enable_ping
opentelemetry	otel_enable	opentelemetry:enable
permissions	address_dump	permissions:address_dump
permissions	address_reload	permissions:address_reload
permissions	allow_uri	permissions:allow_uri
permissions	subnet_dump	permissions:subnet_dump
pi_http	pi_reload_tbls_and_cmds	pi_http:reload_tbls_and_cmds
pike	pike_list	pike:list
pike	pike_rm	pike:rm
presence	cleanup	presence:cleanup
presence	pres_expose	presence:expose
presence	pres_phtable_list	presence:phtable_list
presence	refreshWatchers	presence:refresh_watchers
presence	subs_phtable_list	presence:subs_phtable_list
presence_dfks	dfks_set_feature	presence_dfks:set_feature
pua_mi	pua_publish	pua_mi:publish
pua_mi	pua_subscribe	pua_mi:subscribe
qrouting	qr_disable_dst	qrouting:disable_dst
qrouting	qr_enable_dst	qrouting:enable_dst
qrouting	qr_reload	qrouting:reload
qrouting	qr_status	qrouting:status
rate_cacher	rc_addClient	rate_cacher:addClient
rate_cacher	rc_addVendor	rate_cacher:addVendor
rate_cacher	rc_deleteClient	rate_cacher:deleteClient
rate_cacher	rc_deleteClientRate	rate_cacher:deleteClientRate
rate_cacher	rc_deleteVendor	rate_cacher:deleteVendor
rate_cacher	rc_deleteVendorRate	rate_cacher:deleteVendorRate
rate_cacher	rc_getClientPrice	rate_cacher:getClientPrice
rate_cacher	rc_getVendorPrice	rate_cacher:getVendorPrice
rate_cacher	rc_reloadClientRate	rate_cacher:reloadClientRate
rate_cacher	rc_reloadVendorRate	rate_cacher:reloadVendorRate
ratelimit	rl_dump_pipe	ratelimit:dump_pipe
ratelimit	rl_get_pid	ratelimit:get_pid
ratelimit	rl_list	ratelimit:list
ratelimit	rl_reset_pipe	ratelimit:reset_pipe
ratelimit	rl_set_pid	ratelimit:set_pid
regex	regex_match	regex:match
regex	regex_match_group	regex:match_group
regex	regex_reload	regex:reload
rls	rls_update_subscriptions	rls:update_subscriptions
rtp_relay	rtp_relay_list	rtp_relay:list
rtp_relay	rtp_relay_update	rtp_relay:update
rtp_relay	rtp_relay_update_callid	rtp_relay:update_callid
rtpengine	teardown	rtpengine:teardown
rtpengine	rtpengine_enable	rtpengine:enable
rtpengine	rtpengine_reload	rtpengine:reload
rtpengine	rtpengine_show	rtpengine:show
rtpproxy	rtpproxy_enable	rtpproxy:enable
rtpproxy	rtpproxy_reload	rtpproxy:reload
rtpproxy	rtpproxy_show	rtpproxy:show
sipcapture	sip_capture	sipcapture:capture
sockets_mgm	sockets_list	sockets_mgm:list
sockets_mgm	sockets_reload	sockets_mgm:reload
sql_cacher	sql_cacher_reload	sql_cacher:reload
stir_shaken	stir_shaken_ca_reload	stir_shaken:ca_reload
stir_shaken	stir_shaken_crl_reload	stir_shaken:crl_reload
tcp	tcp_trace	tcp:trace
tcp_mgm	tcp_reload	tcp_mgm:reload
tls	tls_trace	tls:trace
tls_mgm	tls_list	tls_mgm:list
tls_mgm	tls_reload	tls_mgm:reload
tm	t_hash	tm:hash
tm	t_reply	tm:reply
tm	t_uac_cancel	tm:uac_cancel
tm	t_uac_dlg	tm:uac_dlg
tracer	trace	tracer:trace
tracer	trace_start	tracer:start
tracer	trace_stop	tracer:stop
trie	trie_number_delete	trie:number_delete
trie	trie_number_upsert	trie:number_upsert
trie	trie_reload	trie:reload
trie	trie_reload_status	trie:reload_status
trie	trie_search	trie:search
uac_registrant	reg_delete	uac_registrant:delete
uac_registrant	reg_disable	uac_registrant:disable
uac_registrant	reg_enable	uac_registrant:enable
uac_registrant	reg_force_register	uac_registrant:force_register
uac_registrant	reg_list	uac_registrant:list
uac_registrant	reg_reload	uac_registrant:reload
uac_registrant	reg_upsert	uac_registrant:upsert
userblacklist	reload_blacklist	userblacklist:reload
usrloc	ul_add	usrloc:add
usrloc	ul_cluster_sync	usrloc:cluster_sync
usrloc	ul_dump	usrloc:dump
usrloc	ul_flush	usrloc:flush
usrloc	ul_rm	usrloc:rm
usrloc	ul_rm_contact	usrloc:rm_contact
usrloc	ul_show_contact	usrloc:show_contact
usrloc	ul_sync	usrloc:sync
ws	ws_trace	ws:trace
wss	wss_trace	wss:trace
xcap_client	refreshXcapDoc	xcap_client:refreshXcapDoc

Script migration

The following is the full list of backwards-incompatible syntax or functional changes in the OpenSIPS configuration script:

• none

Global Parameters

• The log_stderror parameter has been completely dropped, use stderror_enabled and/or syslog_enabled instead
• The log_facility parameter has been completely dropped, use syslog_facility instead
• The log_name parameter has been completely dropped, use syslog_name instead
• The listen parameter has been completely dropped, use socket instead
• The tcp_parallel_read_on_workers parameter has been completely dropped, as it makes no sense after the new TCP/TLS engine rework.

Core Variables

• example

Core keywords

• example

Core functions

• example

Core MI commands

• Canonical MI command format is now module:command (for example, usrloc:rm_contact, blacklists:list).
• Local (module-less) MI calls are still accepted only if the local name is unambiguous across all modules.
• Ambiguous module-less MI calls now fail with JSON-RPC custom error code -32001 (Method ambiguous) and return the supported canonical names.
• MI commands can define up to 4 aliases (typically old names kept for compatibility).
• Core command regrouping:
  • mem_* -> mem:*
  • sr_* -> status_report:* (with sr_get_status -> status_report:get)
  • event MI commands -> evi:*
  • cache MI commands -> cache:*
• The which MI command now supports module listing by suffixing the module with : (example: which command=dialog: lists all dialog MI commands).

Statistics migration

• example

Module migration

• All MI function renames are consolidated in the MI command migration table above.

AUTH_DB module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.

CARRIEROUTE module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.

CPL_C module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.

DIALOG module

• Full rework of create_dialog()‘s flag arguments, now using hyphenated, full flag names instead of single-letter names for better script readability. Make sure to update your previous flags to their 4.0 counterparts.

GROUP module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.

MI_XMLRPC_NG module

• The old MI_XMLRPC_NG module has been renamed to MI_XMLRPC - in order to migrate, replace mi_xmlrpc_ng references with mi_xmlrpc.

PROTO_BIN module

• The bin_async_local_connect_timeout parameter has been removed, as it no longer makes sense after the latest TCP/TLS rework.

PROTO_BINS module

• The bins_async_local_connect_timeout parameter has been removed, as it no longer makes sense after the latest TCP/TLS rework.

PROTO_HEP module

• The hep_async_local_connect_timeout parameter has been removed, as it no longer makes sense after the latest TCP/TLS rework.

PROTO_TCP module

• The tcp_async_local_connect_timeout parameter has been removed, as it no longer makes sense after the latest TCP/TLS rework.

PROTO_TLS module

• The tls_async_local_connect_timeout and tls_async_handshake_timeout parameters have been removed, as they no longer makes sense after the latest TCP/TLS rework.

SQLOPS module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.

USRLOC module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.
• The db_mode parameter has been dropped in favor of working_mode_preset.
• The shared_pinging parameter has been completely dropped - use pinging_mode.

USERBLACKLIST module

• New default value for use_domain (changed to: true), so either remove or add this setting as needed.