Realtime Integration Of Asterisk With OpenSER

http://www.voip-info.org/wiki/view/Realtime+Integration+Of+Asterisk+With+OpenSER

valid for openser 1.1.x and asterisk 1.2.x

OpenSER is a pure VoIP signaling server using Session Initiation Protocol - SIP. It is flexible and highly configurable but cannot be used to provide media services as voicemail, anounncements or conferencing. For such services, Asterisk is the most suitable open source product. In this document we present how to configure Asterisk to use OpenSER's subscribers database to provide voicemail service. A basic configuration file for OpenSER is posted down the page, allowing to have a functional system by following the steps in this tutorial.

Requirements

<!-- bitremovebr -->

• linux-like operating system (examples in this document are specific for Debian)
• asterisk 1.2.x+ - http://www.asterisk.org
• mysql 5.0.x+ - http://www.mysql.com
• openser 1.0.x+ - http://www.openser-project.org
• unixodbc 2.2.11+ - http://www.unixodbc.org
• unixodbc mysql driver - libmyodbc

UnixODBC Installation

<!-- bitremovebr -->

Get the sources from http://www.unixodbc.org, compile and install them on your system

cd /usr/local/src
wget http://www.unixodbc.org/unixODBC-2.2.11.tar.gz
tar xvfz unixODBC-2.2.11.tar.gz
cd unixODBC-2.2.11
./configure –enable-gui=no
make
make install

NOTE: if you get error during compilation in 'sqp/lex.l', the line 240, related to 'YY_FLUSH_BUFFER', you can safely comment/remove that line.

NOTE: you must have /usr/local/lib in your /etc/ld.so.conf file or LD_LIBRARY_PATH environment variable.

MySQL Installation

<!-- bitremovebr -->

You can install MySQL using the packaging system from you Linux distribution. The only requirements is to be MySQL 5.0+. For example, http://dotdeb.org provides packages for Debian stable.

After installation, you can set the MySQL root password with a command like:

/usr/bin/mysqladmin -u root password 'your-new-password'

Asterisk Installation

<!-- bitremovebr -->

Get Asterisk sources from http://www.asterisk.org. At this moment Asterisk 1.2.9.1 is the latest stable version.

cd /usr/local/src
wget http://ftp.digium.com/pub/asterisk/releases/asterisk-1.2.9.1.tar.gz
tar xvfz asterisk-1.2.9.1.tar.gz
cd asterisk-1.2.9.1

Edit 'apps/Makefile' and uncomment lines:

CFLAGS+=-DUSE_ODBC_STORAGE
CFLAGS+=-DEXTENDED_ODBC_STORAGE

Edit 'apps/app_voicemail.c' and change the size of memeber 'uniqueid' in 'struct ast_vm_user' to 64:

