Migrating OpenSER v1.0.x to v1.1.x

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

In this section are listed the changes in database structure.

* new columns

* table version: 2

MySQL queries:

alter table gw add column strip TINYINT UNSIGNED after transport;

update version set table_version = 2 where table_name = 'lcr' ;

* new columns

* table version: 1003

MySQL queries:

update version set table_version =1003 where table_name = 'location';

update version set table_version =1003 where table_name = 'aliases';

alter table location add column path varchar(255) default NULL after received;

alter table location add column methods int(11) default NULL after socket;

alter table location change column last_modified last_modified datetime NOT NULL default “1900-01-01 00:00”;

* new table (grp module)

* table version: 1

* new column

alter table silo add column snd_time INTEGER NOT NULL DEFAULT 0;

update version set table_version = 4 where table_name = ‘silo’ ;

* table version: 4

* new table (siptrace module)

* table version: 1

* new columns

* table version: 3

MySQL queries: alter table trusted add column tag varchar(32) DEFAULT NULL;

This section reflects changes in core which affects configuration file or application behaviour.

Forward functions use same syntax as t_relay(). They get the parameter as a destination address in format 'proto:host:port'

forward("udp:10.10.10.10:5060");

forward_[proto](“address”) ⇒ forward(“proto:address”)

forward(uri:host, uri:port) ⇒ forward()

more: http://openser.org/dokuwiki/doku.php?id=openser_v1.1.0_core_cookbook#forward_destination

* The pseudo-variables can have variable-length name.

Take care now to use parenthesis to mark pseudo-variable name when needed – $ru is the same as $(ru). If you do not use parenthesis, the name should be followed by a character which is not accepted in pseudo-variables' name. The name of a pseudo-variable may contain: any letter, any digit, '_' , '.'.

Examples:

avp_printf("$avp(i:123)","$rUabc");
  -- this will print the pseudo-variable with name 'rUabc'

avp_printf("$avp(i:123)","$(rU)abc");
 -- this will print the username of request URI concatenated with 'abc'

avp_printf("$avp(i:123)","$rU/abc"); and avp_printf("$avp(i:123)","$(rU)/abc");
 -- are equivalent -- '/' is not a valid character for pseudo-variables name

* OpenSER 1.1.x allows modules to export pseudo variables.

