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:
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.
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: firstname.lastname@example.org 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: email@example.com 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 (firstname.lastname@example.org): instance show 10.0.0.1 (email@example.com): 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 (firstname.lastname@example.org): instance list default 10.0.0.1 10.0.0.2 (email@example.com): instance switch 10. 10.0.0.1 10.0.0.2 (firstname.lastname@example.org): instance switch 10.0.0.2 OpenSIPS CLI for 10.0.0.2 instance (email@example.com): 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 (firstname.lastname@example.org):
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.
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!