/* Structure for linked list of users */
struct ast_vm_user {
charcontext[AST_MAX_CONTEXT];/*Voicemailcontext*/
charmailbox[AST_MAX_EXTENSION];/*Mailboxid,uniquewithinvmcontext
charpassword[80];/*Secretpincode,numbersonly*/
charfullname[80];/*Fullname,fordirectoryapp*/
charemail[80];/*E-mailaddress*/
charpager[80];/*E-mailaddresstopager(noattachme
charserveremail[80];/*From:Mailaddress*/
charmailcmd[160];/*Configurablemailcommand*/
charlanguage[MAX_LANGUAGE];/*Config:Languagesetting*/
charzonetag[80];/*Timezone*/
charcallback[80];
chardialout[80];
charuniqueid[64];/*Uniqueintegeridentifier*/
charexit[80];
unsignedintflags;/*VM_flags*/
intsaydurationm;
intmaxmsg;/*Maximumnumberofmsgsperfolderfo
structast_vm_user*next;
};

Proceed with usual Asterisk installation:

make
make install

OpenSER Installation

<!-- bitremovebr -->

You can download latest stable version via CVS snapshots. For branch 1.0.0 (latest release in this branch is 1.0.1) you can do:

cd /usr/local/src
wget http://www.openser-project.org/downloads/snapshots/openser-1.0.0/openser-1.0.0-cvs-latest.tgz
tar xvfz openser-1.0.0-cvs-latest.tgz
cd openser-1.0.0
make all include_modules="mysql"
make install include_modules="mysql"

UnixODBC MySQL Driver Installation

<!-- bitremovebr -->

Simply install the package using the tools from your linux distribution. For example, for Debian:

apt-get install libmyodbc

Create OpenSER Database

<!-- bitremovebr -->

To create the database needed by OpenSER:

/usr/local/sbin/openser_mysql.sh create

This will create a database named 'openser' and will add a MySQL user 'openser' with full access to it. The default password is 'openserrw', do change it before (by editing usr/local/sbin/openser_mysql.sh) or immediately after you create the database.

Once you create the database, you need to add a new column to the 'subscriber' table to store the PIN for voicemail access:

ALTER TABLE subscriber ADD vmail_password varchar(32);

Create Asterisk Database

<!-- bitremovebr -->

The database needed by Asterisk will contain two views ('vmusers' and 'sipusers') of tables from OpenSER database, therefore it is required to have MySQL 5.0+ since the views were introduced in this version. There is a real MySQL table ('voicemessages') which will store the voice messages.

Log in as root in MySQL server:

create database asterisk;

use asterisk;

CREATE TABLE `voicemessages` (
`id`int(11)NOTNULLauto_increment,
`msgnum`int(11)NOTNULLdefault'0',
`dir`varchar(80)default'',
`context`varchar(80)default'',
`macrocontext`varchar(80)default'',
`callerid`varchar(40)default'',
`origtime`varchar(40)default'',
`duration`varchar(20)default'',
`mailboxuser`varchar(80)default'',
`mailboxcontext`varchar(80)default'',
`recording`longblob,
PRIMARYKEY(`id`),
KEY`dir`(`dir`)
) ENGINE=InnoDB;

CREATE VIEW vmusers AS
SELECT phplib_id as uniqueid,
usernameascustomer_id,
'default'ascontext,
usernameasmailbox,
vmail_passwordaspassword,
CONCAT(first_name,'',last_name)asfullname,
email_addressasemail,
NULLaspager,
datetime_createdasstamp
FROM openser.subscriber;

CREATE VIEW sipusers AS
SELECT username as name,
username,
'friend'astype,
NULLassecret,
domainashost,
CONCAT(rpid,'','<',username,'>')ascallerid,
'default'ascontext,
usernameasmailbox,
'yes'asnat,
'no'asqualify,
usernameasfromuser,
NULLasauthuser,
domainasfromdomain,
NULLasinsecure,
'no'ascanreinvite,
NULLasdisallow,
NULLasallow,
NULLasrestrictcid,
domainasdefaultip,
domainasipaddr,
'5060'asport,
NULLasregseconds
FROM openser.subscriber;

Add a MySQL user which will have full access right to 'asterisk' database.

GRANT ALL ON asterisk.* to asterisk@localhost IDENTIFIED BY 'some_password';

Configure UnixODBC

<!-- bitremovebr -->


In the file ‘/usr/local/etc/odbcinst.ini’ you must add:

[MySQL]
Description = MySQL driver
Driver = /usr/lib/odbc/libmyodbc.so
Setup = /usr/lib/odbc/libodbcmyS.so
CPTimeout =
CPReuse =
UsageCount = 1

In the file '/usr/local/etc/odbc.ini' you must add:

[MySQL-asterisk]
Description = MySQL Asterisk database
Trace = Off
TraceFile = stderr
Driver = MySQL
SERVER = localhost
USER = asterisk
PASSWORD = some_password
PORT = 3306
DATABASE = asterisk

Configure Asterisk

<!-- bitremovebr -->

In '/etc/asterisk/res_odbc.conf':

[asterisk]
enabled => yes
dsn => MySQL-asterisk
username => asterisk
password => asterisk
pre-connect => yes

In '/etc/asterisk/extconfig.conf':

sipusers => odbc,asterisk,sipusers
sippeers => odbc,asterisk,sipusers
voicemail => odbc,asterisk,vmusers

In '/etc/asterisk/sip.conf':

If you want to enable MWI, do not forget to set checkmwi attribute.

checkmwi=10

Guidelines about configuring the SIP channel you find at http://www.voip-info.org/wiki-Asterisk+config+sip.conf. You do not need to add any SIP user or peer in the configuration file, they will be loaded from database.

In ‘/etc/asterisk/voicemail.conf’ you do not need to add any mailbox. They will be loaded from database. The general configuration part of voicemail application is presented at http://www.voip-info.org/wiki/index.php?page=Asterisk+config+voicemail.conf

For our tutorial, we consider that the users will have 4-digit ID. To implement a clear dialing plan in Asterisk which allow extensibility and clear extentions for different services, the calls to voicemail will be prefixed with '1' in OpenSER proxy. This prefix will be transpartent for users. If voice mailbox does not exist, Asterisk will play "invalid extension" message.

In '/etc/asterisk/extensions.conf':

exten => 1,1,Ringing
exten => 1,2,VoicemailMain(${CALLERIDNUM})
exten => 1,3,Hangup

exten => 11,1,Ringing
exten => 11,2,VoicemailMain()
exten => 11,3,Hangup

exten => _1XXXX,1,Ringing
exten => _1XXXX,2,MailboxExists(${EXTEN:1})
exten => _1XXXX,3,Playback(invalid)
exten => _1XXXX,4,Hangup
exten => _1XXXX,103,Voicemail(u${EXTEN:1})
exten => _1XXXX,104,Hangup

Configure OpenSER

<!-- bitremovebr -->

Dialing plan:
- local users have 4-digit extension
- to listen its voice messages from its SIP phone, the user has to dial *98 (Asterisk will prompt only for PIN)
- to listen its voice messages from another SIP phone, the user has to dial *981 (Asterisk will prompt for mailbox ID and PIN)
- to call directly to leave voice message to user XXXX, the user has to dial *89XXXX

In '/usr/local/etc/openser/openser.cfg':

#
# $Id$
#

# ----------- global configuration parameters ------------------------

debug=3           # debug level (cmd line: -dddddddddd)
fork=yes          # daemonize
log_stderror=no   # (cmd line: -E)

check_via=no      # (cmd. line: -v)
dns=no            # (cmd. line: -r)
rev_dns=no        # (cmd. line: -R)
children=4
fifo="/tmp/openser_fifo"

listen=udp:10.10.10.10:5060

#
# ------------------ module loading ----------------------------------

# Uncomment this if you want to use SQL database
mpath="/usr/local/lib/openser/modules"
loadmodule "mysql.so"

loadmodule "xlog.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "textops.so"
loadmodule "avpops.so"
loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "group.so"
loadmodule "uri.so"

# ----------------- setting module-specific parameters ---------------
modparam("usrloc|auth_db|avpops|group",
    "db_url", "mysql://openser:openserrw@localhost/openser")

# -- usrloc params --
# persistent storage
modparam("usrloc", "db_mode", 2)

# -- auth params --
# Uncomment if you are using auth module
#
modparam("auth_db", "calculate_ha1", yes)
#
# If you set "calculate_ha1" parameter to yes (which true in this config), 
# uncomment also the following parameter)
#
modparam("auth_db", "password_column", "password")

# -- rr params --
# add value to ;lr param to make some broken UAs happy
modparam("rr", "enable_full_lr", 1)


modparam("avpops", "avp_table", "usr_preferences")

# -------------------------  request routing logic -------------------

# main routing logic

route{

	# initial sanity checks -- messages with
	# max_forwards==0, or excessively long requests
	if (!mf_process_maxfwd_header("10")) {
		sl_send_reply("483","Too Many Hops");
		exit;
	};

	if (msg:len >=  2048 ) {
		sl_send_reply("513", "Message too big");
		exit;
	};

	# we record-route all messages -- to make sure that
	# subsequent messages will go through our proxy; that's
	# particularly good if upstream and downstream entities
	# use different transport protocol
	if (!method=="REGISTER")
		record_route();

	# subsequent messages withing a dialog should take the
	# path determined by record-routing
	if (loose_route()) {
		# mark routing logic in request
		append_hf("P-hint: rr-enforced/r/n"); 
		route(1);
	};

	if (!uri==myself) {
		# mark routing logic in request
		append_hf("P-hint: outbound/r/n"); 
		route(1);
	};

	# if the request is for other domain use UsrLoc
	# (in case, it does not work, use the following command
	# with proper names and addresses in it)
	if (uri==myself) {

		if (method=="REGISTER") {
			if (!www_authorize("openser.org", "subscriber")) {
				www_challenge("openser.org", "0");
				exit;
			};

			save("location");
			exit;
		};

		# requests for Media server
		if(is_method("INVITE") && !has_totag() && uri=~"sip:/*9") {
			route(3);
			exit;
		}

		# mark transaction if user is in voicemail group
		if(is_method("INVITE") && !has_totag()
			&& is_user_in("Request-URI","voicemail"))
		{
			xdbg("user [$ru] has voicemail redirection enabled/n");
			# backup R-URI
			avp_write("$ruri", "i:10");
			setflag(2);
		};
		# native SIP destinations are handled using our USRLOC DB
		if (!lookup("location")) {
			if(isflagset(2)) {
				# route to Asterisk Media Server
				prefix("1");
				rewritehostport("10.10.10.11:5060");
				route(1);
			} else {
				sl_send_reply("404", "Not Found");
				exit;
			}
		};
		append_hf("P-hint: usrloc applied/r/n"); 
	};

	route(1);
}


route[1] {
	
	if(isflagset(2))
		t_on_failure("1");

	if (!t_relay()) {
		sl_reply_error();
	};
	exit;
}


# voicemail access
# - *98 - listen caller's voice messages, being prompted for pin
# - *981 - listen voice messages, being promted for mailbox and pin
# - *98XXXX - leave voice message to XXXX
#
route[3] {
  	# direct voicemail
	if (uri =~ "sip:/*98@" ) {
        	rewriteuser("1");
		xdbg("voicemail access/n");
	} else if (uri =~ "sip:/*981@" ) {
 		strip(4);
		rewriteuser("11");
	} else if (uri =~ "sip:/*98.+@" ) {
 		strip(3);
		prefix("1");
	} else {
		xlog("unknown media extension $rU/n");
		sl_send_reply("404", "Unknown media service");
		exit;
	}

	# route to Asterisk Media Server
	rewritehostport("10.10.10.11:5060");
	route(1);
}

failure_route[1] {
	if (t_was_cancelled()) {
		xdbg("transaction was cancelled by UAC/n");
		return;
	}
	# restore initial uri
	avp_pushto("$ruri", "i:10");
	prefix("1");
	# route to Asterisk Media Server
	rewritehostport("10.10.10.11:5060");
	resetflag(2);
	route(1);
}

See also

• Asterisk at large: Asterisk with SER/OpenSer
• Initial tutorial about this subject on OpenSER site
• OpenSER - open source SIP server with TLS support
• http://www.openser-project.org - OpenSER home page