OpenSIPS-CP Installation & Configuration



Installation and Configuration Steps:

Apache must be Installed and Configured:

# yum install httpd

Run it :

# systemctl start httpd

Then be sure it is running: # ps aux |grep http or # netstat -lpn |grep http

Go to and get the source:

# cd /var/www

# svn checkout svn:// opensips-cp

Install PHP and some extensions: Here i have Fedora Red Hat:

 #  yum install php php-common php-gd php-mysql php-xmlrpc php-pear

Install Mysql Driver

# pear install mdb2#mysql

Check if the Extensions are Installed Correctly:

For Redhat check “mysql.ini”/”mysqlnd.ini”, “gd.ini”, “xmlrpc.ini” in “/etc/php.d/”.

Enable short_open_tag in “/etc/php.ini”:

 short_open_tag = On

Configure OpenSIPS-CP’s Database Connection:

# cd /var/www/opensips-cp

# vi config/

Configure OpenSIPS-CP Boxes:

The configuration of these boxes determines how the OpenSIPS-CP will communicate with OpenSIPS. For example you can configure Mi box to access the OpenSIPS Mi interface. This can be through RPC protocol, FIFO, UDP, or JSON.

 # vi config/

Part of this file:

            // options: fifo:/path/to/fifo_file | xmlrpc:host:port | udp:host:port | json:json_url


This file “/tmp/opensips_fifo” is configured  in OpenSIPS’s configuration file in the FIFO module section:

            #### FIFO Management Interface

            loadmodule “”

            modparam(“mi_fifo”, “fifo_name”, “/tmp/opensips_fifo”)

            modparam(“mi_fifo”, “fifo_mode”, 0666)

This file is created by OpenSIPS. so the access permission to this file is determined by OpenSIPS. “0666” is the (read&write for all ) permission to the fifo file.

Note: The global  file “/var/www/opensips-cp/config/” is important but also the local file for each module is important. For example: the file “/var/www/opensips-cp/config/tools/system/dialog/” contains some options  for “dialog” module.

If you have any problem related to accessing the fifo file please click here.

Now OpenSIPS-CP can access the opensips database and can communicate with opensips through Mi interface.

OpenSIPS-CP needs an extra table as an addition to OpenSIPS’s Database. We need to push it in the opensips database. Install the “ocp_admin_privileges” table schema.

# cd /var/www/opensips-cp

# mysql -Dopensips -p < config/tools/admin/add_admin/ocp_admin_privileges.mysql

Create Admin Account with all Privileges:

You will use this account from the opensips-cp web interface. I will add the user admin with password admin withh full permission:

Login to the Database as Root

         # mysql -uroot -p

Mysql> use opensips;

Mysql> INSERT INTO ocp_admin_privileges (username,password,ha1,available_tools,permissions) values (‘admin’,’admin’,md5(‘admin:admin’),’all’,’all’);

Configure Apache:

# vi /etc/httpd/conf/httpd.conf

Add the following:

<Directory /var/www/opensips-cp>

Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require all denied


<Directory  /var/www/opensips-cp/web>

Options Indexes FollowSymLinks MultiViews

AllowOverride None
Require all granted


Alias /cp /var/www/opensips-cp/web

Restart Apache:

# systemctl restart httpd

Make apache, the owner of opensips-cp folder:

# chown -R apache:apache /var/www/opensips-cp/

Open the browser and go to OpenSIPS-CP main page: http://localhost/cp

 snapshot6Login by username:admin and password:admin


Go a head and explore it.

More Information

OpenSIPS Compilation and Installation Troubleshooting On Fedora


OpenSIPS Installation

Here i will install OpenSIPS 1.11. To get more control over the installation process, I will compile the OpenSIPS from the source.

# cd /usr/local/src/

Get the latest release of OpenSIPS source from OpenSIPS’s GitHub repository:

Go to the place where “” is remotely storing OpenSIPS and get the OpenSIPS ‘s repo HTTP-address“. Then clone the repo.

# git clone -b 1.11 opensips_1_11

# cd opensips_1_11

Note: The option -b is used to choose the branch “-b 1.11”

Install the prerequisites needed to configure the compilation:

  • Flex and Bison needed for parsing of configuration file.
  • ncurses-libs, ncurses-devel, and ncurses-static for grafical display (text-based user interfaces).

Some prerequisites must be installed for GCC like Flex, Bison, TCl and others. If you could not compile, check what is missed in your system. Have a look here.

Open the configuration interface:

# make menuconfig

