Compilation, Installation, and Configuration of OpenSIPS’s Perl Module

.

If you want to implement a new feature (i.e. not exist in OpenSIPS), you can extend OpenSIPS by either writing new module (in C) or writing Perl script and call it within the routing script using OpenSIPS’s Perl module. In this article i will explain how to compile, install and configure OpenSIP’s Perl module. Then you will be ready to write your own extension.  To do that, follow these steps.

Installation of “ExtUtils::Embed” Perl Module

It is Perl module used for embedding Perl interpreter and extensions in C/C++ (i.e. Cross Compiling). To install this module on Fedora: #yum install perl-ExtUtils-Embed. The Makefile of the application can call functions from this module while building the application. In OpenSIPS, we will call the functions manually and set the results in environment variables accessed by the Makefile. One of these functions is “ldopts” which gives the GCC ‘s arguments for linking the perl library to  C/C++ application (Perl is dynamically linked to OpenSIPS). You can call this function as following:

# perl –MExtUtils::Embed –e ldopts.

Set the option -M to specify the module name which is “ExtUtils::Embed” and the option -e to call the function “ldopts”.

Pre Compilation Procedures

OpenSIPS is C application. C is a compiling language whereas Perl is a scripting language with C++ interpreter. OpenSIPS uses Perl interpreter and extensions in its Perl module to Parse/Load/Execute Perl scripts. So we need  to prepare  GCC (C/C++ compiler) to be able to compile OpenSIPS’ s Perl module. In this tutorial i am using perl (v5.18.4) and GCC (v4.8.3) on Fedora 20.

  • Execute the command #perl -MExtUtils::Embed -e ldopts.

In my case the output is:

-Wl,–enable-new-dtags  -fstack-protector  -L/usr/lib64/perl5/CORE -lperl -lresolv -lnsl -ldl -lm -lcrypt -lutil -lpthread -lc

Assign the output to the environment variable PERLLDOPTS:

#export PERLLDOPTS=-Wl,–enable-new-dtags  -fstack-protector  -L/usr/lib64/perl5/CORE -lperl -lresolv -lnsl -ldl -lm -lcrypt -lutil -lpthread -lc.

To make this permanently, edit the file “.bash_profile” and write the previous export statement there. Check its value: # echo $PERLLDOPTS

  • Execute the command #perl -MExtUtils::Embed -e ccopts.

In my case the output is:

-D_REENTRANT -D_GNU_SOURCE -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64  -I/usr/lib64/perl5/CORE

Assign the output to the environment variable PERLCCOPTS. Check its value : # echo $PERLCCOPTS

  • Execute the command : #echo “`perl -MConfig -e ‘print $Config{installprivlib}’`/ExtUtils/typemap” and assign the output to environment variable TYPEMAP.
  • OpenSIPS’s Makefile is already prepared for cross compilation. It will recognize these variables. For example “Makefile.defs-> CROSS_COMPILE ?=” will include PERLCCOPTS‘s value (DON’T DO ANYTHING).

Notes:

  • If you write these variables in bash profile (.bash_profile), you must reload the file: # source .bash_profile
  • See the corresponding procedures in your system.

Compilation & Installation of OpenSIPS’s Perl Module

  • If you don’t have OpenSIPS yet, have a look  here. Include Perl in the compilation (i.e. Click on “Configure Compile Options” –> “Configure Excluded Modules”. Then compile the OpenSIPS by selecting “Compile and Install OpenSIPS”. This will not rebuild everything only the new selected modules.

OR

From the OpenSIPS ‘s src  folder (“/usr/local/src/opensips_1_11”), execute:

#make include_modules=”perl”modules

# make install

  • To see if the module is compiled and installed , check the Perl module path “/usr/local/opensips_1_11/lib64/opensips/perl/”. Check also Perl.so in the OpenSIPS’s C modules path: In my case  “ /usr/local/opensips_1_11/lib64/opensips/modules/“.

Configuration of OpenSIPS’s Perl Module

♣ The module “Perl” must be loaded in OpenSIPS’s routing script (i.e. the configuration file) after loading the module “sl”.  To load the module, write this statement:

loadmodule “perl.so.

♣ Set the name of the new extension (i.e. the name of your Perl script):

modparam(“perl”, “filename”, “/usr/local/opensips_1_11/Your-Extensions-Folder/Name-Of-Your-Script.pl”)

♣ Set the module path

modparam(“perl”, “modpath”, “/usr/local/opensips_1_11/lib64/opensips/perl/”)

♣ Restart OpenSIPS: #systemctl restart opensips.service

♣ Check the permission to execute the script: # ls -l  /Path-To-Your-Script/Name-Of-Your-Script.pl. (  use “chmod +x” to give it execute permission).

♣ Use “strace”  to debug the script execution. # strace file Name-Of-Your-Script.

Writing a New OpenSIPS ‘s Perl Extension

Later i will write a Perl script that extend the feature “Advice of Charge (AOC) in SIP”. If you are in hurry you can go here and see an example ( Replace 183 early media reply with 180 (Ringing)). Now you can write your Perl script and call functions from OpenSIPS’s Perl module. For example the package Message  provides access functions for an OpenSIPS sip_msg structure. For example calling the function getRURI() gives the Request-URI of the current message.


More Information


Advertisements

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 “GitHub.com” is remotely storing OpenSIPS and get the OpenSIPS ‘s repo HTTP-address https://github.com/OpenSIPS/opensips.git“. Then clone the repo.

# git clone https://github.com/OpenSIPS/opensips.git -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.

all: $(MENUCONFIG_FILES)
$(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”

Notes

  • 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.

snapshot3

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:

snapshot4

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”.

snapshot5

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:10.0.0.4:5060 # 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.

prog=opensips

opensips=/usr/sbin/$prog

opensips=/usr/local/opensips_1_11/sbin/$prog

cfgdir=”/usr/local/opensips_1_11/etc/$prog”

pidfile=”/var/run/$prog.pid”

lockfile=”/var/lock/subsys/$prog”

configfile=”/etc/$prog/$prog.cfg”

configfile=”$cfgdir/opensips_residential_2014-9-25_12:30:52.cfg”

Include New Syslog Entry for OpenSIPS

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

          debug=3

          log_stderror=no

          log_facility=LOG_LOCAL0

          Change 0 to 1

          log_facility=LOG_LOCAL1

  • 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 127.0.0.1:5060 0.0.0.0:* LISTEN 32634/opensips

udp 0 0 127.0.0.1:5060 0.0.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

or

#  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