OpenSIPS Module Interface – Part 2 (C Development)

.

Introduction

This is Part 2 of the topic “OpenSIPS Module Interface”. In Part 1,I have talked about the definition of the module interface, some fields of its structure, and how to export function from the module to the routing script. So you can call this function in the routing script. Also i have talked about how to export a module parameter. I have talked about the OpenSIPS management interface in the article “OpenSIPS Management Interface (C Development)“. In this article, i will explain a little bit in the module interface and i will show you how to compile a new module.

The definition of the module interface is defined in the header file: “sr_module.h” as following:

struct module_exports {.

……… /* Fields that are explained in the Previous Article are missed here*/

……..  /* Some other fields are missed to be explained in the Next Article */

init_function   init_f;                              /* Initialization function */

destroy_function destroy_f;                /* Function called when the module

.                                                                       should be “destroyed” */
.child_init_function init_child_f;            /* Function called by all processes after the fork */

}

init_f function which will be called at OpenSIPS startup time. In OpenSIPS 1.x which is multi process application, this function will be called when OpenSIPS is just one process (attendant process). For example checking for the database connection can be done here or allocating a memory that will be as shared memory for the forked processes (after forking). You can define your init_f function in the “exports” which is the actual module interface. Lets say “mod_init” is the initialization function in the module interface:

static int mod_init(void){

……

}

