New OpenSIPS CLI tool for the New Management Interface in OpenSIPS 3.0

When running a non-interactive service (daemon), such as OpenSIPS, a mandatory requirement is to have a method to interact with it. This is useful for different purposes, such as monitoring the service, provisioning certain data within it, or simply controlling different behaviors of its components.

For these matters we have developed the new OpenSIPS CLI tool, an interactive command line tool that aims to improve your experience when managing and interacting with OpenSIPS servers, by providing cool new features such as:

Commands auto-completion

You don’t know the exact MI command that you want to run? Forget about the MI which command, the new OpenSIPS CLI will do all the job for you. Just hit the TAB key, and opensips-cli will show you all the possible alternatives for your input, or even complete the command for you.

Moreover, if you don’t know the parameters a command receives, a simple TAB key will show you all the arguments available for that specific command. You just need to fill in the values for the ones you need, and that’s it!

History and commands navigation

Need to run a previous command? No worries, just hit the UP button to navigate until you find the command you want to execute. Or simply search for it using the CTRL-R keys followed by parts of the commands you want to run.

Check out a nice demo of using the opensips-cli auto-completion tool and history here:

Standard configuration format

The tool can be configured using a configuration file, specified in the widespread ini format. An example configuration file that modifies the default prompt info and log level is:

[default]             
log_level: INFO                                                                                                                                                                                                                         
prompt_intro: My custom OpenSIPS CLI Intro!

All parameters that can be configured are extensively documented in the project’s page.

Remote Execution

Using the new OpenSIPS CLI tool,  you are no longer constrained to run commands only locally, through local FIFO files. Since opensips-cli has support for running commands over JSON-RPC, you can now execute commands on remote OpenSIPS instances.

Support for multiple OpenSIPS instances

Moreover, you can manage multiple remote instances from a single CLI session. All you have to do is to specify in a configuration file different connections to each of your OpenSIPS instances and switch to the instance you want to trigger the command for.

For example, consider the following configuration file, which specifies two OpenSIPS instances: one on 10.0.0.1 and one on 10.0.0.2:

[10.0.0.1]
prompt_name: opensips-cli@10.0.0.1
prompt_intro: OpenSIPS CLI for 10.0.0.1 instance
communication_type: http
url: http://10.0.0.1:8888/json

[10.0.0.2]
prompt_name: opensips-cli@10.0.0.2
prompt_intro: OpenSIPS CLI for 10.0.0.2 instance
communication_type: http
url: http://10.0.0.2:8888/json

Now start a cli towards the first instance using:

$ opensips-cli -i 10.0.0.1

First we run a ps command on instance 10.0.0.1, then switch on a different instance, 10.0.0.2, and run a different command.

OpenSIPS CLI for 10.0.0.1 instance
(opensips-cli@10.0.0.1): instance show
10.0.0.1
(opensips-cli@10.0.0.1): mi ps
Processes:
- ID: 1
  PID: 3645
  Type: MI FIFO
- ID: 2
  PID: 3646
  Type: time_keeper
- ID: 3
  PID: 3647
  Type: timer
- ID: 4
  PID: 3648
  Type: SIP receiver udp:10.0.0.1:5060
- ID: 5
  PID: 3649
  Type: Timer handler
(opensips-cli@10.0.0.1): instance list
default
10.0.0.1
10.0.0.2
(opensips-cli@10.0.0.1): instance switch 10.
10.0.0.1  10.0.0.2  
(opensips-cli@10.0.0.1): instance switch 10.0.0.2 
OpenSIPS CLI for 10.0.0.2 instance
(opensips-cli@10.0.0.2): mi ps
Processes:
- ID: 1
  PID: 28064
  Type: MI FIFO
- ID: 2
  PID: 28065
  Type: time_keeper
- ID: 3
  PID: 28066
  Type: timer
- ID: 4
  PID: 28067
  Type: SIP receiver udp:10.0.0.2:5060
- ID: 5
  PID: 28068
  Type: Timer handler
(opensips-cli@10.0.0.2):

Notice that each instance has it’s own processes and listeners, which proves that we are interrogating a different OpenSIPS server.

Easy to extend

The new OpenSIPS CLI is developed using Python3, and it is written in a very modular way. If you want to develop a new feature, all you have to do is to write your own module, that defines handlers for each command you want to support. And from here, OpenSIPS CLI will do all the internal management for auto-completion, instances, etc.

This new tool incorporates all the relevant features of its older brothers (opensipsctl, opensipsdbctl and osipsconsole) in a single application. Therefore, starting with OpenSIPS 3.0, these applications will be completely dropped.

New OpenSIPS 3.0 Management Interface

In order to make these features in the new OpenSIPS CLI possible, we had to have OpenSIPS to provide a standard way of specifying input commands and arguments, and return their results. Therefore, we completely reworked the OpenSIPS MI interface to have each MI transport module adhere to the standard JSON-RPC 2.0 format. This offers us the flexibility of specifying commands arguments as both positional and named parameters, solving some commands ambiguity (see the dlg_list command).

Now that the output of the commands are also returned in a standard, structured manner, you can easily use any JSON-RPC parser yourself to interpret the output of the command and extract only the information you need. And, of course, you can easily interpret the output it in your favorite  programming or scripting language, using existing libraries, instead of writing your own line-by-line parser (as you would have done with opensipsctl).

Note that in order to provide backwards compatibility, the mi_xmlrpc_ng module is still supported and works similar to previous versions. But since XML-RPC is a well-structured, standard protocol by itself (thus it adheres to our new MI philosophy), it does not (directly) rely on the JSON-RPC specifications. However we have created an adapter in OpenSIPS that translates XML-RPC to JSON-RPC to make it compliant with the new MI interface.

Conclusions

The new OpenSIPS CLI tool, along with the new OpenSIPS 3.0 MI interface rework, aim to ease the way you manage and control your VoIP services. Be sure that your operations team will love them!

Special thanks go to Dorin Geman for the development of the OpenSIPS CLI tool!

If you want to find out more about the new OpenSIPS 3.0 and the OpenSIPS CLI tool, make sure you do not miss this year’s OpenSIPS Summit in Amsterdam!