Migrating Kamailio v3.0.x to v3.1.0

The structure of following DB tables that existed in v3.0.x was changed:

• dialog module
  • dialog table
    • table version is 5
    • toroute column deleted
    • toroute_name column added
• dispatcher module
  • dispatcher table
    • table version is 4
    • attrs column added
• permissions module
  • address table
    • table version is 4
    • tag column added
    • default value for column grp is 1
• lcr module
  • gw table removed
  • lcr table removed
  • lcr_gw table added
  • lcr_rule table added
  • lcr_rule_target table added

Next is the MySQL script to update tables for dialog, dispatcher and permissions modules. By using it, the existing data in these tables is not lost, just the structure is updated.

ALTER TABLE dialog DROP COLUMN toroute;
ALTER TABLE dialog ADD COLUMN toroute_name VARCHAR(32);
UPDATE version SET table_version=5 WHERE table_name='dialog';
ALTER TABLE dispatcher ADD COLUMN attrs VARCHAR(128) DEFAULT '' NOT NULL;
UPDATE version SET table_version=4 WHERE table_name='dispatcher';
ALTER TABLE address ADD COLUMN tag VARCHAR(64);
UPDATE version SET table_version=4 WHERE table_name='address';

You can migrate from old data and db structure of lcr module to new version by using migration script available at:

• http://box.openxg.com/tmp/lcr_upgrade_from_3.0.sh

If you want to do by hand or you don't have any data in lcr module tables, then next is the MySQL script to update tables for lcr module. Beware that by running the script as provided next, you will lose old data you had for lcr module since the new version requires new tables, therefore old tables are removed.

DROP TABLE gw;
DROP TABLE lcr;
DELETE FROM version WHERE table_name='gw';
DELETE FROM version WHERE table_name='lcr';
 
INSERT INTO version (table_name, table_version) values ('lcr_gw','1');
CREATE TABLE lcr_gw (
    id INT(10) UNSIGNED AUTO_INCREMENT PRIMARY KEY NOT NULL,
    lcr_id SMALLINT UNSIGNED NOT NULL,
    gw_name VARCHAR(128),
    ip_addr VARCHAR(15),
    hostname VARCHAR(64),
    port SMALLINT UNSIGNED,
    params VARCHAR(64),
    uri_scheme TINYINT UNSIGNED,
    transport TINYINT UNSIGNED,
    strip TINYINT UNSIGNED,
    tag VARCHAR(16) DEFAULT NULL,
    flags INT UNSIGNED DEFAULT 0 NOT NULL,
    defunct INT UNSIGNED DEFAULT NULL,
    CONSTRAINT lcr_id_ip_addr_port_hostname_idx UNIQUE (lcr_id, ip_addr, port, hostname)
) ENGINE=MyISAM;
 
INSERT INTO version (table_name, table_version) values ('lcr_rule_target','1');
CREATE TABLE lcr_rule_target (
    id INT(10) UNSIGNED AUTO_INCREMENT PRIMARY KEY NOT NULL,
    lcr_id SMALLINT UNSIGNED NOT NULL,
    rule_id INT UNSIGNED NOT NULL,
    gw_id INT UNSIGNED NOT NULL,
    priority TINYINT UNSIGNED NOT NULL,
    weight INT UNSIGNED DEFAULT 1 NOT NULL,
    CONSTRAINT rule_id_gw_id_idx UNIQUE (rule_id, gw_id)
) ENGINE=MyISAM;
 
CREATE INDEX lcr_id_idx ON lcr_rule_target (lcr_id);
 
INSERT INTO version (table_name, table_version) values ('lcr_rule','1');
CREATE TABLE lcr_rule (
    id INT(10) UNSIGNED AUTO_INCREMENT PRIMARY KEY NOT NULL,
    lcr_id SMALLINT UNSIGNED NOT NULL,
    prefix VARCHAR(16) DEFAULT NULL,
    from_uri VARCHAR(64) DEFAULT NULL,
    stopper INT UNSIGNED DEFAULT 0 NOT NULL,
    enabled INT UNSIGNED DEFAULT 1 NOT NULL,
    CONSTRAINT lcr_id_prefix_from_uri_idx UNIQUE (lcr_id, prefix, from_uri)
) ENGINE=MyISAM;