The initialization of the exported variables in the routing script will be done before calling the function mod_init. The full OpenSIPS configuration file will be parsed and the own module parameters will be included. For example the parameter “db_url” which will be configured in the routing script:  modparam(“module_name”,”db_url”,”mysql://user:passwd@host/database”) and the “db_url” will be evaluated and can be used in the function “mod_init”. So a connection to the database can be opened in the body of the “mod_init” function.

Also the helper API like shared memory, locking, timer, ..etc. will be available and can be used. Note some resources like new timer processes for the module can only be initialized in the “mod_init” function.

After forking, each process will get a copy of what the OpenSIPS attendant process had before forking (structures/connections).

init_child_f function will be called after OpenSIPS has been forked (It will be called by each process individually). For example if each process will have its separate DB connection, the creation of the DB connection will be in this function.

static int child_init(int rank){

……..

}

The rank parameter allows you to know which process is calling the function. For example it can be called from SIP worker or MI worker (e.g. fifo worker).

destroy_f function will be called when OpenSIPS will shutdown. Here you can do some cleaning of resources(memory, DB connections, and so on). For example you can free the memory for some module-created variables (e.g. pkg_free(Pointer to the Variable)). OpenSIPS 1.X has its own internal memory manager and the function pkg_free is like the function free(pointer to a variable) of glibc standard library. The pointer must not be null otherwise it will crash. Also here in this function, you can save a state that the module have into persistent storage so they can be loaded again at the next OpenSIPS startup. For example in this function, the “dialog” module saves the dialog states in the database.

OpenSIPS 2.X is multi thread application. I will back to it in one or two upcoming articles.

Add Include Directives

You need to add the include statements to the new module code to be able to compile it. For example: the “string.h”, “sr_module.h” which includes the definitions of the structures, “dprint.h” which is used to print stuffs to the syslog or standard error, “mem.h” which is used to allocate/free a memory, and the header file which contains the structures of the new module (e.g. new_module.h).

How to Compile a New OpenSIPS Module

Each OpenSIPS module has its own regular Makefile. It will be run by the master Makefile. The file name is “Makefile” and its content looks like this:

include ../../Makefile.defs
auto_gen=
NAME=new_module.so
LIBS=

include ../../Makefile.modules

The “Makefile.defs” must be included from the OpenSIPS source folder in addition to the name of the shared object “new_module.so” which will be generated and the file “Makefile.modules”. If the module has external libraries dependencies, they should be linked in the module’s Makefile.  Here we have two Makefile variables:

  • DEFS: This is used if the module has additional definitions that you want to pass it to the compiler. Add this line to the module’s Makefile if the module has additional definitions:

DEFS+=-I$(LOCALBASE)/include

OR DEFS+=-I../../../exdef/include

+= is a Makefile operator.

  • LIBS: This is if the  module requires external libraries. So these options:  -llibrary and the -Lpath_to_library will be set to LIBS variable. For example for “cachedb_memcashed module”, add this line to the module’s Makefile:

LIBS=-L$(LOCALBASE)/lib -lmemcashed

To compile the module:

  • The module source files (.c and .h files) and the Makefile should be in the folder “/usr/local/src/opensips_1_11/modules/new_module”
  • From the OpenSIPS ‘s src  folder (“/usr/local/src/opensips_1_11″), execute:

# make include_modules=”new_module” modules OR # make modules modules=modules/new_module

# make install

  • To see if the module is compiled and installed , check having the file “new_module.so” installed in the subdirectory “/usr/local/opensips_1_11/lib64/opensips/modules/“.

Testing

Write log statements (e.g. LM_INFO(….)) in the C code of the new module. Compile it , and restart opensips. Open the log file and search for the name of the module (for example search for “new_module”) to see what is happening to the module “new_module”.


Notes

1- If you’ve got a compilation error (e.g “….. No rule to make target ….”) and you want to clean everything (delete the generated object files and dependencies files (files with extensions “.d”), execute “make proper” and then “make”.

2- If the module depends on external libraries, the module must NOT be compiled by default. To disable this, we edit the file “Makefile.conf.template” which specifies the modules that are not compiles by default.

  • Add a line for your module in “Makefile.conf.template” file in this format:

modulename= Module-Description | module-dependency

For example for the “xcap” module:

xcap= XCAP utility functions for OpenSIPS. | libxml-dev

  • Add the module name to “exclude_modules” list in “Makefile.conf.template” file.
  • After this compile the module as explained in this article.

3- Each OpenSIPS ‘s module has a section in its documentation called “Dependencies -External Libraries” which contains the external libraries that must be installed for this module.


Next

I will continue explaining the module interface.

More Information


Advertisements

OpenSIPS and SIP PATH Extension

.

Introduction

RFC 3327 (SIP Path Extension) specifies a way to discover and record the sequence of proxies between the UA and the registrar. The constructed routing path will be stored in the database of the registrar along with the corresponding contact address. Each intermediate proxy (NOT terminating routing point) that wants to stay in the routing path, inserts its URI as a new “Path” header field (or as value in the “Path” header field). This mechanism is applied only to requests that are transiting or originating in the home domain. The constructed routing path will be carried as pre-loaded Route set in the upcoming initial requests. This mechanism is similar to the operation of Record-Route mechanism in dialog-initiating requests (In-dialog/Sequential requests) and it can be combined with it (Example – Invite Transaction).

In this article i will talk about SIP Path extension in OpenSIPS context.

Example

Assume we have this scenario:

UA1 – – – – P1 (Outbound Proxy) – – – – P2 – – – – Registrar/Home-Proxy (OpenSIPS) – – – – UA2

The outgoing proxy is the first hop after client’s NAT . The home proxy is a terminal point for SIP routing. The requested path starts by the outgoing proxy and ends at the registrar/home proxy. It is not common that the UA adds a “Path” header field in the request.

OpenSIPS As Registrar/Home-Proxy

OpenSIPS “Registrar” module has “Path” support. When OpenSIPS receives a SIP Register request, it calls the function save(..), among others. Upon calling this function, the values of the Path header(s) along with the contact address will be stored in the database (User Location Table). The contact address will be stored in the column “contact” and the values of Path header(s) will be stored in the column “path”.

In our scenario, if the proxies P1 and P2 receive a Register request and want to be in the path vector, each one adds its own SIP address as a top most value in the “Path” header field and forward the request. When the request reached the registrar, the path vector will be: Path: <sip:P2.testdomain.com;lr>,<sip:P1.testdomain.com;lr>.

The function save(…) takes some flags as a single string parameter. Among others, we have these flags that are related to the “Path” support:

  • p0‘ (OFF Mode): The path vector will be saved in the user location table but it will not be included in the reply of the Register request.
  • p1‘ (Lazy Mode): The path vector will be saved in the user location table and it will be included in the reply only if the UA indicated path support in the request (add the tag “path” as a value in the “Supported” header field of the request: “Supported: path”).
  • p2‘ (Strict Mode): The path vector will be saved in the user location table only if the the UA indicated path support in the registration request (add the tag “path” as a value in the “Supported” header field of the request). If it is not indicated, the request is rejected with “420 – Bad Extension” and the header “Unsupported: path” will be included in the reply along with the received path vector.

The flags above enable “path” support in “registrar” module and specify the mode of this support as well.

According to all above and if the path vector {p2,p1} is sent in the response, the UA can use the path (as preloaded Route set) in the future requests if that is allowed by the policy. In addition to this, any request reached the home proxy can be routed based on that path {p2,p1} which is stored in the database of the registrar.

According to RFC 3327:

The intermediate proxies (not terminating points) should not add a “Path” header field to a request unless the UA add the tag “path” as a value in the “Supported” header field in that request. Here we say the UA indicated support for PATH extension. If the UA indicated path support and the intermediate proxy requires path support in the registrar, then the proxy adds the tag “path” as a value in the “Requires” header field in that request. If the UA has not indicated support for path and the proxy requires support for it in the registrar, the proxy should reject the request with 421 response. This nearly corresponds to using the flag ‘p2’ in the “save” function: save(“location”,”p2″).

The “save(…)” function has also flag ‘v‘ (path received). If this flag is set, the “received” parameter of the first Path URI of a registration {p1} is set as received-uri and the NAT branch flag is set for this contact. This will be explained further down.

To use multiple flags in the “save(…)” function, mix them as one string. Example: save(“location”,”p2v”).

The routing script will have these lines, among others:

….

if (method == “REGISTER”) {

save(“location”, “p2v”);
}

Registrar’s Lookup Operation

When for example UA2 wants to call UA1 (Send Invite request). When the request reached OpenSIPS that operates as a registrar/home proxy, it looks up (Call the function lookup(..)) the AOR of UA1 (UA1@testdomain.com) and returns:

  • Contact = <sip:UA1@192.18.8.10>

  • Path vector= <sip:P2.testdomain.com;lr>,<sip:P1.testdomain.com;lr>

The Request-URI is overwritten by the registered contact address and the Path vector {p2,p1} is inserted as Route set in the same order {p2,p1} in the outgoing Invite request. The topmost Route header field (proxy: p2) is used for routing decision (next hop) in conjunction with the local policy. Calling this function, also sets the destination URI to the first Path URI (outbound proxy: p1).

OpenSIPS As Outbound Proxy with NAT Detection

OpenSIPS has a module named “path” which is designed to be used at intermediate SIP proxies (e.g. outgoing proxy, load balancer,..etc.). Assume we have this scenario:

UA1 – – – NAT – – – P1 (Outbound Proxy -OpenSIPS) – – – P2 – – – Registrar/Home-Proxy

P1 is OpenSIPS that operates as outgoing proxy with NAT detection. To use “path” module, it must be configured in the routing script to be loaded at startup (loadmodule “path.so”). The module “rr” must be loaded before so it must be configured to be loaded before. To insert a path header into Register message, two functions are exported by this module:

  • The function “add_path(…)” which adds a path header in this form “Path: <sip:1.2.3.4;lr>” .The IP address is the IP address of the proxy’s outgoing interface. A port is only added if it is not the default (5060). If it is called with username as parameter, then the username will be added to the URI “Path: <sip:username@1.2.3.4;lr>“.
  • The function “add_path_received(…)” which adds a path header in this form:

Path: <sip:1.2.3.4;received=sip:2.3.4.5:1234;lr>

In our scenario, the outbound proxy p1 will call the function “add_path_received” upon receiving a Register message. The received parameter of its Path URI contains the address where the request has been received (NAT’ed address). This is used to pass the NAT’ed address to the registrar through the next proxy if exists. If it is called with username then the username is added to the URI: “Path: <sip:username@1.2.3.4;received=sip:2.3.4.5:1234;lr>“. Then the proxy will forward the message further to next hop on a way to the registrar.

If the parameter “use_received” exported from “path” module is set to 1 by the outgoing proxy (modparam(“path”, “use_received”, 1), then when the proxy receives a request, the “received” parameter of the its Route URI  (first Route URI ) is evaluated and used as destination URI(route the request to this address).

This behaviour of outbound proxy is considered as complement to registrar behaviour (SIP Path Extension-aware behaviour of Save(…) and Lookup(…)). So Keep the outbound proxy in the constructed path.

The routing script will have these lines, among others:

loadmodule “path.so”

modparam(“path”, “use_received”, 1)

if (method == “REGISTER”) {
if (!add_path_received(“Outbound”))
sl_send_reply(“503”, “Internal Path Error”);

}


Notes

  • SIP “Path” extension is very useful for SIP loadbalancers that are in front of registrars and proxies. As it helps in drawing SIP routing paths.
  • If you like to manipulate the “received” parameter of the Path URI by yourself in the script (not recommended), you can use the script core variables: $Ri which is the IP address of the interface where the request has been received and $Rp which is the port number. Informations like these are detected by the transport of OpenSIPS (under the SIP layer).
  • If you do not understand the structure of the SIP URI. Go Here.

 More Information


Regular Expressions For SIP Trunk

.

Introduction

The regular expression is a sequence of characters that form a search pattern. See the definition in Wikipedia. It is a huge topic and takes a lot of time to explain. If you didn’t use it, you will get stuck in a nested “If” statements situation. Using regular expressions means professionalism. I am assuming you know about it and i will just apply it to SIP.

.

Regular Expressions For a SIP Trunk

Usually when a SIP router receives a SIP request which is addressed to a PSTN gateway (i.e. Its Request-URI contains a telephone number), it checks which group the requested user (called party) belongs to. The router also must check if the caller has permission to make this call. So the check can be done on the caller and calle. Any check done by the router is translated into this simple thinking logic:

If (Routing Condition){

  Do Specific Work

}

This can be in the router’s routing script or internally integrated in the router’s application.

Example

If (The Call Is Addressed To A Local Number){

Do Specific Work

}

In OpenSIPS SIP router, the previous condition can be treated in the routing scripts in two ways:

  • Using the Script Variables (e.g. the reference to the request’s uri ($ru)) with the regular expression directly:

If ($ru=~sip:[2-9][0-9]{6}@){

}

The previous regular expression is for any 7 numbers starting by one digit from the range [2-9].

  • Using a function like “pcre_match” in “Regex” module which matches the given string against a given regular expression. The return value is TRUE if it is matched, FALSE otherwise:

If (pcre_match(“$ru”,sip:[2-9][0-9]{6}@){

}

The variable “$ru” is read/write variable so be aware where in the script you are checking its value. You can use “$ou” which is a reference to the request’s original URI. The module “Regex” is based on the library “PCRE” which is an implementation of regular expression pattern matching where the regular expression parameter will be compiled in PCRE object. So the development libraries of “PCRE” must be installed (“libpcre-dev” or “pcre-devel”).

Note: Use “&&” if you want to concatenate multiple conditions in one “if” statement.

If ((Routing Condition-1) && (Routing Condition-2)){

  Do Specific Work

}

Examples of Regular Expressions For SIP Trunk

You should test your regular expression before using it to know if you have constructed it correctly. There are many online free services that you can use to do your tests. Use search engines to search for syntax symbols that you can use to construct the regular expression. The following are examples. Note that each one defines a group:

  • Any user on any domain/IP: sip:(.*)@(.*)
  • Any user on certain domain: sip:(.*)@mydomain.com
  • Any user on certain IP (198.18.250.10):  sip:(.*)@198\.18\.250\.10 In regular expression, the “.” is interpreted as “any character” symbol whereas “\.” is just a period (dot).
  • Any user on IP Range (198.18.250.0 – 198.18.250.255): sip:(.*)@198\.18\.250.* The symbol “*” is quantifier which means the preceding character is found 0 or more times. Here i left the last part of IP to be anything but you can restrict it.
  • To group a set of SIP URIs that are within a certain domain or certain subdomain, use .*mydomain\.com.* For example these URIs will be matched: sip:mydomain.com:5060;transport=tcp, and sips:test.mydomain.com:5061 SIP/2.0
  • To group a set of SIP URIs that have certain string in the username part of URI and the ports 5060 and 5061 are accepted, use the regular expression .*group1@198\.18\.250.\10:506<01>.* For example these two URIs will be matched sip:serv1group1@198.18.250.10:5060;transport=tcp and sips:serv2group1@198.18.250.10:5061;tranport=tcp
  • 8-digit number on any domain: sip:[0-9]{8}@(.*) The [0-9] is a range for one number between 0 and 9 and {8} means repeat the preceding number 8 times.
  • 8-digit number starting optionally by 8 on any domain: sip:8?[0-9]{7}@(.*)  The symbol “?” means the repetition is 0 or 1 to the preceding. For example sip:80986853@mydomain.com, sip:0986853@mydomain.com, 1234567@mydomain.com, and so on.
  • 4-digit number (could be an extension number) starting by 6 on a certain domain: sip:6[0-9]{3}@(.*)
  • 4-digit number which is not starting by 55 on any domain: sip:(?!55)[0-9]{4}@(.*)

 More Information


OpenSIPS Management Interface (C Development)

.

Introduction

OpenSIPS Management Interface (MI)  is a mechanism which enables the external application (e.g. command line :opensipsctl , web: OpenSIPS-CP) to send commands (MI commands) to OpenSIPS. It is a pull based mechanism which means when you need information you need to query OpenSIPS (i.e. need to do something at a certain time). The MI command allows you to fetch/push data from/to OpenSIPS or trigger some actions there. The core has its own exported MI functions and the module has its own as well. Here you can find some examples of sending mi commands by the external applications “opensipsctl” and “OpenSIPS-CP”

Several transport protocols are used to carry MI commands and their replies between the external application and OpenSIPS. Each protocol is provided by separate OpenSIPS module. The current protocols are mi_fifo, mi_datagram, mi_xmlrpc, mi_http, mi_json, and mi_xmlrpc_ng. These modules require extra processes to avoid disturbing OpenSIPS main processes that are working with SIP.

The module must be loaded (i.e. configured to be loaded in the routing script) so its exported MI functions (exported by the module interface “exports”) are populated and can be called from the external application otherwise you will get an error message “500 command ‘Module_Name’ not available”. To be able to send MI command from the external application, the transport module also must be configured in the routing script to be loaded. For example if you want to connect to MI interface via FIFO file stream, the module MI_FIFO must be right configured and loaded. The same for the rest of transport protocols.

So two modules are needed to be able to call a specific MI function:

  • The module which exports the MI function.
  • The transport protocol which will transport the command to OpenSIPS.

The extra processes that are required for transport issues will be listening on different ports than the SIP ports. OpenSIPS can use multiple transport protocols at the same time (In the routing script, configure them to be loaded).

MI Command Syntax

If you are willing to write an external management application, you have to implement the transport you want to use. Your application will behave like a client which sends MI command in a specific format to OpenSIPS. These are the current formats:

MI Internal Structure

The following is the module_exports structure (Module Interface) defined in the file “sr_module.h” with the parts related to MI.

struct module_exports {.

……… /* Many Fields are Missed For Simplicity */

mi_export_t*     mi_cmds;           /* Array of the exported MI functions */

….

proc_export_t*  procs;     /* Array of the additional processes required by the module */

……

}

procs

Sometime the module needs extra processes like the transport protocol. So it exports

  • The number of required processes to be forked (“no” number).
  • The helper functions (pre_fork_function and post_fork_function) which help the attendant process to create the extra processes.
  • The function which will be executed by the extra processes. What will be done by these extra processes will not interfere with the rest of processes that handle the SIP.

The structure is defined in the file “sr_module.h” in OpenSIPS source directory:

typedef struct cmd_export_ cmd_export_t;

struct proc_export_ {
char *name;
mod_proc_wrapper pre_fork_function;
mod_proc_wrapper post_fork_function;
mod_proc function;
unsigned int no;
unsigned int flags;
};

typedef void (*mod_proc)(int no);

typedef int (*mod_proc_wrapper)();

The flags can be 0 or PROC_FLAG_INITCHILD. If PROC_FLAG_INITCHILD is provided, the function “child_init” from all modules will be run by the new extra processes.

Example of procs NULL terminated array:

static proc_export_t mi_procs[] = {
{“MI Datagram”,  pre_datagram_process,  post_datagram_process,
datagram_process, MI_CHILD_NO, PROC_FLAG_INITCHILD },
{0,0,0,0,0,0}
};
static param_export_t mi_params[] = {
{“children_count”,      INT_PARAM,    &mi_procs[0].no},…….}

mi_cmds

mi_cmds is an array of exported MI function (Type: mi_export_t*). The definition of the type “mi_export_t” is included in the file “mi/mi.h” as following:

typedef struct mi_export_ {
char *name;
char *help;
mi_cmd_f *cmd;
unsigned int flags;
void *param;
mi_child_init_f *init_f;
} mi_export_t;

name is the actual name of the MI function which will be called. help is the information about what this function is doing. cmd is a pointer to the actual mi function:

typedef struct mi_root* (mi_cmd_f)(struct mi_root*, void *param)

The return value is mi_root * (pointer to the root of the MI reply tree).  The first parameter is the MI root parameter(type: mi_root *) and the second parameter is the actual command parameter (void *). the param is the actual parameter of the MI function.

init_f is the child init function for the exported MI function. In some parts, some extra stuffs are needed to be done by the MI workers (processes that are handling the MI requests  like MI_FIFO proces, MI_XMLRPC process,….. This function will be called at the startup after OpenSIPS has been forked (will be called one time by each core process individually).

Example of MI functions NULL terminated array:

static mi_export_t mi_cmds[] = {
{ “mi_get_function“,”This Function is doing bla bla”,mi_get_function,MI_NO_INPUT_FLAG,0,0},
{0,0,0,0,0,0}
}

The string “mi_get_function” is the actual name of the mi command which will be named by when MI command is received and needed to be verified (lookup_mi_cmd(MethodName,..)). The actual function will be like this:

struct mi_root* mi_get_function(struct mi_root*  root, void * param){

……..

}

MI Function Reply Tree

The return value of MI function is a pointer to a tree (reply tree) . The root of this tree is pointer to struct mi_root. This structure is defined in the file “mi/tree.h”:

struct mi_root {
unsigned int  code;
str   reason;
struct mi_handler  * async_hdl;
struct mi_node node;
}

The code is the root code of the response (200 for sucess,500 for error, …) and the node is the starting node (type: mi_node defined in the same file “mi/tree.h”):

struct mi_node {
str value;
str name;
unsigned int flags;
struct mi_node *kids;
struct mi_node *next;
struct mi_node *last;
struct mi_attr *attributes;
}

To initialize MI reply tree in the previous MI function (mi_get_function), the function “init_mi_tree” can be called. To add child node, the function “add_mi_node_child“. To add attribute, the function “add_mi_attr” is called  and so on. Here you can find an example code where a reply tree is built when a MI function is called.

struct mi_root* mi_get_function(struct mi_root*  root, void * param){

………

struct mi_root * rpl_tree = init_mi_tree( 200, MI_SSTR(MI_OK));    /* 200 OK Reply */

……..

}

The transport process like datagram_process, xmlrpc_process,..etc  behaves as a server which accepts connections (UDP connections in case datagram transport , TCP connections in case xmlrpc connections and so on). To serve the MI request, the transport process calls functions from OpenSIPS core (Management Interface: “mi/mi.h”) in addition to some module-defined functions.

When the message is received, the transport process checks if the requested MI function is available (looks up the MI command):

struct mi_cmd*  fu =lookup_mi_cmd((char*)methodName, strlen(methodName))

The “lookup_mi_cmd” is defined in “mi/mi.h”. If “f==0”, the MI command is not available. Otherwise it parses the parameters of the requested MI function into a MI tree. For example in xmlrpc, the function “xr_parse_tree” is defined in the file “modules/mi_xmlrpc/xr_parser.h” and called in “modules/mi_xmlrpc/xr_server.c”. It returns a pointer to the reply tree (mi_root * t).

After this, the actual mi function will be called through the function “run_mi_cmd”. As i explained above the return value of the MI function (reply tree) has the type mi_root*. This is how it is called in xmlrpc transport module “”.

struct mi_root*  mi_rpl=run_mi_cmd( fu , t , (mi_flush_f*)xr_flush_response,env))

The function “run_mi_cmd” is defined in the file “mi/mi.h” and in its body you call the actual MI function as following:

static inline struct mi_root* run_mi_cmd(struct mi_cmd *cmd, struct mi_root * t, mi_flush_f *f, void *param){

struct mi_root *ret;

…..

ret = cmd->f( t, cmd->param);

…..

}

struct mi_cmd {
int id;
str module;
str name;
str help;
mi_child_init_f *init_f;
mi_cmd_f *f;
unsigned int flags;
void *param;
};

Then the reply tree mi_rpl  (Type: mi_root *) will be formatted corresponded to the transport process (transport protocol). For example if the protocol is xmlrpc, then the reply tree will be formatted in xml either as string that contains the name and attributes of each node OR as an array where each element contains a node information (node name and its attributes). Each attribute has name and value.

Finally, the response will be written in fifo file, UDP socket (datagram transport), TCP socket (xmlrpc transport) so it will be sent to the external application.

Test MI Function of a New Module

You can test the MI command by using opensipsctl as following:

# scripts/opensipsctl fifo mi_get_function


 Note

  • The OpenSIPS core MI exported functions (mi_core_cmds) are defined in the file “mi_core.c”.
  • The OpenSIPS Module MI exported functions (mi_cmds) are defind in the file modules/Module_Name/Module_Name.c
  • OpenSIPS has many transport modules. Go to “modules/mi_Transport“, Where Transport can be datagram, xmlrpc, json,…etc.

 More Information


Linux Tuning For SIP Routers – Part 3 (Memory)

.

Introduction

This is Part  3 of “Linux Tuning For SIP Routers” topic. In Part 1 i have talked about Interrupts and IRQ Tuning. In Part 2 i have talked about File System Tuning, Journaling File System, and Swappiness . In this part i will talk about OOM killer, Private Momory, and Shared Memory Tuning.


Out-Of-Memory (OOM) Killer

Linux kernel uses Out-Of-Memory (OOM) killing technique to recover the memory in “out-of-memory” situation. The OOM killer will select one or more processes to kill. You can make a specific process less likely to be killed by the OOM killer as following:

# echo -15 /proc/PID/oom_adj  where the PID is the process ID and oom_adj represents how likely is the process to be killed. oom_adj takes values between -16 to +15. Setting oom_adj to -17 exempts the process entirely from the OOM killer.

To know how likely is a process to be killed, view the content of the file “oom_score”:

# cat /proc/PID/oom_score


Private Memory (Per Process Memory) Settings

Check if there is any memory limitation for a user process. The command “ulimit -a” display the limitations on all resources not only the memory. Use the option -m to display the max memory size:

# ulimit -m

The output: unlimited

The command “ulimit” is built into the bash shell and used for read and write the limitations on the resources available to the shell and the processes started by it. The system must allow such control on the resources.

What remained is configuring the private memory of SIP router’s process. See the example below:

Example: Tuning the Private Memory of OpenSIPS Process

OpenSIPS private memory (file: mem/mem.h) is a memory dedicated to each process and used for process own business like building buffer for sending SIP message. The default size of private memory used by each OpenSIPS process is 1 MB. Common cases that need large private memory are loading user location contacts and doing NAT pinging. You can set the size of private memory (in megabytes) at startup by using the command parameter -M:

# ./opensips -M 10


Shared Memory Settings

The shared memory is memory shared between processes. The data that are stored  in the shared memory can be accessed by many processes. You need to care about shared memory if your SIP router is multi process and the processes/threads from different processes share some data. To see the shared memory settings in your system, type: # ipcs -lm

—— Shared Memory Limits ——–
max number of segments = 4096
max seg size (kbytes) = 32768
max total shared memory (kbytes) = 8388608
min seg size (bytes) = 1

Usually the SIP router has its own memory manager which allocates and frees the memory offered by the operating system between its processes. So tuning the memory involves tuning the memory at the operating system level and at the router level. Linux as an operating system has some parameters that you can configure:

SHMMAX Parameter

It is the maximum size (in bytes) of a single shared segment that a Linux process can allocate in its virtual address space. The value of this parameter depends on whether you are using 32 bit system or 64 bit system (size of the available address space).

What to do

  • Check your system (# uname -a): I am using Fedora Red Hat SMP kernel on 64 bit platform (X86-64) so the maximum size of a shared memory segment theoretically is 2^64bytes. This is correspond to all physical RAM that you have.
  • As a test case, I will set the value of the SHMMAX parameter to “1/4 of physical RAM”. I have 4 GB of RAM so I will set SHMMAX value to 1*1024*1024*1024=1,073,741,824 (bytes):
    • Temporarily:   echo 1073741824> /proc/sys/kernel/shmmax
    • Permanently: Edit the file “/etc/sysctl.conf” and set the entry: kernel.shmmax = 1073741824. This change can be reflected without restart by executing: “/sbin/sysctl -p“.

SHMALL Parameter

It is the total amount of shared memory pages that can be used system wide. Hence, SHMALL should always be at least SHMMAX / PAGE_SIZE. Execute “getconf PAGE_SIZE” to get the page size. In my case the page size is 4096 So the SHMALL value will be 1073741824/ 4096 = 262,144.

After configuring what the operating system allocate to your SIP router application, we need to configure the application itself. The following is an example:

Example: Tuning the Shared Memory of OpenSIPS SIP Router

OpenSIPS 1.X is pure multi process SIP server (version 2.x is multi threads). It stores the state of the calls (SIP transactions or SIP dialogs) in the shared memory accessed by all its processes (file: mem/shm_mem.h). Lets say the SHMEM_SIZE is the size of the shared memory. The recommended value of SHMEM_SIZE depends on the complexity of the routing script. When you run OpenSIPS, you can specify the entire shared memory (in MB) by using the command parameter -m. Ideally it is preferable to have SHMEM_SIZE equal to SHMMAX kernel parameter. This means OpenSIPS shared memory will fit in one shared memory segment. This leads to less job to memory manager and less memory errors. If  SHMEM_SIZE > SHMMAX, this means OpenSIPS memory manager will take more than one segment and manage access to them between all processes.
Here i will show you how to set OpenSIPS shared memory to 1 GB (SHMEM_SIZE = SHMMAX):

# ./opensips -m 1024 (1GB * 1024= 1024 MB)

  • Test the shared memory: You can get some statistics about the shared memory used and managed by OpenSIPS by sending FIFO commands to OpenSIPS. Have a look here on the SHMEM class. Use also system commands like “free” (MemShared or Shmem value) to get information about the memory.
  • The size of the recommended shared memory depends on the complexity of the routing script. So do the test many times for different values and choose the best for your system. Don’t forget to tune the value of  SHMMAX kernel parameter.

Note: Configure both the private memory (-M parameter) and the shared memory (-m parameter) at OpenSIPS startup. Test for different values and choose the one which suitable to your routing script.


Semaphores Settings

Semaphores are like counters that are used for controlling access by multiple processes to shared resources like shared memories. To see all semaphores settings: # ipcs -ls

—— Semaphore Limits ——–
max number of arrays = 128                      # SEMMNI Parameter
max semaphores per array = 250               # SEMMSL Parameter
max semaphores system wide = 32000      # SEMMNS Parameter
max ops per semop call = 32                     # SEMOPM Parameter
semaphore max value = 32767

or you can do this: # cat /proc/sys/kernel/sem

The output will be in this order (SEMMSL, SEMMNS, SEMOPM, SEMMNI):

250     32000   32      128

Tuning these values also depends on the complexity of the routing script. More complexity –> More loaded modules (shared libraries) –> more sharing –> more need for tuning the synchronization between processes.

Keep these values AS IS  if you don’t have problems with performance. To change these values temporarily:

# echo 250 32000 100 128 > /proc/sys/kernel/sem  

OR 

# sysctl -w kernel.sem=”250 32000 100 128″

To permanently change these values, Edit the file “/etc/sysctl.conf” and override the settings: kernel.sem=250 32000 100 128

Check The System Limits using “ulimit” System Property

Follow these steps to monitor the resources offered by the system to specific process:

  • Get the ID of the proess using # ps -A | grep …
  • Execute this: # cat /proc/$ProcessID/limits. Replace the ProcessID with the ID you get using the “ps” above.

The output will look like this:

Limit                     Soft Limit           Hard Limit           Units
Max cpu time              unlimited            unlimited            seconds
Max file size             unlimited            unlimited            bytes
Max data size             unlimited            unlimited            bytes
Max stack size            8388608              unlimited            bytes
Max core file size        0                    unlimited            bytes
Max resident set          unlimited            unlimited            bytes
Max processes             511830               511830               processes
Max open files            1024                 1024                 files
Max locked memory         65536                65536                bytes
Max address space         unlimited            unlimited            bytes
Max file locks            unlimited            unlimited            locks
Max pending signals       511830               511830               signals
Max msgqueue size         819200               819200               bytes
Max nice priority         0                    0
Max realtime priority     0                    0
Max realtime timeout      unlimited            unlimited            us


Next

After tuning the memory of the operating system, you need to care about the memory of  the SIP application itself. Here is an example (OpenSIPS Memory Debugging) .In the Next Part, I will talk about network tuning to optimize SIP Routers.


Linux Tuning For SIP Routers – Part 2 (Disk Access)

.

Introduction

If your SIP router does statefull processing and write the state like transactions information to different backends like syslog and SQL, you have to optimize the access to the disk where the state will be stored. The state can also be the dialog information like call duration, call start time, and setup time.

In Part 1 i have talked about interrupts and IRQ tuning. In this part i will show you how to tune the access to the disk to optimize the performance of your SIP router. Here i have Fedora Red Hat operating system, and Ext4 file system.

File System Tuning

To know the file system of your operating system and the mount options, execute the command “cat /etc/fstab“. The output will be like this:

/dev/mapper/fedora_dhcppc7-root                                  /              ext4    defaults        1 1
UUID=a534d6c5-ec57-4854-9c2b-db3ec3e66286            /boot        ext4    defaults        1 2
/dev/mapper/fedora_dhcppc7-home                               /home       ext4    defaults        1 2
/dev/mapper/fedora_dhcppc7-swap                                swap        swap    defaults       0 0

Each line in this output contains the following fields separated by spaces or tabs: partition or storage device, mounting point, file system type, mount options, dump, and pass.

According to this, the file system type is ext4 and the mount options is the defaults. In my system the default mount options are (rw, suid, dev, exec, auto, nouser, and async).

  • The option async allows asynchronous write/read operations on the file system. If your system has sync instead of async, change it otherwise keep it. You can read more about mount options in the man page “man mount“.
  • There is an option called  “noatime” which means reading accesses to the file system will not cause an update to the atime information (access time information) of the accessed files. In other words no writes to the file system for files which are being read. This is useful in case there is state reading from the disk.

To remount the root partition (i.e. /) with the mount option “noatime”, do this as root:

# mount -o remount, noatime   /

To do that permanently, edit the file fstab “vi  /etc/fstab" and update the corresponding line. For example if you want to add the mount option “noatime”  to the root partition (i.e. /):

This line : /dev/mapper/fedora_dhcppc7-root /                    ext4    defaults        1 1

will be : /dev/mapper/fedora_dhcppc7-root /                       ext4    defaults, noatime        1 1

To check the change in mount options: # mount |grep noatime. You will get this:

/dev/mapper/fedora_dhcppc7-root on  /  type ext4 (rw,noatime,seclabel,data=ordered)

Journaling File System

It is a file system feature which allows to serially log the changes in the file system into a dedicated area before committing them to the main file system. If a crash occurred, Any lost data can be recreated and stored in the locations that would have been stored in if the system had not crashed. In real time application like SIP routing, using non-journaling file system enhances the performance by avoiding the delay caused by jourmaling. In Ext4 file system you can turn off journaling feature. Do this to disable journaling:

  • Boot from your Linux installation DVD. Select Troubleshooting –> Rescue a Fedora system. Here you have your file system unmounted.
    • Execute: sh-4.2# tune2fs -O ^has_journal /dev/sda1
    • sh-4.2# tune2fs -O ^needs_recovery /dev/sda1
    • sh-4.2# e2fsck -f /dev/sda1
    • Remove the DVD and reboot.
  • Check file system features (There should be no “has_journal” or “needs_recovery”): # debugfs -R features /dev/sda1. The output:

Filesystem features: ext_attr resize_inode dir_index filetype extent flex_bg sparse_super huge_file uninit_bg dir_nlink extra_isize

Swappiness

The swap is a special place on the hard disk. Linux kernel stores physical memory pages/chunks that are currently unused on the swap to free up that pages from the physical memory. Using the disk as an extension to RAM is called virtual memory (RAM + swap). In real time applications like SIP routing, these are recommended:

  • Use enough physical memory.
  • Disable the swap or make the swapping rare.

How often the kernel do swapping is controlled by kernel parameter “Swappiness”. This parameter can be set to value between 0 and 100. The default value is 60.  To decrease the response latency, we use low value 0-10.  The value 0 makes the kernel swap only to avoid out of memory condition.

To change the “swappiness” value temporarily to 10, do this as root:

  • # echo 10 > /proc/sys/vm/swappiness
  • To verify the change : # cat /proc/sys/vm/swappines

To change the “swappiness” value permanently to 10, do this as root:

  • Edit the file “sysctl.conf” : # vim /etc/sysctl.conf
  • Add this line to override the default: vm.swappiness = 10

Next

In the Next Part , I will talk about memory tuning to optimize SIP Routers.


 

Homer as a SIP Capturing System – Part 2

.

Introduction

In Part 1, i have talked about the definition of Homer. In this article i will talk about these:

  • Compilation and Installation of SipCapture module with OpenSIPS. To have more control over the installation process, i will do the compilation from the source.
  • Preparing Homer database.
  • Installation and configuration of Homer web interface.

Please have a look here OpenSIPS Compilation and Installation.

Some Packages must be Installed

To be able to compile the Sip_Capture module and install it, you need some packages installed on your system. Here i am using Fedora Red Hat.

# yum  install autoconf automake bzip2 cpio curl curl-devel curl-devel expat-devel fileutils make gcc gcc-c++ gettext-devel gnutls-devel ncftp nmap openssl openssl-devel mod_ssl mcrypt perl patch unzip wget zip zlib zlib-devel bison flex mysql mysql-server mysql-devel pcre-devel libxml2-devel sox httpd php php-gd php-mysql php-json git php-mysql php-devel php-gd

# yum install php-pecl-jsonc php-pecl-jsonc-devel

Some of above packages are needed for Homer Web interface.

Compilation and Installation of SipCapture Module

  • Go to the folder where you have the source code of OpenSIPS. SipCapture module is included with OpenSIPS (“/usr/local/src/opensips_1_11/modules/sipcapture”). To compile it, do these:

# cd  /usr/local/src/opensips_1_11/

  • Compile the SipCapture module as following:

# make include_modules=”sipcapture” modules

  • Install it:

# make install

  • Go to “/usr/local/opensips_1_11/lib64/opensips/modules/” and be sure there is a file named sipcapture.so

Downoad Homer Web

 # cd /var/www/

# git clone https://code.google.com/p/homer/

Or

# git clone https://github.com/sipcapture/homer/

# cd homer

Preparing Homer Databases

Now we want to prepare the databases that are used by the capturing server and the web interface:

Run Mysql server: # systemctl start mysqld.service

  • We will login to mysql as root (# mysql -uroot -p password) and add the super user “homeruser” :

MariaDB [(none)]> CREATE USER homeruser@localhost IDENTIFIED BY “homerpass”;

MariaDB [(none)]> GRANT ALL PRIVILEGES ON *.* TO homeruser@localhost WITH GRANT OPTION;

  • Create the database “homer_db” by the user “homeruser”:

# mysql –uhomeruser –phomerpass -e “create database IF NOT EXISTS homer_db”;

  • Create another database “homer_users“:

# mysql -uhomeruser -phomerpass -e create database IF NOT EXISTS homer_users;

  • Create the required tables:

# mysql -uhomeruser -phomerpass -Dhomer_db < sql/create_sipcapture_version_4.sql

# mysql -uhomeruser -phomerpass -Dhomer_db < webhomer/sql/statistics.sql
# mysql -uhomeruser -phomerpass -Dhomer_users < webhomer/sql/homer_users.sql

  • Some nodes are added as default. So  i will delete them:

# mysql -uhomeruser -phomerpass -Dhomer_users -e TRUNCATE TABLE homer_nodes;

  • Now i will add my node:

# mysql -uhomeruser -phomerpass -Dhomer_users -e “INSERT INTO homer_nodes VALUES(1,’127.0.0.1′,’homer_db’,’3306′,’homeruser’,’homerpass’,’sip_capture’,’node1′, 1);”

  • Add web user: user level can be: 1 – ADMIN, 2 – Power User, 3 – User

I will delete the default user (test@test.com,test123):

# mysql -uhomeruser -phomerpass -Dhomer_users -e TRUNCATE TABLE homer_logon;

Now i will add my admin:

# mysql -uhomeruser -phomerpass -Dhomer_users -e “INSERT INTO homer_logon VALUES(NULL, ‘Admin’, MD5(‘admin123’), 1);”

Configuration of Homer Web Interface

We are in this folder “/var/www/homer/webhomer/”. The configuration and preferences PHP pages are exist in that folder. Just rename the files “configuration_example.php”  to “configuration.php” and  “preferences_example.php” to “preferences.php”.

# cp configuration_example.php configuration.php
# cp preferences_example.php preferences.php

Give (Read,Write,Execute) permission to Homer tmp folder:

# chmod 777 tmp/

If you have SELinux enabled, please run SELinux troubleshooter and follow what it will suggest to do to give permission to “tmp/”

Set the time zone of the Homer server

Take the time zone of your system (# system-config-date) and set it in the variable “HOMER_TIMEZONE” in the file “preferences.php”.

# vim preferences.php

define(‘HOMER_TIMEZONE’, “Europe/Stockholm”);

Configuration of database access credentials

Adjust the database access credentials in the configuration file “configuration.php”.

/* Access Credentials to “homer_users” Database */
define(‘HOST’, “localhost”);
define(‘PORT’, 3306);
define(‘USER’, “homeruser”);
define(‘PW’, “homerpass”);
define(‘DB’, “homer_users”);

/* Access Credentials to “homer_db” Database */
define(‘HOMER_HOST’, “localhost”);
define(‘HOMER_PORT’, 3306);
define(‘HOMER_USER’, “homeruser”);
define(‘HOMER_PW’, “homerpass”);
define(‘HOMER_DB’, “homer_db”);
define(‘HOMER_TABLE’, “sip_capture”);

Some paths must be adjusted:

define(‘PCAPDIR’,”/var/www/homer/webhomer/tmp/”);
define(‘WEBPCAPLOC’,”/var/www/homer/webhomer/tmp/”);
define(‘APILOC’,”/var/www/homer/webhomer/api/”);

Apache Configuration

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

Add these to httpd configuration file:

<Directory /var/www/homer/webhomer>
Options Indexes FollowSymLinks MultiViews
AllowOverride All
Order allow,deny
allow from all
</Directory>

Alias /homer /var/www/homer/webhomer

Restart the Httpd

# systemctl restart httpd

Open the browser and go to the URL : http://IP_address/homer. You will be here:

Login by this user  (username=”admin”, password=”admin123″). If it is ok with authentication, you will be here:

If you could not login from another computer, check the firewall configuration (Open the port 80 and 443 on your server). 443 is the HTTPS port /HTTP over TLS/SSL). We will see the related configuration in another article.

Till now Homer database is empty and we need to run the capturing server which is responsible for capturing packets and insert them in the database.

OpenSIPS Configuration to be a Homer Capturing Server

OpenSIPS configuration file will be like the following:

# This Configuration file is taken from Homer GIT Page:

####### Global Parameters #########

debug=3
log_stderror=no
log_facility=LOG_LOCAL1

fork=yes
children=5

listen=udp:10.0.0.9:5060   # CUSTOMIZE ME

disable_tcp=yes
disable_tls=yes
#db_default_url="mysql://opensips:opensipsrw@localhost/opensips"

####### Modules Section ########
#set module path
mpath="/usr/local/opensips_1_11/lib64/opensips/modules/"

loadmodule "db_mysql.so"
loadmodule "sipcapture.so"

####### Routing Logic ########
modparam("sipcapture", "db_url", "mysql://homeruser:homerpass@localhost/homer_db")
modparam("sipcapture", "capture_on", 1)
modparam("sipcapture", "table_name", "sip_capture")
/* activate HEP capturing */
modparam("sipcapture", "hep_capture_on", 1)

/* configuration for Mirroring PORT */
modparam("sipcapture", "raw_socket_listen", "10.0.0.9:5060-6000")
modparam("sipcapture", "raw_interface", "eth1")
/* activate monitoring port capturing */
modparam("sipcapture", "raw_moni_capture_on", 1)
modparam("sipcapture", "raw_sock_children", 4)
/* Promiscious mode */
modparam("sipcapture", "promiscious_on", 1)

####### Routing Logic ########


# main request routing logic

# Main SIP request routing logic
# - processing of any incoming SIP request starts with this route
route {
        #For example, you can capture only needed methods...
        #if (!(method =~ "^(OPTIONS|NOTIFY|SUBSCRIBE)$"))) {
                sip_capture();
        #}
        drop;
}

onreply_route {

        #And only needed reply or needed requests method
        #if(status =~ "^(1[0-9][0-9]|[3[0-9][0-9]|4[0-9]|[56][0-9][0-9])") {
        #if(!($rm =~ "^(NOTIFY|SUBSCRIBE|OPTIONS|)$")) {
                sip_capture();
        #}
        drop;
}

Save the file and restart OpenSIPS:

# systemctl restart opensips.service

Troubleshooting

Missed column  “authorization” in the capturing table “sip_capture”

MariaDB [(none)]> alter table sip_capture ADD authorization VARCHAR(125);

Now the capturing server can store the packets in the database homer_db

OpenSIPS as a SIP Capturing Agent

OpenSIPS SIPTRACE module can send the captured packets to an external HEP server (Homer capturing server) instead of storing them in the local database. The following is the configuration to send the captured packets out:

modparam(“siptrace”, “duplicate_uri”, “sip:10.0.0.1:9060″) # The capturing server address to send a duplicate of traced message to.

modparam(“siptrace”, “duplicate_with_hep”, 1)  # Enable HEP

modparam(“siptrace”, “trace_to_database”, 0) # Disable tracing to the local database


Next

The next part will be exploring Homer through its web interface and enabling statistics.


More Information


Homer as a SIP Capturing System – Part 1

.

Definition

homerHomer is a system designed to serve packet capturing purpose.The playing actors in this system are the capturing agent, the capturing server, and the web interface. The capturing agent is a daemon process (i.e. background process) which is running on the system of the routing node (SIP router). When a SIP message reaches the router, the capturing agent on this router takes a copy of this message, encapsulate it in HEP/IPIP packet (add an addition header to the message), and send it to the capturing server. The capturing agent will be configured with the address of the capturing server so it knows exactly where to send the packets. The capturing agent can be an external agent likeCaptagent“.

When the capturing server receives a packet, it decapsulates it (remove the added header), extracts,validate, and parses the SIP message and insert it in the database.The capturing server can also capture the SIP messages directly from the Ethernet (network monitoring connection). This is when a network switch send a copy of networks packets seen on one switch port to a network monitoring connection on another switch port.

The web interface which is connected to the database of the capturing server, loads the captured data  from the database and displays it  in a proper way. The figure below  shows how Homer system looks like:

OpenSIPS as a Homer Capturing Server

OpenSIPS can operate as a Homer capturing server. This is done with SipCapture module which is contributed to OpenSIPS in 2011. To achieve that, load and configure the SipCapture module in the routing script. In the routing script will be no routing for SIP messages but only capturing, processing and storing in the database. So another module must be loaded here which is the database module “db_mysql.so”.

Choosing OpenSIPS to operate as a capturing server is a good choice because of these:

  • Good core performance of OpenSIPS (e.g. Receive Message Handling, SIP Validator, SIP Parser).
  • By using OpenSIPS database interface, the capturing server will support many database servers (e.g. Mysql, Oracle,..).
  • Portability (Can be compiled on different systems).
  • Open source and free.

OpenSIPS as a SIP Router with Integrated Capturing Agent

Here OpenSIPS will operate as a SIP router with an integrated tracing capability (integrated capturing agent). To achieve this, the SipTrace module will be loaded to take a copy of each SIP message (or some of SIP messages) before routing it, encapsulate the message and send it to Homer capturing server. The address of Homer capturing server is configured as a parameter of SipTrace module.

modparam(“siptrace”, “duplicate_uri”, “sip:10.0.0.1:9060”) # The address to send a duplicate of traced message to it.

modparam(“siptrace”, “duplicate_with_hep”, 1)  # Enable HEP

modparam(“siptrace”, “trace_to_database”, 0) # Disable tracing to the local database

I will back to this later.

Note: OpenSIPS can not operate as capturing agent (siptrace module, HEP mode) and capturing server (sipcapture module) at the same time.

Homer Web Interface

The captured SIP messages are stored in the database and they should be displayed in proper way to the user who wants to analyse this data to be able to find any problem and solve it. This can be done through Homer multi-user web interface where you can see the messages displayed in table.You can search , filter, and sort the data. You can export the data as pcap files.  You can visualize the call flows. You can also get statistics. So the user login to the Homer web interface from anywhere and start working with SIP data.


Next:

The Next Part of this article will be about the compilation and installation of SipCapture Module, Setup of Homer Database, Installation of Homer Web interface.


More Information


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


SIP Stress Testing -Part 2 (SIPSAK)

.

This is part 2 of the “SIP Stress Testing” topic. In Part 1, I have talked about the definition of the stress, opensipsctl (command line tool) and OpenSIPS-CP (Web tool) and how they are used in testing. In this part, i will talk about SIPSAK. SIPSAK is a command line tool used by SIP administrators to test the performance and the security of the SIP servers or user agents. SIPSAK is a SIP traffic generator. It generates SIP requests and sends them to the target addressed by SIP-URI . To download SIPSAK on Fedora, simply:

 # yum install sipsak

SIPSAK runs in the following modes:

♣ Default mode: Using the OPTIONS SIP method, you can  ping a target addressed by SIP-URI.

♣ Traceroute mode (-T): This is useful for learning the request’s path. The number of SIP servers on the way to the destination is counted plus the round trip time of each request is printed out.

♣ Message mode (-M): Send a short message using MESSAGE SIP request. The content of the message will be set using the option (-B).

♣ Usrloc mode (-U): Register the user addressed by SIP-URI (Set by option -s).

♣ Randtrash mode (-R) :keeps sending randomly corrupted messages to torture a SIP server’s parser. OPTIONS requests with increasing numbers of randomly crashed characters are sent to the server.

♣ Flood Mode (-F): keeps sending requests to a SIP server at high pace. OPTIONS requests with increasing CSeq numbers are sent to the server.

Current SIPSAK is missing support for the Record-Route and Route headers and IPv6 is not supported. At the stressed SIP server’s side, you need monitoring and analyzing tool which display the state of the server as numbers and figures.

Examples

  • Ping the target “test1”: #sipsak -s sip:test1@testdomain.org. In this tutorial i will ping the user test1@10.0.0.9.

Here is the messages sent by SIPSAK and captured by SIPTRACE. See the User-Agent header field in the traced SIP message (User-Agent: sipsak 0.9.6). The message is taken from OpenSIPPS-CP SIPTRACE page.

If the server allows pinging. It will relay the ping message (SIP OPTION Request) and the response from the pinged target will come back to SIPSAK through the SIP server. The response will look like:

sipsak3The User-Agent: Jitsi2.2.4603.9615Linux . The target user (test1) must be registered otherwise you will get an error response message sent from the server (in case the server is programmed to do this in its routing script). The test server in this tutorial sends “404 Not Found” SIP failure:

sipsak4The server is “OpenSIPS (1.11.2-notls (x86_64/linux))” as written in the server’s response.

If you put the option -F , SIPSAK will flood the server with SIP OPTION Requests.

# sipsak -F  -s sip:test1@testdomain.org

SIPSAK is also used to test the security of the SIP server. In the previous example, flooding the server with OPTIONS SIP Requests (a lot of ping messages) is considered attack because after a short time the SIP service will be not available and the server became unable to handle more SIP requests. The test server in this tutorial sends an error message ” 500 Internal Error” after short time of flooding.

sipsak5Pinging is a way to check that the server is awake and not down. It must be available only for administration’s purposes.

Other SIPSAK examples:

  • Trace a call: # sipsak –T –s sip:test1@testdomain.org
  • Send a message to the user “test1” :# sipsak –M –s sip:test1@testdomain.org –c test2@testdomain.org –B “Message Text”
  • Register the user “test1” # sipsak –U –s sip:test1@testdomain.org

Nagios monitoring tool are good complement to SIPSAK traffic generator.

SO to test the server, generate requests and check the system’s response. If you get something you don’t like, change it and do it again (Make changes, Restart the server, Generate traffic , and Check the server’s response).


More Information


 Next

The Next Part will be about SIPp which is an emulation tool which generates SIP traffic and gives some statistics.