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



===== OpenSER Packaging =====

==== Debian packages: make deb ====

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.

===== OpenSER Database Structure =====

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

<code>
openser_mysqldb.sh migrate <old_db> <new_db>
</code>

More details:

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

===== OpenSER Core =====


==== FIFO server moved as module - mi_fifo ====

- 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: [[http://www.openser.org/docs/modules/1.2.x/mi_fifo.html|MI_FIFO Readme]]

- 1.1.x version of:

<code>
fifo="/tmp/fifo"
</code>

goes in 1.2.x as:

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

modparam("mi_fifo","fifo_name", "/tmp/openser_fifo")
</code>


==== fifo_db_url removed ====

The "fifo_db_url" and FIFO DB interface were removed.

==== Flags redesigned ====

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

- [b]transaction flags[/b]

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

- [b]branch flags[/b]

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

- [b]script flags[/b]

* 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 [[core-cookbook:devel|OpenSER Core Cookbook]] and [[utils:flags|OpenSER Flags Description]] for function prototypes and documentation.


==== retcode removed ====

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

Example v1.1.x:
<code>
switch(retcode) {
   case 1:
     xlog("returned code was 1\n");
   break;
   default:
     xlog("returned code different than 1\n")
}
</code>

Example v1.2.x:
<code>
switch($retcode) {
   case 1:
     xlog("returned code was 1\n");
   break;
   default:
     xlog("returned code different than 1\n")
}
</code>


==== auto_aliases ====
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

===== OpenSER Modules =====

==== AVP Parameters ====

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/]

==== acc ====

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.

<code>
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`)
);
</code>

The parameters of **acc** module will look like:

<code>
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")
</code>


==== auth ====

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

==== avpops ====

* [b]avpops functions can be used in onreply routes[/b]. 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 [b]onreply_avp_mode parameter[/b] (http://www.openser.org/docs/modules/1.2.x/tm.html#AEN303).

* [b]avp_aliases was moved to core[/b]

- 1.1.x version of:

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

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

<code>
avp_aliases="uuid=I:660;email=s:email_addr;fwd=i:753"
</code>

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

<code>
# 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";
</code>


==== cpl-c ====

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



==== dispatcher ====

* 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


==== msilo ====

* 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


===== OpenSER Tools =====



==== openserctl ====

* 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".

<code>
## presence of serweb tables - default "no"
HAS_SERWEB="yes" 
</code>

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

<code>
STORE_PLAINTEXT_PW=1
</code>

===== OpenSER Internals =====

Stuff that should concern the developers.

  * struct module_exports has changed


===== OpenSER Configuration =====


==== NAT Traversal ====

The branch flags have to be used now for NAT traversal. See [[utils:flags|OpenSER Flags Description]].

<code>
..........
# 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
       .........
    }
}
</code>

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

<code>
    ........
    if (isbflagset(3)) {
       #current branch is marked as natted
       .........
    }
    .........
</code>

===== Installation Stuff =====

{{indexmenu>install|js}}