Migrating OpenSER v1.1.x to v1.2.x

This page is dedicated to the differences between versions 1.1.x and 1.2.x of OpenSER. The aim is to ease the upgrade to v1.2.x.

The debian packages of 1.2 are built by default without TLS support. To enable TLS set TLS=1 in packaging/debian/rules.

btw: Default debian packages are built for etch. If you need sarge, then rename packaging/debian into packaging/debian-etch and packaging/debian-sarge into packaging/debian.

Database structure has been updated. All tables have primary key auto incremented, previous ones are now unique keys. Many indexes were added to speed up SQL queries.

openser_mysql.sh has a new option “migrate” to migrate the content of OpenSER database from the structure required by 1.1.x to 1.2.x. It is a safer mode, the data from old database cannot be lost (however, as always, it is recommended to backup critical data).

openser_mysqldb.sh migrate <old_db> <new_db>

More details:

[http://openser.org/pipermail/users/2007-February/009415.html]

- using the new management interface (MI) old FIFO implementation has moved as module (new alternative to mi_fifo is mi_xmlrpc – XMLRPC transport for MI).

- all FIFO-related global parameters are now parameters of mi_fifo module: MI_FIFO Readme

- 1.1.x version of:

fifo="/tmp/fifo"

goes in 1.2.x as:

mpath="/usr/local/openser/lib/modules/"
loadmodule "mi_fifo.so"

modparam("mi_fifo","fifo_name", "/tmp/openser_fifo")

The “fifo_db_url” and FIFO DB interface were removed.

The old flags were specific per transaction. With the new version there are:

- transaction flags

* the flags persist as long as the transaction is in memory (same as old flags) * functions to manage these flags: setflag(), isflagset(), resetflag()

- branch flags

* these flags are specific per each branch of a transaction. These flags have to be used now for NAT traversal, as opposite of transaction flags used in the past * functions to manage these flags: setbflag(), isbflagset(), resetbflag()

- script flags

* these flags are not tied to a SIP message, they persist as long as it takes interpretation of routing blocks. They can be used to keep state of message routing processing. * functions to manage these flags: setsflag(), issflagset(), resetsflag()

See OpenSER Core Cookbook and OpenSER Flags Description for function prototypes and documentation.

retcode core keyword has been removed. The replacement is the pseudo-variable $retcode (or $rc if you prefer shorter version).

Example v1.1.x:

switch(retcode) {
   case 1:
     xlog("returned code was 1\n");
   break;
   default:
     xlog("returned code different than 1\n")
}

Example v1.2.x:

switch($retcode) {
   case 1:
     xlog("returned code was 1\n");
   break;
   default:
     xlog("returned code different than 1\n")
}

There is a new feature to turn off the aliases which are automatically generated with reverse DNS lookups. For more details refer to http://openser.org/dokuwiki/doku.php/core-cookbook:1.2.x#auto_aliases

For many modules the AVP parameters must be given now in full AVP name format “$avp(name)”. Check the README of the module if you get errors.

[http://www.openser.org/docs/modules/1.2.x/]

The acc module was restructured so it records only basic details of an event. You have to use log_extra/db_extra/radius_extra parameter to log more accounting information.

If you want to store source username and domain (caller), plus destination username and domain (callee), you have to add extra colums in table acc (as well as missed_calls table). The new structure of table acc is shown in the next SQL statement.

CREATE TABLE `acc` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `method` varchar(16) NOT NULL default '',
  `from_tag` varchar(64) NOT NULL default '',
  `to_tag` varchar(64) NOT NULL default '',
  `callid` varchar(128) NOT NULL default '',
  `sip_code` char(3) NOT NULL default '',
  `sip_reason` varchar(32) NOT NULL default '',
  `time` datetime NOT NULL default '0000-00-00 00:00:00',
  `dst_user` varchar(64) NOT NULL default '',
  `dst_domain` varchar(128) NOT NULL default '',
  `src_user` varchar(64) NOT NULL default '',
  `src_domain` varchar(128) NOT NULL default '',
  PRIMARY KEY  (`id`),
  KEY `acc_callid` (`callid`)
);

The parameters of acc module will look like:

modparam("acc", "log_extra", "src_user=$fU;src_domain=$fd;dst_user=$rU;dst_domain=$rd")
modparam("acc", "db_extra", "src_user=$fU;src_domain=$fd;dst_user=$rU;dst_domain=$rd")

* rpid_avp parameter value must be full AVP spec name * load credentials must contain full AVP spec names

* avpops functions can be used in onreply routes. Default onreply_route will get access to SIP message AVPs, while onreply_route armed by TM module can get access to transaction AVPs if TM module instructed to do so via onreply_avp_mode parameter (http://www.openser.org/docs/modules/1.2.x/tm.html#AEN303).

* avp_aliases was moved to core

- 1.1.x version of:

modparam("avpops", "avp_aliases", "uuid=I:660;email=s:email_addr;fwd=i:753")

goes in 1.2.x (in global parameter section) as:

avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753"

* avp_write() has been removed, being replaced by assignment operation in configuration file

# format in 1.1.x                  =>  format in 1.2.x

avp_write("i:22", "$avp(i:123)");  =>  $avp(i:123) = 22;

avp_write("s:22", "$avp(i:123)");  =>  $avp(i:123) = "22";

* nat_flag module parameter removed as now it is automatically imported from USRLOC module

* dst_avp_id, grp_avp_id, cnt_avp_id renamed in dst_avp, grp_avp, cnt_avp * the parameters take now full AVP spec name as value

* format of the parameter for function m_store() has changed m_store(“0”) goes in m_store() or m_store(“$ru”) – see [http://www.openser.org/docs/modules/1.2.x/msilo.html#AEN319] * snd_time_avp get's now full AVP spec name as value ==== nathelper ==== * new module parameter sipping_bflag - the branch flag that mark the contacts that needs ping via SIP request. As the flag was moved into branch flags (from messages flags - as in 1.1.x) as a custom flag, its definition was moved from registrar to nathelper module - only nathelper needs now to know exactly the flag value to identify the marked contacts (marking is done from script, at registration time via setbflag() ). * reveived_avp parameter takes full AVP spec name as value ==== registrar ==== * nat_flag module parameter removed as now it is automatically imported from USRLOC module * use_branch_flags module parameter removed as now the nat flag is all the time pushed into branch flags * sip_natping_flag module parameter removed as now the sip ping flag was moved into branch flags (which are automatically saved and restored by usrloc) and only nathelper module needs to know its value (see nathelper module also) * the registrar module must be loaded after usrloc module, because of importing some parameter values * AVP parameters of registrar module take full AVP name spec as value * use_domain parameter is not longer used ==== siptrace ==== - AVPs parameters take now full AVP spec name as value ==== tm ==== * fr_timer_avp and fr_inv_timer_avp are default NULL (you have to set the value for them if you want dynamic timer values) * fr_timer_avp and fr_inv_timer_avp parameter values must be given in full PV format <code> # sample as in 1.1.x modparam(“tm”, “fr_inv_timer_avp”, “i:25”) # in 1.2.x must be modparam(“tm”, “fr_inv_timer_avp”, “$avp(i:25)”) </code> ==== usrloc ==== * new module parameter nat_bflag - the branch/contact NAT flags are saved in USRLOC records. The value is used by all other modules that had parameter nat_flag in v1.1.x. * because usrloc exports values in API, it must be loaded before registrar** or any other module that uses the API

* if you have installed serweb tables/columns, you have to enable HAS_SERWEB in 'openserctlrc' (default path when installed from source is /usr/local/etc/openser/openserctlrc). Common error one gets in this case is “ERROR: Duplicate entry”.

## presence of serweb tables - default "no"
HAS_SERWEB="yes" 

* if you want to store the plain text password in database, then add following lines in your 'openserctlrc':

STORE_PLAINTEXT_PW=1

Stuff that should concern the developers.

• struct module_exports has changed

The branch flags have to be used now for NAT traversal. See OpenSER Flags Description.

..........
# branch flags:
# 3 - the nat flag 
# 5 - the sip ping flag
modparam("usrloc","nat_bflag",3)
modparam("nathelper","sipping_bflag",5)
..........

route {
    ..........
    if (nat detected) {
       setbflag(3); # set branch flag 3 for the branch 0
       if (I+want+sip+ping)
           setbflag(5);
    }

    ..........
    if (is_method("REGISTER")) {
       # the branch flags (including 3 and 5) will be saved into location
       save("location");
       exit;
    } else {
       # lookup will load the branch flag from location
       if (!lookup("location")) {
          sl_send_reply("404","Not Found");
          exit;
       }
       t_on_branch("1")
       t_relay();
    }
}

onbranch_route[1] {
    xlog("-------branch=$T_branch_idx, branch flags=$bF\n");
    if (isbflagset(3)) {
       #current branch is marked as natted
       .........
    }
}

If no parallel forking is done, you can get rid of the branch route and add instead of t_on_branch():

    ........
    if (isbflagset(3)) {
       #current branch is marked as natted
       .........
    }
    .........