• module was merged into modules/auth
• RPID related functions and parameters moved to siputils
• nonce_reuse parameter removed, you have to use one_time_nonce parameter instead
• realm parameter to challenge function is mandatory, see README
• PV authentication functions were re-designed. See README of the module for new prototype and more details:
• http://kamailio.org/docs/modules/3.1.x/modules/auth.html

• the module is using now the common modules/auth module
• because of that, return codes for www_authorize() and proxy_authorize() have changed
• new values can be found at:
  • http://kamailio.org/docs/modules/stable/modules_k/auth_db.html#id2753068
• new functions www_authenticate() and proxy_authenticate() offer the same as www_authorize() and proxy_authorize(), but the have better naming suggestion as the functions actually do user password authentication
• realm parameter to auth functions is mandatory, see README

• Module is now using modules/auth api.
• Functions radius_www_authorize()/radius_proxy_authorize() now return a new negative result value -2 if there was something wrong in the request.
• Realm argument must now be always given when radius_www_authorize()/radius_proxy_authorize() functions are called.
• See http://kamailio.org/docs/modules/3.1.x/modules/auth.html for new auth module parameters.

• If configuration parameter “detect_spirals” is set (true by default), spiraling messages will be detected and not cause the creation of another dialog structure. Otherwise, the old behavior of maintaining one dialog per spiral occurrence will be maintained.
• New callback type DLGCB_SPIRALED will be executed on detection of a spiraling message (“detect_spirals” must be enabled, however).
• Changes to database: toroute column was removed, toroute_name column was added

• Changes to database: attrs column was added

• Major rewrite: lcr and gw tables have been replaced by lcr_rule, lcr_rule_target, and lcr_gw tables. Upgrade script is available as http://box.openxg.com/tmp/lcr_upgrade_from_3.0.sh.
• A rule can be specified as a “stopper” rule meaning that no shorter prefixes will be tried if “stopper” rule matches.
• A rule may be marked as “disabled”.
• Added new gateway property: URI parameters.
• Gateway IP address can be NULL, if hostname is not NULL.
• If gateway IP address is NULL, all test functions fail on that LCR instance, because for performance reasons, DNS queries are not done and test functions operate only on IP addresses.
• MI functions are not supported anymore; use RPC functions instead.

• rtpproxy functionality was removed from the nathelper module and belongs to the new rtpproxy module - see README files for both modules.

• a new column in address table to hold a tag value per record. The value is returned in peer tag avp upon address matching.

• rl_drop() was dropped (same functionality can be achieved with: append_to_reply() and sl_send_reply() - see the README file.
• module moved to modules/ratelimit

• module was merged in modules/sl

• module was merged in modules/sms

IMPORTANT - pay attention to next changes

• removed the auto-adjustment of timer parameters for too low values (in Kamailio 3.0.x, if the value was lower than 120, they were multiplied with 1000)
  • all timer parameters must be set in milisecond
    • make sure the values of fr_inv_timer, fr_timer are given in mili-seconds otherwise you get a very fast timeout
  • note that dynamic timeout values given via avps for each transaction are still in seconds
  • you can use t_set_fr(…) functions with milisecond parameters as alternative to avps.
• new parameter failure_reply_mode to control winning branch selection (reply code) for failure_route
  • if you used kamailio config, be sure you set this parameter to 3 in order to have same behavior as in 1.5.x or lower and 3.0.x
  • otherwise, see t_drop_replies() function to control the behaviour per transaction inside config file, within failure_route.

• no more different behaviour based on config compat mode in core
  • drop() action is the same all the time
    • drop a reply in onreply route
    • drop the request in onsend route