Building the User Portal with SerMyAdmin for OpenSER

March 2009


Originally, this material was written for SerWeb. SerWeb was originally developed for the SER project. Unfortunately, SerWeb became incompatible with newer versions of OpenSER. Another important aspect of SerWeb to be considered is its vulnerabilities. There are very few options for web interfaces to OpenSER. One of the tools we have found is OpenSER administrator. This tool is being developed using Ruby on Rails. While it seems to be a very good tool to administer an OpenSER server, it does not permit to provisioning users in the same way that SerWeb did and it lacks multi-domain support. OpenSER administrator can be found at

Since a tool to build an OpenSER portal was not available , we decided to build our own tool named SerMyAdmin using Java. After a slow start, it is now ready and we are using it to build a book. It is licensed according to GPLv2 and developed in Grails (Groovy on rails). It can be downloaded at

What you are seeing here is the standalone tool. In our roadmap, we intend to integrate SerMyAdmin into the Liferay portal. Using a content management system such as Liferay ( will make your task of building a portal much easier than it is today.

The SerMyAdmin project can be found at The idea is to facilitate the administration of the OpenSER database. SerMyAdmin is licensed under the GPLv2.

Building the User Portal with SerMyAdmin for OpenSER

Lab—Installing SerMyAdmin

SerMyAdmin uses the Grails framework, so it needs an application server. You can choose from many application servers, such as IBM WebSphere, JBoss, Jetty, Tomcat, and so on. In this article we will use Apache Tomcat, because it's free and easy to install. Because we use some Java 1.5 features, we'll need Sun's Java JDK, not the free alternative GCJ.

Step 1: Create an administrator for SerMyAdmin:

mysql –u root
use openser
INSERT INTO 'subscriber' ( 'id' , 'username' , 'domain' , 'password' ,
'first_name' , 'last_name' , 'email_address' , 'datetime_created' ,
'ha1' , 'ha1b' , 'timezone' , 'rpid' , 'version' , 'password_hash' ,
'auth_username' , 'class' , 'domain_id' , 'role_id' )
NULL , 'admin', '', 'senha', 'Admin', 'Admin', 'admin@', '0000-00-00 00:00:00', '1', '1', '1', '1', '1', NULL ,
'', NULL , '1', '3'

Step 2: The next step we will take is to update our source's list to use the contrib repository and non-free packages. Our /etc/apt/sources.list, should look like below:

# /etc/apt/souces.list
deb etch main contrib non-free
deb-src etch main contrib non-free

deb etch/updates main contrib non-free
deb-src etch/updates main contrib non-free

Notice that we have added only the keywords contrib and non-free after our repository definitions.

Step 3: Update the package listing using the following command:

openser:~# apt-get update

Step 4: Install Sun's Java 1.5, running the command below:

openser:~# apt-get install sun-java5-jdk

Step 5: Make sure you are using Sun's Java. Please, run the command below to tell Debian that you want to use Sun's Java as your default Java implementation.

openser:~# update-java-alternatives -s java-1.5.0-sun

Step 6: If everything has gone well so far, you should run the following command and get a similar output.

openser:~# java -version

java version "1.5.0_14"

Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_14-b03)

Java HotSpot(TM) Client VM (build 1.5.0_14-b03, mixed mode, sharing)

Step 7: Install Tomcat. You can obtain Tomcat at:

To install Tomcat, just run the commands below:

openser:/usr/local/etc/openser# cd /usr/local
openser:/usr/local# wget
openser:/usr/local# tar zxvf apache-tomcat-6.0.16.tar.gz
openser:/usr/local# ln -s apache-tomcat-6.0.16 tomcat6

Step 8: To start Tomcat on your server initialization, please copy the following script to /etc/init.d/tomcat6.

#! /bin/bash –e
# Provides: Apache’s Tomcat 6.0
# Required-Start: $local_fs $remote_fs $network
# Required-Stop: $local_fs $remote_fs $network
# Default-Start: 2 3 4 5
# Default-Stop: S 0 1 6
# Short-Description: Tomcat 6.0 Servlet engine
# Description: Apache’s Tomcat Servlet Engine
# Author: Guilherme Loch Góes <>
set -e
test -x $DAEMON || exit 0
. /lib/lsb/init-functions
case "$1" in
echo "Starting Tomcat 6" "Tomcat6"
log_end_msg $?
echo "Stopping Tomcat6" "Tomcat6"
log_end_msg $?
$0 stop
$0 start
echo "Usage: /etc/init.d/tomcat6 {start|stop|restart}"
exit 1
exit 0