E.g. the tlsops module (with patch http://sourceforge.net/tracker/index.php?func=detail&aid=1477147&group_id=139143&atid=743022) exports the following pseudo variables (for more details refer to the tlsops README in modules/tlsops/):

• $tls_version
• $tls_description
• $tls_cipher_info
• $tls_cipher_bits
• $tls_[peer|my]_version
• $tls_[peer|my]_serial
• $tls_[peer|my]_[subject|issuer]
• $tls_[peer|my]_[subject|issuer]_cn
• $tls_[peer|my]_[subject|issuer]_locality
• $tls_[peer|my]_[subject|issuer]_country
• $tls_[peer|my]_[subject|issuer]_state
• $tls_[peer|my]_[subject|issuer]_organization
• $tls_[peer|my]_[subject|issuer]_unit
• $tls_[peer|my]_san_email
• $tls_[peer|my]_san_hostname
• $tls_[peer|my]_san_uri
• $tls_[peer|my]_san_ip
• $tls_peer_verified
• $tls_peer_revoked
• $tls_peer_expired
• $tls_peer_selfsigned
• $tls_peer_notBefore
• $tls_peer_notAfter

The TLS core was extended to provide not only tls server domains, but also tls client domains. This means for each outgoing request you can specify the TLS parameters (cert, CA …). The selection can be done depending on a certain AVP or on the destination socket of the request (ip:port). There were further some changes in the syntax to make it more consistent (refer to section “OpenSER Configuration”).

This section reflects changes in modules which affects configuration file or application behaviour.

The naming schema in parameter given to exported functions of avpops module has changed. From now on you have to use:

• $avp(i:number) - e.g., $avp(i:10)

• $avp(s:string) - e.g., $avp(s:rpid)

• $avp(alias) - e.g., $avp(foo)

example: in v1.0.x was 'avp_printf("i:10", "1234")' => in v1.1.x is 'avp_printf("$avp(i:10)", "1234")'
-- print to AVP having integer ID 10
example: in v1.0.x was 'avp_check("i:3", "eq/i:1")' => in v1.1.x is 'avp_check("$avp(i:3)", "eq/i:1")'
-- check if AVP having integer ID 3 is equal to integer 1

avp_pushto(“$Header”,“…”) is depreacated, instead use append_hf() from textops module.

avp_pushto("$Email", "$avp(s:email)") => append_hf("Email: $avp(s:email)\r\n")

The set of relaying functions 't_relay_to_[proto]()' has been removed and replaced with 't_relay(“proto:address:port”)'.

t_relay_to_udp("sip.com","5060") => t_relay("udp:sip.com:5060")

The lcr module can operate in two modes:

• non-caching mode (default one in 1.0.x).

For preserving the old behaviour, set the db_mode param to non-caching mode:

modparam("lcr","db_mode",0).

• caching mode (default one in 1.1.0).

The from_uri_column of the lcr table must be transitioned from db matching (special characters '%' and '_') to regex matching.

This section reflects changes in configuration file format.

Note: the following text is based on current CVS+the TLS patch (http://sourceforge.net/tracker/index.php?func=detail&aid=1477147&group_id=139143&atid=743022)

• “tls_require_certificate” was renamed to “tls_require_client_certificate” to be more accurate and self explanatory
• “tls_verify” was splitted into “tls_verify_client” and “tls_verify_server” to set the verify policy indepdently for TLS client and TLS server domains
• new parameter “tls_client_domain_avp” defines the AVP for AVP based TLS client domain selection
• parameter “tls_domain” was splitted into “tls_client_domain” and “tls_server_domain” to allow definition of TLS client and server domains
• “tls_verify_client”, “tls_verify_server” and “tls_require_client_certificate” can be used inside the respective tls_xxxx_domain block to define the verify policy per TLS domain
• “tls_ciphers_list” can be used inside the tls_xxxx_domain block to specify the TLS method per TLS domain

For more details refer to the TLS README in tls/

Stuff that should concern the developers.

• struct int_str has changed from {str*, int} in {str, int}

• struct module_exports has changed

This section reflects changes in OpenSER tools which affects configuration file or application behaviour.

• the tool has been removed, same functionality being given by:

echo -n 'user:realm:password' | md5sum | awk  '{ print $1 }'

The OpenSER control tool (openserctl) has a new version. It includes the functionalities from several old tools with similar functionality: openserctl, openserctl.postgress and openserctl_unixsock.

Right now it has a plug-in model, so you can customize it to fit your needs. You can select mysql or postgres as database backend and fifo or unixsockets as communication protocol with OpenSER.

By default, openserctl installs with only FIFO support, all the other components requiring non-standard modules. For example, the component which enables MySQL backend in installed only when mysql modules is intalled. This allow better dependency rules for packaging.

openserctl components are installed in '/usr/local/lib/openser/openserctl' if you install from sources and in '/usr/lib/openser/openserctl' if you install from packages. Each component is named 'openserctl.xyz', where xyz is a meaningful name for the extension.

In addition, there is a configuration file for 'openserctl'. By default it is '/usr/local/etc/openser/openserctlrc' when installing from sources and '/etc/openser/openserctlrc' when installing from packages.

In this file, you can configure openserctl do load desired extensions. You have to edit it and read the comments for further instructions.

Also, you can create a .openserctlrc file in your home directory for a personal customization of openserctl.

If you encounter troubles, here is manual way of getting the new openserctl work:

Download it from cvs:

http://openser.cvs.sourceforge.net/openser/sip-server/scripts/?pathrev=rel_1_1_0

All files containing openserctl in the name should be downloaded. Then place the files on the local file system as follows:

openserctl ⇒ /usr/local/sbin/

openserctlrc ⇒ /usr/local/etc/openser/

openserctl.{base,sqlbase,ctlbase,fifo,unixsock,mysql,pgsql} ⇒ /usr/local/lib/openser/opensectl/

Edit now /usr/local/etc/openserctrc and add:

DBENGINE=MYSQL

CTLENGINE=FIFO

Do: chmod +x /usr/local/sbin/openserctl

Also, you can set the database parameters - the comments in /usr/local/etc/openserctrc give you more details.

Now you can use /usr/local/sbin/openserctl to perform the usual tasks you did with the openserctl from 1.0.1.

In addition, new functions were added, better help message and error handling.