If you couldn’t open the interface and have an error like “Make error *255*“, this means  needed prerequisites are not all installed. You could also need  to try these:

  • Remove GCC and install it again:

# yum remove gcc

# yum install gcc

If you are patient, try to do the same thing with some broken installed prerequisites.

  • You could need to change the Makefile (In my case: “/usr/local/src/opensips_1_11/menuconfig/Makefile“). For example adding include (-I) and library (-L) paths.

$(CC) -o $(EXEC_NAME) $(CFLAGS) $^ -I/usr/include -L/usr/lib -lncurses

  • Still have a problem, do system restart.

The text-based user interface to configure and compile will look like this:

Here we can do the following

  • Configure some compile options used at OpenSIPS compilation time.
  • Compile and install OpenSIPS.
  • Cleanup OpenSIPS sources.
  • Generate OpenSIPS script
  • Exit and save all changes.

To get the features you want, go to the first menu and configure the compilation. You can select the modules you want to compile (“Configure Compile Options” –> “Configure Excluded Modules”). The selected modules here (marked with star *) will be included in the compilation of the OpenSIPS. Also you can configure the installation directories (“Configure Compile Options” –> “Configure Install Prefix”). It can be for example “/usr/local/opensips_1_11/”. Note: press q letter or left-arrow to go back to the previous screen.

After the configuration press on “Save Changes” to save the changes you did. After this you will get a message of the required libraries which must be installed according to the modules included in the configuration of the compilation (module dependencies). Go ahead and download them before compilation. Put the graphical interface in the background (press control-Z) or open a new terminal so you can see the names of the required libraries from the graphical interface and install them in the new terminal.

For example the module “db_mysql” needs mysql-devel (mysql client development library) to be installed.

Back to the interface and select “Compile and Install OpenSIPS” , then the compilation will start. It takes few minutes.

After the installation is completed, we get OpenSIPS installed as it is configured. In my case, it will be installed in “/usr/local/opensips_1_11/”. This directory contains these:

In “etc” we have the OpenSIPS configuration files.

In “lib” we have OpenSIPS modules

In “sbin” we have the executable files.

In “share” we have the documentation.

Create OpenSIPS Mysql Database

Install your database server. As an example install MySQL database server.

Now we are in “/usr/local/opensips_1_11/”

  • Configure the database parameters: Edit the configuration file “etc/opensips/opensipsctlrc”. This file contains the configuration of the database connection. # vim opensipsctlrc. Adjust the parameters like the name of the database, the read/write user that the opensips will be using, password, the database root user, and others.
  • Create the OpenSIPS database.Now back to “/usr/local/opensips_1_11/”. In the sub-directory /sbin we have opensipsdbctl tool. Use it to create the database. Here is the command and its output:

# ./opensipsdbctl create  

        MySQL password for root:

INFO: test server charset

INFO: creating database opensips …

INFO: Core OpenSIPS tables succesfully created.

Install presence related tables? (y/n): y

INFO: creating presence tables into opensips …

INFO: Presence tables succesfully created.

Install tables for imc cpl siptrace domainpolicy carrierroute userblacklist b2b registrant call_center? (y/n): y

INFO: creating extra tables into opensips …

INFO: Extra tables succesfully created.

opensipsdbctl tool takes its configuration from the file “etc/opensipsctlrc”


  • Install and configure mysqld as a system service:

# yum -y install community-mysql-server

       # systemctl start mysqld.service

       # systemctl enable mysqld.service

  • Check if its running: # ps aux | grep mysql
  • Default password is empty so only press “Enter” when asking for password. For security, set root password as following:

  mysql> set password for root@localhost=password(‘fedoracore2’);

Generate OpenSIPS Configuration File

The prerequisite is to install m4 package which comes by default with most Linux distribution. M4 is GNU macro processor and it is useful for writing text files which can be logically parsed.

Now we are in “/usr/local/opensips_1_11/”

Go to sbin and execute ./osipsconfig. You will get the text interface to generate the configuration file.


Three kinds of configuration files/scripts can be generated:

  • Residential scripts: If we have customers and we want to offer them certain services.
  • Trunking scripts: where we have PBXs and SIP trunks and we want to route the traffic.
  • Load-balancing scripts: Simple load balancer that can load the traffic between chosen destinations.

Example: Generating residential script (“Generate OpenSIPS Script” –> “Residential Script” –> “Configure Residential Script”) so we come to this page:


Here we can configure how OpenSIPs will work. After this configuration press “q” to go to the previous page then click on “Generate Residential Script”.