Step 9: Instruct Debian to run your script on startup; we do this with the command below.

openser: chmod 755 /etc/init.d/tomcat6

openser:/etc/init.d# update-rc.d tomcat6 defaults 99

Step 10: To make sure everything is running correctly, reboot the server and try to open in your browser the URL http://localhost:8080; if everything is OK you'll be greeted with Tomcat's start page.

Step 11: Install the MySQL driver for Tomcat, so that SerMyAdmin can access your database. This driver can be found at You should download the driver and unpack it, then copy the connector to Tomcat's shared library directory, as follows.

openser:/usr/src# tar zxf mysql-connector-java-5.1.5.tar.gz

openser:/usr/src# cp mysql-connector-java-5.1.5/mysql-connector-java-5.1.5-bin.jar /usr/local/tomcat6/lib

Step 12: Declare the data source for SerMyAdmin to connect to OpenSER's database. You can do this in an XML file found at /usr/local/tomcat6/conf/context.xml. The file should look as below:

<?xml version="1.0" encoding="UTF-8"?>
<Context path="/serMyAdmin">
<Resource auth="Container" driverClassName="com.mysql.jdbc.Driver"
 maxActive="20" maxIdle="10" maxWait="-1" name="jdbc/openser_MySQL"
 type="javax.sql.DataSource" url="jdbc:mysql://localhost:3306/openser"
 username="sermyadmin" password="secret"/>

In the file above, please change the highlighted parameters according to your scenario. SerMyAdmin can be installed in a different server than the one that holds the database. Do this for better scalability when possible. The default MySQL installation on Debian only accepts requests from localhost, so you should edit the file /etc/mysql/my.cnf, for MySQL to accept requests from external hosts.

Step 13: Create a user to be referenced in the file context.xml. This user will have the required access to the database. Please, run the commands below:

openser:/var/lib/tomcat5.5/conf# mysql -u root –p

Enter password:

Welcome to the MySQL monitor. Commands end with ; or g.

Your MySQL connection id is 14

Server version: 5.0.32-Debian_7etch5-log Debian etch distribution

Type 'help;' or 'h' for help. Type 'c' to clear the buffer.

mysql> grant all privileges on openser.* to sermyadmin@'%' identified by 'secret';

Query OK, 0 rows affected (0.00 sec)

Step 14: We're almost there. The next step is to deploy the SerMyAdmin WAR file. Please, download and copy the file serMyAdmin.war to Tomcat's webapps directory. Restart it, to activate the changes.

openser:/usr/src# cp serMyAdmin-0.4.war /usr/local/tomcat6/webapps/serMyAdmin.war

openser:/usr/src# invoke-rc.d tomcat6 restart

Don't worry about database modifications; SerMyAdmin will automatically handle that for you.

Step 15: Configure Debian's MTA (Message Transfer Agent) to allow SerMyAdmin to send a confirmation email to new users. Run the command below to configure Exim4 (default MTA for Debian). Ask your company's email administrator.

openser:/# apt-get install exim4

openser:/# dpkg-reconfigure exim4-config

You will be greeted with a dialog-based configuration menu; on this menu it's import to pay attention to two options: General type of mail configuration, which should be set to Internet Site so that we can send and receive mails directly using SMTP, and Domains to relay mail for, which should be set to the domain from which you want the emails from SerMyAdmin to appear to come.

Step 16: Customize the file /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin-0.3/WEB-INF/spring/resource.xml, which contains the parameters that specify which email server is used to send mails and from whom these emails should appear to come from. The following is an example of this file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns=""
xsi:schemaLocation=" http://www.">
<bean id="mailSender" class="org.springframework.mail.javamail.
<property name="host"><value>localhost</value></property>
<!-- You can set default email bean properties here, eg: from/to/
subject -->
<bean id="mailMessage" class="org.springframework.mail.
<property name="from"><value></value></

The first parameter to change is the server that we will use to send emails. The second is the parameter specifying from whom those emails will appear to come.

Restart Tomcat again and we're ready to go. When you point your browser to http://<server address>:8080/serMyAdmin you should be greeted with the login page, the same as we have shown at the start on this article.


Basic Tasks

You can now use SerMyAdmin for a bunch of tasks. In this article we will show you how to create and administer new users and groups. We can also use SerMyAdmin for other tasks such as managing the trust table and the LCR module.

Registering a New User

To register a new user, in the login screen simply click on the Register Button.

Building the User Portal with SerMyAdmin for OpenSER

