The OpenSIPS design

Architecturally speaking, OpenSIPS is formed out of two logical components: the core and modules.

The core is the application itself and it provides the low-level functionalities of OpenSIPS, the definition of various interfaces, and some generic resources.

The modules are shared libraries, loaded on demand at the startup time. Each module implements a well-defined functionality for a specific routing algorithm or authentication method. There are mainly two types of modules in OpenSIPS:

• Modules providing functionalities and functions directly for the routing script
• Modules implementing a core-defined interface (such as a module implementing the SQL interface will become a backend to a certain SQL server)

The following is a figure showing the OpenSIPS architecture:

The OpenSIPS core

The OpenSIPS core is a minimal application. By itself, it is only able to proxy the SIP requests and replies in a stateless mode with very basic scripting capabilities. In most of the cases, the core is used in conjunction with several modules.

The OpenSIPS core provides the following features:

• The SIP transport layer
• The SIP factory—the message parser and builder
• The routing script parser and interpreter
• The memory and locking manager
• The core script functions and script variables
• The SQL interface definition (implementation provided by modules and not by the core itself)
• The NoSQL interface definition
• The AAA interface definition
• The management interface
• The events interface
• The statistics interface

The SIP transport layer implements various SIP transport protocols. Currently, OpenSIPS supports UDP, TCP, TLS, and WebSockets. Which transport protocols are to be used depends on the SIP listeners defined in the routing script. Multiple transport protocols can be used at the same time.

The SIP factory layer provides functions to parse and build SIP messages. OpenSIPS implements a lazy but efficient SIP parser, which means that the parsing is done on demand (OpenSIPS parses as far as requested) and is selective. (The header bodies are parsed only if requested; otherwise, only the header name is parsed.) The parsing process is transparent at the script level, each function (core or modules) doing its own parsing internally. When it comes to changing the message, it is very important to know that the changes you make from the script are not applied in real time to the message but stored and applied to all only when the message processing is done.

Tip

Due to this offline handling of changes, you are not able to see your own changes over the message. For example, if you add a new SIP header and test its presence, you will not find it, or if you remove a SIP header and look again for it, you will find it.

The routing script parser and interpreter loads and parses (to the memory) the routing script at the startup time; after this, the file is no longer needed. The routing script cannot be reloaded at runtime; OpenSIPS must be restarted in order to read the routing script again. Aside from various global settings, the routing script contains the routing logic; this logic is defined via a C/Shell language, custom to OpenSIPS. Configuring the routing logic in OpenSIPS is more like doing simple programming. This approach (writing your own program to route the traffic) gives OpenSIPS a tremendous flexibility when it comes to routing.

The memory and locking manager is a global resource in OpenSIPS. For performance reasons, OpenSIPS implements its own internal manager for memory allocation and locking operations. This part is not visible at the route scripting level, but it may be configured at compiling time. (OpenSIPS has several implementations for the memory and locking managers.)

The OpenSIPS core provides its own script functions and script variables to be used from the routing script. As compared with the functions and variables exported by the modules, the core set is quite limited in number and functionality. The online manual lists and documents all the functions and variables provided by the OpenSIPS core.

The SQL interface is defined by the core but not implemented. The definition is done here in the OpenSIPS core for standardization reasons. Modules can use the SQL services via the SQL interface without being aware of the undelaying SQL driver. Additionally, other modules may implement the SQL interface, offering drivers to various SQL DBs, such as MySQL, Postgre, Oracle, Berkeley, Unix odbc, and many others. (See all the modules starting with the db_ prefix.) Even if the SQL interface is for internal usage (between modules), it is partially exposed at the script level by the avpops module:

avp_db_query("select first_name, last_name from subscribers where username='$rU' and domain='$rd'", "$avp(fname);$avp(lname)");

Similar, the NoSQL interface is defined for the standardizing of the operations with the NoSQL databases. OpenSIPS modules currently implement drivers to Redis, CouchBase, Cassandra, MongoDB, Memcached, and other databases. (See all the modules starting with the cachedb_ prefix.) The NoSQL interface is directly exposed by the OpenSIPS core via a simple set of functions:

cache_store("redis:cluster1", "key1", "$var(my_val)", 1200);
cache_fetch("redis:cluster1", "key1", "$var(my_val)");
cache_remove("redis:cluster1", "key1");

The AAA interface defines the interfacing to AAA servers in a similar way. Currently, OpenSIPS supports the RADIUS driver for the AAA interface, the Diameter driver being under heavy rework at this time. The AAA interface is not exposed at all at the routing script level as it is exclusively used internally between modules.

The Management Interface (MI) is an OpenSIPS interface that allows external applications to trigger predefined commands in OpenSIPS. Such commands typically allow an external application/script to perform the following:

• Push data into OpenSIPS (such as setting the debug level, registering a contact, and so on)
• Fetch the data from OpenSIPS (see registered users, see ongoing calls, get statistics, and so on)
• Trigger an internal action in OpenSIPS (reloading the data, sending a message, and so on)

