Building Telephony Systems with OpenSIPS 1.6 — Save 50%
Build scalable and robust telephony systems using SIP
It is very hard to manage thousands of users manually, so a user-provisioning tool becomes very important in our process. In this article by Flavio E.Goncalves, we are going to see two of these tools—SerMyAdmin and OpenSIPS Control Panel (OpenSIPS-CP). SerMyAdmin is more focused on the administration of the users, while OpenSIPS-CP is excellent for monitoring and provisioning parameters to the system. By the end of this article, you will be able to:
- Identify why you need a user portal for administration
- Install SerMyAdmin and its dependencies
- Configure resources such as administrator and user access
- Add and remove domains
- Customize the portal with the colors and logos of your company
- Install and configure OpenSIPS Control Panel
- Use opensips-cp for daily tasks
OpenSIPS Control Panel
This tool, also known as opensips-cp, is the new graphical user interface for the SIP proxy. It was designed to be the primary tool to provision parameters for the OpenSIPS modules in the database.
The screenshot shows the tools available for OpenSIPS Control Panel. This tool is focused on the provisioning of system parameters. As it is usual for the VoIP providers to develop their own interface with the end users, the tools to manage end users are not available. Developed using PHP, opensips-cp currently features the following modules:
- load balancer
Installation of opensips-cp
The step-by-step instructions to install opensips-cp in a server with Debian 5.0 are as follows:
Installation instructions change very often. For updates, check the opensips-cp project's website at http://opensipscp.sourceforge.net/.
Step 1: Install Apache and PHP as follows:
apt-get install apache2 php5
Step 2: Install php5-mysql and php5-xmlrpc packages, and set the right parameters in the php.ini file. (It has been done for you to save time.)
apt-get install php5-mysql php5-xmlrpc php-pear
Please verify that you have set the short_open_tag = On ; option in your php.ini file.
Step 3: Download opensips-cp and untar the file.
Download opensips-cp from http://opensips-cp.sourceforge.net/index.php?req=download (or copy from DVD) and copy the opensip-cp_3.0.tgz file to /var/www as follows:
tar -xzvf opensips-cp_3.0.tgz
chown www-data:www-data opensips-cp -R
Step 4: Install MDB2.
pear install MDB2
pear install MDB2#mysql
pear install log
Step 5: Configure Apache for OpenSIPS Control Panel. Edit the apache2.conf file.
After doing so, include the following line below the last line:
Alias /cp "/var/www/opensips-cp/web"
Also, change the owner of the log file:
chown www-data:www-data /var/www/opensips-cp/config/access.log
Step 6: Install the cdr table schema:
mysql -D opensips -p < cdrs.sql
mysql -u root -p
mysql> use opensips
mysql -D opensips -p < opensips_cdrs_1_6.mysql
Step 7: Edit the cron_job/generate-cdrs.sh file and change the MySQL connection data (hostname, username, password, and database) as follows:
Step 8: Edit the /etc/crontab file and add the following line for a three-minute interval:
*/3 * * * * root /var/www/opensips-cp/cron_job/generate-cdrs.sh
Step 9: For the smonitor module, you must add two tables to the OpenSIPS database:
mysql -p opensips <tables.sql
Step 10: Add a cron job that collects data from the OpenSIPS machine(s). Here is a cron job that collects data at a one-minute interval. (This interval is not arbitrary. It must be set to one minute by design.)
* * * * * root php /var/www/opensips-cp/cron_job/get_opensips_stats.php >
The cron jobs do not need to run as root. You might want to change the user.
Step 11: Restart OpenSIPS and Apache.
eBook Price: $26.99
Book Price: $44.99
Monit is a system-monitoring utility that allows an admin to easily monitor files, processes, directories, or devices on your system. It can also be used for automatic maintenance/repairs by executing particular commands when errors arise. Providing instructions on how to install Monit is beyond the scope of this article, but we have provided some here in order to avoid errors when you select the Monit tool in the OpenSIPS-CP.
The step-by-step instructions are as follows:
Step 1: To install Monit on your server, simply use apt-get:
apt-get install monit
Step 2: Once installed, you'll find the main configuration file.
set daemon 120
set logfile syslog facility log_daemon
set alert root@localhost
set httpd port 2812 and
use address yourdomain.com
allow localhost # allow localhost to connect to the server and
allow youripaddress # allow 192.168.1.2 to connect to the server,
# You can give only one per entry
allow admin:monit # user name and password for authentication.
check process opensips with pidfile /var/run/opensips.pid
#Below is actions taken by monit when service got stuck.
start program = "/etc/init.d/opensips start"
stop program = "/etc/init.d/opensips stop"
# Admin will notify by mail if below of the condition satisfied.
if cpu is greater than 70% for 2 cycles then alert
if cpu > 90% for 5 cycles then restart
Step 3: After modifying the configuration file, you should check for the syntax to make sure that everything is correct. To do this, run:
# monit -t
Step 4: Edit the /etc/default/monit file and change the parameters as follows:
# You must set this variable to for 1 monit to start
# To change the intervals which monit should run uncomment
# and change this variable.
Configuring OpenSIPS Control Panel
Step 1: Configure the database access parameters. Edit the db.inc.php file, which is valid for all modules. You may change the database parameters for a single module inside the module configuration section.
$config->db_host = "localhost";
//database port - leave empty for default
$config->db_port = "";
//database connection user
$config->db_user = "root";
//database connection password
$config->db_pass = "opensips";
$config->db_name = "opensips";
if ($config->db_port != "")$config->db_host=$config->db_host":"
Step 2: Configure the FIFO access in the boxes.global.inc.php file:
// mi host:port pair || fifo_file
// monit host:port
// description (appears in mi , monit )
$boxes[$box_id]['desc']="Primary SIP server";
// enable local smonitor charts on this box : 0=disabled 1=enabled
Step 3: Access http://server_ip_address/cp and check each module for the correct functionality.
SerMyAdmin was originally created to be an alternative for provisioning user and system information to the database. It is licensed according to GPL-2 and developed in Grails (Groovy on Rails). It can be downloaded from http://sourceforge.net/projects/sermyadmin.
The utility SerMyAdmin has the following modules:
- Load Balance
- Speed Dial
Some more interesting features of the interface are:
- User auto-registration with e-mail confirmation
- Captcha to prevent spam in the auto-registration process
- A user portal to allow end users to change preferences, speed dial, and password
- It allows enabling and disabling modules
- Support for internationalization (i18N)
- An installation utility
The utilities in OpenSIPS-CP that are not found in SerMyAdmin are siptrace, smonitor, and monit.
We started the SerMyAdmin project in 2007 as a GUI for OpenSER because none was available. We migrated the tool for OpenSIPS recently; the idea is not to compete with OpenSIPS-CP, but to provide an easy interface to edit OpenSIPS tables and users. The new version is capable of automatically registering users with e-mail confirmation and providing user parameters. There is a plan to rename the tool to SipMyAdmin in the near future for coherency. Many customers don't really see a product if you don't have a graphical user interface. The administration costs to operate OpenSIPS in the command line are high because you need a specialized professional just to create users, groups, and so on. I think SerMyAdmin is a good start for a user and an administration portal.
SerMyAdmin uses the Grails framework, which is an excellent platform to develop web applications connected to a jdbc database. It is possible to include a new module in a matter of hours. Grails has a nice learning curve, so within a few days you can start changing or enhancing SerMyAdmin to fulfill your needs.
On the other hand, Grails needs an application server. You can choose from many different application servers, such as Tomcat or Glassfish. In this article, we will use Apache's Tomcat because it's free and easy to install. As we use some Java 1.6 features, we'll need Sun's Java JDK; rather than the free alternative GNU Compiler for Java (GCJ).
Step 1: The first step is to update your sources list to use the contrib repository and the non-free packages. Your /etc/apt/sources.list should look like:
http://ftp.us.debian.org/debian/lenny main contrib non-free
http://ftp.us.debian.org/debian/lenny main contrib non-free
http://security.debian.org/lenny/updates main contrib non-free
http://security.debian.org/lenny/updates main contrib nonfree
We've added only the contrib and non-free keywords after our repository definitions.
Step 2: Update the package listing using the following command:
Step 3: Download and uncompress sermyadmin-install-2.x.tar.gz from the website www.sermyadmin.org.
The URLs for downloadable files change very often. Please check the website first and change x to the latest version of the software.
tar -xzvf sermyadmin-install-2.x.tar.gz
Step 4: Run the installation shell script and answer yes to the questions:
Step 5: To make sure everything is running fine, reboot the server and try to open the URL http://localhost:8080 in your browser. If everything is okay, you'll be greeted with Tomcat's start page.
Step 6 (optional): Configure Debian's message transfer agent (MTA) in case you want your own server to send e-mails, but this is not the easiest setup. The utility SerMyAdmin can be configured to use any e-mail service; all you have to do is set the parameters.
apt-get install exim4
You will be greeted with a dialog-based configuration menu. On this menu, it's important to pay attention to two options:
- General type of mail configuration: This should be set to Internet Site, so that we can send and receive mails directly using SMTP
- Domains to relay mail for: This should be set to the domain which you want the e-mails from SerMyAdmin to appear to come from
Step 1: Declare the datasource for SerMyAdmin to connect to OpenSIPS's database. You can do this in an XML file found at /usr/local/tomcat6/conf/context.xml. The file should look like the following:
<?xml version="1.0" encoding="UTF-8"?>
<Resource auth="Container" driverClassName="com.mysql.jdbc.Driver"
maxActive="20" maxIdle="10" maxWait="-1" name="jdbc/opensips_MySQL"
In the file we just saw, change the highlighted parameters according to your scenario. SerMyAdmin can be installed on a different server than the one that holds the database. Do this for better scalability whenever possible. The default MySQL installation on Debian only accepts requests from localhost. So, you should edit the /etc/mysql/my.cnf file to enable MySQL to accept requests from external hosts.
Step 2: Customize the /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin/WEB-INF/spring/resource.xml file, which contains the parameters that dictate which e-mail server is used to send mails and from whom these e-mails should appear to come from. The following is a sample of this file:
<?xml version="1.0" encoding="UTF-8"?>
<bean id="smtpAuthenticator" class="SmtpAuthenticator">
<constructor-arg value="firstname.lastname@example.org" />
<constructor-arg value="password" />
<bean id="mailSession" class="javax.mail.Session" factorymethod="
<constructor-arg ref="smtpAuthenticator" />
<property name="host" value="smtp.gmail.com" />
<property name="session" ref="mailSession" />
<bean id="mailMessage" class="org.springframework.mail.SimpleMailMessage">
<property name="from" value="email@example.com" />
These parameters are for sending e-mails using the Spring framework. The first parameter to be changed is the server that we will use to send e-mails. The following is the parameter from which those e-mails will appear to come from, and then you can set authentication parameters and mail servers. Restart Tomcat again and we're ready to go.
Step 3: Restart Tomcat and point your browser to http://<server address>:8080/serMyAdmin. You should be greeted with the login page.
eBook Price: $26.99
Book Price: $44.99
You can now use SerMyAdmin for a bunch of tasks. In this article, we will learn how to create and administer new users and groups.
Registering a new user
To register a new user, simply click on the Register button in the login screen.
Enter the fields Username, Domain, Password, E-mail Address, First Name, Last Name, Voice Mail Password, and the Security Code. Click on 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 e-mail about the registration. Before the user can make any calls, the administrator will have to previously approve him or her. In the newest version, the user can confirm the account by e-mail. He will receive an e-mail with a code that must be used to confirm the registration request. Anyway, you can still approve users manually.
Approving a new user
Follow this step-by-step procedure to approve a new user:
Step 1: Log in with the admin@setup account and the secret password created during the OpenSIPS installation. The installation process has created a new attribute named Role for every user. The purpose of this column is to differentiate normal users from global administrators. The admin user was automatically set to Global Administrator. This new field will help us to provide multidomain support in the future.
Step 2: Select the Users | Pending menu item.
In the following screenshot, select the users you want to add and select the Approve checkbox. Click on the Approve button to add the user. The user will be removed from the register_user table and moved to the subscriber table, and then he or she will be able to register to OpenSIPS and start making calls.
Step 3: Verify the user's insertion in the user's database, by selecting the Users menu item.
The user should now appear on your user list. Check this by clicking on the Users menu item. Don't forget to include the user in the right groups to allow dialing.
You can view, add, edit, and delete users via the Users | User List menu. After selecting, all users will be displayed.
To add a new user, you must click on the New User link. You'll be directed to the following page:
In the last page, you must complete the fields and click on the Create link. The user will be added to the subscriber table. The following page will be shown after this:
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 e-mail; click on the Search link, and fill only the desired criteria. On the following page, we will search for all users with the username jdoe. Click on Search and you'll be directed to the User List that matches your criteria.
You can manage your domains in the same way as you manage your users. Click on Domains to get a domain list. Here, 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 who belong to that domain.
The SerMyAdmin interface is licensed according to GPL. You can download and modify the code. To do this, I suggest you to read at least the Grail tutorial. After learning some Grail, you may create a development environment using NetBeansIDE.
For its site layout, SerMyAdmin uses the 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 may be found at /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin/WEB-INF/grails-app/views/layouts.
There, you'll find the main.gsp and notLoggedIn.gsp files. These files are Groovy Server Pages (GSP) that control how the pages are displayed.
SiteMesh uses HTML <meta> tags to choose which layout to use. These tags should be found in the <head> tag of each page. That is, if a page has the <meta content="main" name="layout"/> tag inside its <head> tag, SiteMesh will use the main.gsp layout to display it.
You may now change the 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 the <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 in /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin/images and edit the tag that points to the logo.png in the layout files, as shown in the following code snippet:
In the tag we just saw, we replaced the SerMyAdmin logo with one of our own, just changing the highlighted parameter.
You can also change the look and feel of SerMyAdmin, modifying its CSS file that can be found at /usr/local/apache-tomcat-6.0.16/webapps/serMyAdmin/css. In the main.css file, we'll find every class required to change the SerMyAdmin behavior.
Comparing OpenSIPS-CP and SerMyAdmin
The OpenSIPS-CP tool is more focused on the provisioning of OpenSIPS data, and to generate statistics and traces. It is the tool the super administrator will use most of the time. The SerMyAdmin tool is focused on the management of users. It has been developed to be used by users and administrators in the daily tasks related to users, DID (aliases), passwords, and accounting. You may deactivate the routing menus if you don't want your administrators to use it.
In this article, you learned why it is important to have a user and an 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.
OpenSIPS is an amazing SIP proxy, but an SIP proxy is just one of the components in a VoIP provider. Without good administrator and user interfaces, a VoIP provider project may easily fail. SerMyAdmin is our contribution to your project. Developed using Groovy on Rails, it is licensed according to GPL. You learned how to install, manage users and domains, and how to customize the appearance. The tool can do a lot more things. OpenSIPS Control Panel is the new tool developed by the OpenSIPS project. It is focused on the super administrator tasks and provisioning of data for advanced modules.
If you have read this article you may be interested to view :
About the Author :
Flavio E.Goncalves was born in 1966 in Brazil. Having always had a strong interest in computers, he got his first personal computer in 1983 and since then it has been almost an addiction. He received his degree in Engineering in 1989 with a focus on computer-aided design and computer-aided manufacturing.
He is also the CEO of V.Office Networks in Brazil—a consulting company dedicated to the areas of Networks, Security, and Telecommunications and a training center since its foundation in 1996. Since 1993, he has participated in a series of certification programs and been certificated as Novell MCNE/MCNI, Microsoft MCSE/MCT, Cisco CCSP/CCNP/CCDP, Asterisk dCAP, and some others.
He started writing about open source software because he thinks that the way certification programs were organized in the past was very good for helping learners. Some books today are written by strictly technical people who, sometimes, do not have a clear idea of how people learn. He tried to use his 15 years of experience as an instructor to help people learn about the open source telephony software. His experience with networks, protocol analyzers, and IP telephony combined with his teaching experience give him an edge to write this book. This is the third book written by him; the first one was "Configuration Guide for Asterisk PBX“, BookSurge Publishing.
As the CEO of V.Office, Flavio E. Goncalves balances his time between family, work, and fun. He is a father of two children and lives in Florianopolis, Brazil, one of the most beautiful places in the world. He dedicates his free time to water sports such as surfing and sailing.