Fill up the fields, Username, Password, Domain, Email, First Name, Last Name, Caller Id, and the confirmation code. Press the Create button at the end of the screen. The user will be added to the database. Both the system administrator and the user will receive an email about the registration. Before the user can make any calls, the administrator will have to approve the user.

Approving a New User

Follow this step-by-step procedure to approve a new user:

Step 1: Log in with the admin@localhost account, password openserrw created during the OpenSER installation. The installation process has created a new attribute named Role for every user. The purpose of this column is to differentiate normal users, domain administrators, and global administrators. The admin user was automatically set to Global Administrator. This new field will help us to provide multi-domain support.

Step 2: Select the menu item Registered Users.

Building the User Portal with SerMyAdmin for OpenSER

In the screen above, select the users you want to add and check the box Approve. Press the button Approve to add the user; the user will be removed from the register_user table and moved to the subscriber table, and then, he will be able to register to OpenSER and make calls.

Building the User Portal with SerMyAdmin for OpenSER

Step 3: The user now should appear on your user list. Check this by clicking the menu item Users.

Building the User Portal with SerMyAdmin for OpenSER

User Management

You can view, add, edit, and delete users on the Users menu. When you click it, you'll have all users on the system displayed.

Building the User Portal with SerMyAdmin for OpenSER

To add a new user you must click on the New User link. You'll be directed to the page below:

Building the User Portal with SerMyAdmin for OpenSER

In the preceding page you must complete the fields and click on the Create link, then the user will be added to the subscriber table. The following page will be shown after this:

Building the User Portal with SerMyAdmin for OpenSER

In this page you can modify the information inserted by clicking on Edit, or delete the user by clicking on Delete.

On the User List page you can search for users based on username, domain, and email; just click on the Search link, and fill out only the desired criteria. On the following page, we will search for all users with the username jdoe. Click Search; you'll be directed to the User List that matches your criteria.

Building the User Portal with SerMyAdmin for OpenSER

Domain Management

You can manage your domains in the same way as you manage your users. Click on Domains to get a domain list. There, you can add a new domain, delete an existing domain, and so on. It is important to note that SerMyAdmin doesn't allow a user to exist without a domain, so when you delete a domain you also delete all users that belong to that domain.

Interface Customization

For its site layout SerMyAdmin uses a SiteMesh framework, so it's pretty simple to customize the look of SerMyAdmin to your taste. SiteMesh displays the pages based on a template that can be found at openser:/usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin-0.3/WEB-INF/grails-app/views/layouts. There you'll find main.gsp and notLoggedIn.gsp; these files are Groovy Server Pages that control how the pages are displayed.

SiteMesh uses HTML meta tags to choose which layout to use; those tags should be found in the head element of each page, that is, if a page has the tag <meta content="main" name="layout"/> inside its head element, SiteMesh will use the main.gsp layout to display it.

You can change main.gsp and notLoggedIn.gsp as you wish, but it's important to understand that <g:layoutHead /> and <g:layoutBody /> will hold the head and body tags of the pages using this layout. Another thing to know is that <g:render template="/menu" /> is used to render page fragments; these page fragments are GSP files, and their filename should start with an underscore ("_").

To replace the SerMyAdmin logo with one of your own, just put your logo on /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin-0.3/images, and edit the tag that points to the logo_voffice.png in the layout files, just as shown below:

<div class="logo"><img src="${createLinkTo(dir:'images',file:'my_new_logo.png')}" alt="Grails" /></div>

In the above tag we replaced the SerMyAdmin logo with one of our own, just changing by the parameter in bold.

You can also change the look and feel of SerMyAdmin by modifying its CSS file, which can be found at /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin-0.3/css; in the main.css file we'll find every class to change SerMyAdmin behavior.

Example: if we change the background class in this file with the following parameters:

body {
background: #00f;
color: #333;
font: 8px verdana, arial, helvetica, sans-serif;

We will end getting a page that looks like this:

Building the User Portal with SerMyAdmin for OpenSER

This page isn't the prettiest thing on the planet, but you can follow this example to make it look a lot better.


In this article, you have learned why it is important to have a user and administrator portal. It is a piece of software to which you should pay a lot of attention. Several VoIP providers fail to allocate time and resources to the important task of building the portal. OpenSER is an amazing SIP proxy, but a SIP proxy is just one of the components in a VoIP Provider. Without a good administrator and user interface a VoIP provider project can easily fail. SerMyAdmin is our contribution to your project. Developed in Java using Groovy on Rails it is licensed according to GPL version 2. You have learned how to install, manage users and domains, and how to customize the appearance.

You've been reading an excerpt of:

Building Telephony Systems with OpenSER

Explore Title