The MI commands are provided by the OpenSIPS core (See the online documentation at to see the commands provided by each module at http://www.opensips.org/Documentation/Modules-2-1.)

For MI, OpenSIPS supports the following drivers: XMLRPC, FIFO file, Datagrams, JSON RPC, and HTTP. (See all the modules starting with the mi_ prefix.)

A simple example of interacting with OpenSIPS via the MI interfaces is using the opensipsctl utility; it uses the FIFO or XMLRPC protocols to push the MI commands into OpenSIPS. The opensipsctl utility allows you explicitly run an MI command via the FIFO file, as shown here:

opensipsctl fifo ps
opensipsctl fifo debug 4

A simple program in Python to trigger to run an MI command in OpenSIPS via the XMLRPC protocol is as follows:

#!/usr/bin/python
import xmlrpclib
opensips = xmlrpclib.ServerProxy('http://127.0.0.1:8080/RPC2')
print opensips.ps();

The events interface is an OpenSIPS interface that provides different ways to notify external applications about certain events triggered in OpenSIPS. In order to notify an external application about the OpenSIPS internal events, the event interface provides the following functions:

• Manages exported events
• Manages subscriptions from different applications
• Exports generic functions to raise an event (regardless of the transport protocol used)
• Communicates with different transport protocols to send the events

Events can be triggered by the core activities (See the online documentation at http://www.opensips.org/Documentation/Interface-CoreEvents-2-1.), module activities (See the Exported Events section in the module documentation at http://www.opensips.org/Documentation/Modules-2-1.), or explicitly from the routing script via the raise_event() function, as follows:

raise_event("E_SCRIPT_EVENT", $avp(attributes), $avp(values));

To deliver the events, OpenSIPS modules implement the following drivers: datagram, RabbitMQ, and XMLRPC. (See all the modules starting with the event_ prefix.)

The statistics interface provides access to various internal statistics of OpenSIPS. It provides valuable information about what is going on in OpenSIPS. This can be used by external applications to monitor the purposes, load evaluation, and real-time integration with the other services. The values of the statistic variables are exclusively numerical. OpenSIPS provides two types of statistic variables:

• counter like: Variables that keep counting things that happened in OpenSIPS, such as received requests, processed dialogs, failed DB queries, and so on
• computed values: Variables that are calculated in real time, such as how much memory is used, the current load, active dialogs, active transactions, and so on

To know more about statistic variables, refer to http://www.opensips.org/Documentation/Interface-Statistics-1-10.

In OpenSIPS, the statistics variables are grouped in different sets depending on their purposes or how to provide them. For example, the OpenSIPS core provides the shmem, load, net, and other groups (refer http://www.opensips.org/Documentation/Interface-CoreStatistics-2-1), while each OpenSIPS module provides its own group. (Typically, the group has the same name as the module.)

The statistics can be easily queried via the MI with the get_statistics command, as shown here:

# get various statistic variables, by list of names
> opensipsctl fifo get_statistics rcv_requests inuse_transactions
> core:rcv_requests = 453
> tm:inuse_transactions = 10

The OpenSIPS modules

Each OpenSIPS module is a dynamic library that can be loaded on demand at the OpenSIPS startup, if instructed in the routing script.

The modules are identified by their names and they typically export various resources to be used in/from the routing script:

• A set of module parameters (optional): They allow the module to be configured at startup
• A set of script functions (optional): They are functions to be used from the routing script
• A set of asynchronous script functions (optional): They are functions to be used from the routing script but in an asynchronous way via a resume route (refer to Chapter 14, Advanced Topics with OpenSIPS 2.1)
• A set of variables (optional): They are variables that can be used from the routing script
• A set of statistics variables (optional): They are statistics specific to the module that can be read via the MI
• A set of MI commands (optional): They are commands specific to the module to be triggered via the MI from outside OpenSIPS
• A set of events (optional): They are events that can be triggered by the module and delivered by the event modules to external applications

Based on what they implement, there are three types of modules in OpenSIPS:

• Modules implementing the functionalities to be used from the routing script (that is, authentication methods, routing algorithms, registration handling, and so on).
• Modules implementing one of the interfaces defined by the core in order to provide a driver for a certain communication protocol (that is, a MySQL driver for the SQL interface, a RADIUS driver for the AAA interface).
• Modules implementing their own particular API; such an API is to be used directly (bypassing the core) by the other modules. This allows modules to use other modules, independent of the core. (Such modules are the b2b_entities, the dialog module, TM module, and others.)

We can conclude that even if most of the modules provide functionalities to the routing script, there are modules providing functionalities to other modules via the core interfaces or their own APIs.

Here are some examples of the modules:

• The db_mysql module implements the SQL interface defined by the core; the auth_db module using the SQL interface to perform the SQL operations can transparently use any module implementing the SQL interface
• The b2b_entities module defines and implements its own API (to manage SIP UASs and UACs); the b2b_logic module uses the API from the b2b_entities module directly in order to build even more complex functionalities (that are used later from the routing script)

This leads to the concept of module dependencies and an OpenSIPS module may depend on the following:

• An external library at linking time, that is, b2b_logic depends on the xml2 library
• The core interface at startup time; if a module uses the SQL interface, you need to load one or more modules implementing a SQL driver
• The other modules; one module depends directly and explicitly on the other modules (that is, b2b_logic depends on b2b_entities)

The documentation of each module (the readme file) contains information on the module's dependencies, what functions or parameters are exposed, and what MI commands or events are available. See the online module documentations at http://www.opensips.org/Documentation/Modules-2-1.