The generated script will be placed in the OpenSIPs etc folder (/usr/local/opensips_1_11/etc/opensips) marked with the date of its generation. Example: “opensips_residential_2014-9-25_12:30:52.cfg”. After the generation of the file we need to customize it little bit. For example fix the IP addresses and ports that the OpenSIPs will be working on. For example:

listen=udp: # CUSTOMIZE ME
Also customization of the places where DB connection is required. Example:

modparam(“siptrace”, “db_url”, “mysql://user:passwd@host/dbname”)
modparam(“usrloc”, “db_url”,”mysql://opensips:fedoracore2@localhost/opensips”) # CUSTOMIZE ME

Don’t forget to check the path of the installed modules: mpath=”/usr/local/opensips_proxy/lib/opensips/modules”

OpenSIPS Init Script

To make OpenSIPS works as system service, we need Init script. Follow these steps:

  • Go to the src folder : “/usr/local/src/opensips_1_11/packaging”
  • Here you have to select your system. For example if you have Fedora go to fedora sub-directory.
  • In that folder you will see the script opensips.init which is the actual init script. Copy this script to /etc/init.d/opensips and give it execution right.

# cp opensips.init /etc/init.d/opensips
# chmod +x /etc/init.d/opensips

  • Edit the script
    # vim  /etc/init.d/opensips

Here is a part of the script where there will be changes. The red line replace the line above it. Please see the corresponding to this in your system.









Include New Syslog Entry for OpenSIPS

  • Open the configuration file. In the Global Configuration section you will see the following :




          Change 0 to 1


  • Edit rsyslog.conf: #vim  /etc/rsyslog.conf
    Add this entry:   local1.*                        /var/log/opensips.log
  • Restart rsyslog daemon : #systemctl restart rsyslog OR  #service rsyslog restart
    All OpenSIPs log messages will be stored in this file /var/log/opensips.log

   By adding ““, the logging will be in Asynchronous mode so opensips will not wait until the messages are propagated.

Add Linux User and Group For OpenSIPS

Execute “# system-config-users”. Add user=opensips and create group=opensips for that user

Run OpenSIPS

The database server must be running before starting OpenSIPS. For example if the database server is mysql, check its status (# systemctl status mysqld.service) and run it if it is not running (# systemctl start mysqld.service).

To enable and start opensips as a system service.

# systemctl start opensips.service

# systemctl enable opensips.service

Check the file “/var/log/opensips.log” to see if everything is ok and no error messages (# tail -f  /var/log/opensips.log).

Example of an error message in the opensips.log:

ERROR:uri:db_checks_fixup1: configuration error – no database URL is configured!

uri” is the name of the module which has a problem.

Note: Problems which arise before the loading of the configuration file are still going to “/var/log/messages”.

Now the opensips should be running and we can check this by executing some commands:

♠ Check the status of the OpenSIPS’s service (i.e. Loaded and Running): #systemctl status opensips.service

♠ Check network’s state of the OpenSIPS server: # netstat -lpn |grep opensips

tcp 0 0* LISTEN 32634/opensips

udp 0 0* 32634/opensips

Note: OpenSIPS will not start on database init failure and it will exit immediately (return -1) on module initialization failure (calling the function “mod_init”).

Start/Restart OpenSIPS

To restart OpenSIPS, do the following:

# systemctl restart opensips.service


#  cd /etc/init.d/

# ./opensips restart

Start Working

Now after OpenSIPS has been installed successfully, you can start using its modules in the routing script. What i recommend when using any module:

  • Reading in the module documentation (Last Version). Note the section “Exported MI Functions” in the documentation of each module lists the module’s exported MI functions that can be called from outside of OpenSIPS (External applications). Example:

# opensipsctl fifo debug 1 

OpenSIPS project is growing quickly so please always read in the latest documentation.

  • Sometimes you need to look at the Database Schema. Some fields are pushed to database only when a specific module parameter is set. Example: In multi-domain scenarios, you might need to save the domain part of the user so the domain part and the username part are used to identify the user. So in this case you need to set the “use_domain” parameter of “usrloc” module to non zero value which means true.

modparam(“usrloc”, “use_domain”, 1)

More Information

Have a look at OpenSIPS


OpenSIPS is an open-source high performance SIP server. The picture below shows its internal architecture . OpenSIPS has modular architecture. Mainly consists of two parts:

  • The core – This part provides the low-level functionality. It includes so called internal libraries. They collect code shared by several modules.
  • The modules – are the components that provides the most of the functionality that make OpenSIPS powerful in real world deployments.

The architecture for OpenSIPS 1.X is shown in figure below.


Hairpinning, SIP loop, and Spiral

Here i would like to talk about: Hairpinning, SIP Spiral,  and SIP Loop.

  • Hairpinning: RFC 5128#section-2.10 defines hairpinning as following: ”If two hosts (called X1 and X2) are behind the same NAT and exchanging traffic, the NAT may allocate an address on the outside of the NAT for X2, called X2′:x2′. If X1 sends traffic to X2′:x2′, it goes to the NAT, which must relay the traffic from X1 to X2. This is referred to as hairpinning.”. Here is an example: Hairpinning
  • Spiral in SIP: as defined in RFC 3261: the condition where a SIP request routed to the proxy, forwarded onwards, and arrived again to that proxy, but this time differs in Request-URI. Example: call fowarding. Spiral is not considered as an error.
  • Loop in SIP: this is considered as an error. As in Spiral but when the request arrives the second time to the proxy, its Request-ID is identical to the first time. The proxy makes the same routing decision and we come to loop.

SIP Registration Process


The registration is a way to know the location (FQDN/IP address) of the SIP user-agent. The user-agent exchanges a set of SIP messages with the registrar/Proxy server to register its location in the server’s database. In addition to the user-agent location the registrar/proxy server can receive CPL (Call Processing Language) script.

RFC 3665 shows different registration scenarios: successful new registration, update of current registration, request for current contact list, cancellation of the registration, and unsuccessful registration. In this article i will explain only the first scenario (Successful New Registration).

Investigation of a Successful New Registration



Message F1 is explained in the figure below.

Register 1VIA header field defines 3 important informations: Transport, Last SIP Hop , and the Transaction-ID. In the previous figure we can see the transport as SIP/2.0/TLS. This means SIP messages will be secured carried by TLS transport. The last hop here is the The branch parameter in the VIA header field which is marked by star (*) in the figure, represents the identification of the current transaction. To be able to identify the transaction it must be unique across space and time for all requests sent by the user-agent except CANCEL and ACK for non-2xx responses. CANCEL has the same branch parameter as the request it cancels. An ACK for a non-2xx response will also have the same branch ID as the INVITE whose response it acknowledges. This is part of RFC 3261. Making the Branch parameter begins by the string z9hG4bK” means it is compatible with RFC 3261 regarding uniqueness property.

Each proxy adds its own VIA. The VIA header field is used for routing replies backward without DNS lookup.

Max-Fowards header field defines the maximum number of hops the SIP request can do.

From/To header field: From header field defines the user who initiates the request The ”display-name” is optional and it is used for rendering purposes on the human user-interface (GUI) of the user-agent. For example ”A is calling you” text appears on the screen of the calle.

To header header field represents the calle (user who receives the call). For example ”You are calling B” text appears on the screen of the caller. The From and To header fields are logical identities (AORs and optional display-names). NO IP addresses or FQDNs are allowed here since these are not logical. From and To header fields are not used in routing of the SIP messages.

The AOR (Address Of Record) in both From and To header fields is the same in the registration because registration is not a call.

The From-tag (the tag parameter in the From header field) with To-tag and Call-ID identify the dialog (peer-to-peer relationship between caller and calle).

Call-ID header filed identify the group of SIP messages (requests and responses) in the dialog. All must have the same Call-ID. Call-ID is calculated from random string and the phone’s hostname or IP address. This can not fully identify the dialog (the relationship between the caller and the calle) so we need “From-tag” and “To-tag”.

The generation of Call-ID is critical. The question is “When Call-ID must be globally unique ?”

The Call-ID must be selected by the UAC as globally unique over time and space if the new request is created outside any dialog.

CSeq header field used to order transactions within a dialog. Two CSeq header fields are considered equal if the sequence number and the request method are identical.

Contact header field contains SIP or SIPS URI that represents direct route to contact user-agent A. Usually it looks like: username@FQDN (Preferred) or username@IP-Address . For example: as shown in the figure but it can be also A@

You might have several SIP devices all registered under the same address of record (

Now we have finished the first message in the registration process (REGISTER F1).

F2: 401 Unauthorized

This response is shown in the figure below.

401unauthorized1WWW-Authenticate header field contains the authentication challenge sent by the server. It contains the information the user-agent needs to generate the checksum. The word “Digest” indicates the authentication scheme. The parameters are:

realm which is the associated protection domain,

qop (Quality of Protection) is optional. It can be either “auth” for authentication and “auth-int” for authentication and integrity.

nounce: unique string generated by the server.

opaque: optional, generated by the server to be returned in the subsequent requests.

stale: is flag and it is optional. It indicates if the nounce value in the previous request is stale.

algorithm:the algorithm used for checksum. It is optional and the default is MD5.


The user-agent generates what is called Authorization header and resend the original registration request (REGISTER F1) with the Authorization header field in it. The figure below shows REGISTER F3.

register-2Authorization header field involves mainly the response parameter which is the calculated checksum. The Cseq is 2 now since the request is considered new.

F4: 200 OK

If the authentication is success the server send 200 OK.

200ok1This way is the same way used in HTTP to authenticate the user. It is called WWW-authentication. There is another type of authentication used in SIP called Proxy-Authentication. Here the client receives 407 authentication challenge instead of 401.

Now other scenarios of the registration explained in the RFC 3665 will be easy to understand. Also other SIP Processes.

More Information

SIP as Peer-to-Peer distributed system


In SIP we have user-agents (clients and servers) and control-servers. The user-agents handle the signaling and media. The control servers handle only the SIP signaling. Using control-servers in peer-to-peer model serves the purpose of having more control over the sip cloud and doing some sort of translation on SIP message level. Having control means offering more services to the customers and getting more money (Business).

So how this model (Peer to Peer with control servers) looks like ?

As we see in the figure below the user-agent A sends its call (SIP control messages not the media) through its proxy (The proxy which is responsible for user A). You can call it the home proxy or the outgoing proxy or the mom proxy (for fun).

Remember i can ask my mom to do something for me at home but it is not suitable to ask my neighbor to do it for me. You got it !!! More control by the home proxy.

So the SIP as peer-to-peer model is not pure peer-to-peer model for signaling but it is pure peer-to-peer model for media.

DNS lookup: Each proxy has the IP addresses of  its own registered users in its local database. SIP registration process is done before SIP call establishment. When the local proxy wants to route a call (SIP message) depending on the R-URI (Requested URI) it asks the DNS server about the IP address of the targeted domain and forward the call to the IP address returned from DNS server which is the IP address of the Ingoing proxy.

More Information: What does ”Peer-to-Peer Networking” mean?

Aliases in VOIP Systems


Alias(General term): Not the real name. For example My real name is “Binan” as it is written in the civil registry. but you can call me “Beta” (alias) as people used to call. We see this in VOIP world and it is very useful when we don’t want to publish our real names. This gives very clever way to get this way of mapping between the real names and the aliases in the communication systems. The network nodes can do some sort of translation depending on some rules stored in the local database.


For example SIP proxy can store multiple SIP addresses for the same user: # Original-URI # Alias-URI # Alias-URI

The sip proxy does the translation of Alias-URI to Original-URI. This happens only by the proxy who is responsible for user (local user). The mapping between Alias-URI and Original-URI is stored in database. Both the username and the domain name in the URI can be aliased.

In OpenSIPS SIP server:

  • The alias’s module :
  • Database table name (default): dbaliases
  • The lookup is done on the R-URI (Requested URI).

Performance is better if memory caching is supported.

More Information

Linux Standard Network Service


Stop and Disable The Network Manager

To disable the NetworkManager and replace it with the standard network service, check the status of Network Manager:

# systemctl status NetworkManager

If it is running you have to stop and disable it.

# systemctl stop NetworkManager

# systemctl disable NetworkManager

Interfaces’ Configuration Files

The configuration files of the interfaces are exist in the folder “/etc/sysconfig/network-scripts/” and the name of each configuration file has this form “ifcfg-X” where X is the name of the interface. My interface name is “p4p2″ so i must have a configuration file named as “ifcfg-p4p2″. please check the names of your interfaces and the names of the corresponding configuration files.

Now open the configuration file of each interface and check the line for interface name. For example i have this line for my interface “NAME=p4p2″ in the file “ifcfg-p4p2″. To automatically make the interface activated after booting, add this line to its configuration file “ONBOOT=yes”. If the access point uses DHCP, write BOOTPROTO=”dhcp” instead of static.

Note: If the interface configuration file name is not same as the name of the interface, simply change it. The same for the interface name inside the configuration file and other parameters.

Example of Configuration File

Ethernet Interface “p4p1”, Configuration File: “/etc/sysconfig/network-scripts/ifcfg-p4p1”


Enable & Start The Standard Network Service

Take all interfaces down. For example to take the interface p4p2 down, execute “ifdown p4p2“.

Now we can start and enable the standard network service:

# systemctl enable network

# systemctl start  network

Type “systemctl status network” to check the status of the network service and “ifconfig” to check the interfaces state.

More Information