MI SCRIPT module

Admin Guide

Overview

This module provides multiple hooks to run Management Interface commands directly from OpenSIPS script. It supports running both synchronous and asynchronous commands. Depending on the nature of the command (asynchronous or not), and on the way the mi command is run from script, the returned result is different.

Values Returned

In case of success, the MI command returns with success. If a return variable is provided as parameter, a JSON is also stored in the variable provided.

In case of failure of the MI command, JSON-RPC reply error code is stored in the $rc variable, as a negative number. Lower values, such as -1,-2,-3 can also be returned to indicate an internal error. If a return variable is provided, it is stored to the error description.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• proto_hep module, in case MI tracing is used.

External Libraries or Applications

The following libraries or applications must be installed before running OpenSIPS with this module loaded:

• none

Exported Parameters

pretty_printing (int)

Indicates whether the JSON responses stored in the return variable should be pretty-printed or not.

Default value is “0 - no pretty-printing”.

Set pretty_printing parameter

...
modparam("mi_script", "pretty_printing", 1)
...

trace_destination (string)

Trace destination as defined in the tracing module. Currently the only tracing module is proto_hep. This is where traced mi messages will go.

Danger

A tracing module must be loaded in order for this parameter to work. (for example proto_hep).

Default value is none(not defined).

Set trace_destination parameter

...
modparam("proto_hep", "trace_id", "[hep_dest]10.0.0.2;transport=tcp;version=3")

modparam("mi_script", "trace_destination", "hep_dest")
...

trace_bwlist (string)

Filter traced mi commands based on a blacklist or a whitelist. trace_destination must be defined for this parameter to have any purpose. Whitelists can be defined using ‘w’ or ‘W’, blacklists using ‘b’ or ‘B’. The type is separate by the actual blacklist by ’:’. The mi commands in the list must be separated by ’,’.

Defining a blacklists means all the commands that are not blacklisted will be traced. Defining a whitelist means all the commands that are not whitelisted will not be traced.

Danger

One can’t define both a whitelist and a blacklist. Only one of them is allowed. Defining the parameter a second time will just overwrite the first one.

Danger

A tracing module must be loaded in order for this parameter to work. (for example proto_hep).

Default value is none(not defined).

Set trace_destination parameter

...
## blacklist ps and which mi commands
## all the other commands shall be traced
modparam("mi_script", "trace_bwlist", "b: ps, which")
...
## allow only sip_trace mi command
## all the other commands will not be traced
modparam("mi_script", "trace_bwlist", "w: sip_trace")
...

Exported Functions

mi(command, [ret_var [,params_avp[, vals_avp]]])

Runs an MI command in synchronous mode, blocking until a response is available.

Caution

It is highly recommended to prevent using this function for tasks that take long time, such as reloads, as the function would block until the command ends. Moreover, if the running MI command is configured to run in asynchronous mode (such as t_uac_dlg the command blocks in a busy waiting manner until the response is received.

This function can be used in any route.

The function can receive the following parameters:

• command(string) - the MI command to be run. This can be a single token, representing the MI command to run (without parameters), or can be followed by several space separated parameters (no escaping is handled). Each space separated parameter will be passed to the MI command as an indexed parameter. NOTE: named parameters can not be specified using this parameter, and you will have to use the params_avp and/or the vals_avp parameters to specify named commands, in which case this parameter will only consist of the MI command.
• ret_var(var, optional) - a variable used to store the return of the MI command execution. In case of success, a JSON is stored, otherwise an erorr message.
• params_avp(avp, optional) - an AVP consisting of all the parameters names that will be sent to the MI command. If this parameter is used without the vals_avp, all the values inside the AVP will be passed to the MI command as indexed parameters, otherwise as named parameters. NOTE: if this parameter is used, the parameters specified in the command parameter are ignored. NOTE: the order the parameters are passed to the command is the same as the one you populate the AVPs (thus somehow reversed compared to the way AVPs are stored in memory - the first AVP added is the first parameter)
• vals_avp(avp, optional) - an AVP consisting of all the parameters values that will be sent to the MI command. This parameter only makes sense if the params_avp is set, and has to contain the same number of values as there are parameters. To specify array values, enclose your space-separated array elements in the __array() pseudo-function call. For example: “__array(HEARTBEAT BACKGROUND_JOB)“

mi without params

...
mi("shm_check");
...

mi with params in command

...
# this command is similar to the above
mi("cache_remove local password_user1");
...

mi with return

...
mi("ds_list", $var(ret));
...

mi without return but with indexed params

...
$avp(params) = "local";
$avp(params) = "password_user1";
mi("cache_remove",,$avp(params));

# the following command is similar to the above
mi("cache_remove local password_user1");
...

mi with return and named parameters

...
$avp(params) = "callid";
$avp(vals) = "SEARCH_FOR_THIS_CALLID";
$avp(params) = "from_tag";
$avp(vals) = "SEARCH_FOR_THIS_FROM_TAG";
mi("dlg_list", $var(dlg), $avp(params), $avp(vals));
...

mi without return, with an array parameter value

...
$avp(params) = "freeswitch_url";
$avp(vals) = "fs://:ClueCon@192.168.20.8:8021";
$avp(params) = "events";
$avp(vals) = "__array(HEARTBEAT BACKGROUND_JOB)";
mi("fs_subscribe", , $avp(params), $avp(vals));
...

Exported Asynchronous Functions

mi(command, [ret_var [,params_avp[, vals_avp]]])

The function works is more or less the same as its synchronous corespondent, except that the MI command is run in an asynchronous manner - the process does not block to wait for the response, but it continues its execution and the MI command is run in an asynchronous context.

Note

Currently MI commands run asynchronously cannot be traced through hep.

async mi call usage

...
xlog("reload starting\n");
async(mi("dr_reload"), after_reload);
...

route[after_reload] {
  xlog("reload completed\n");
}

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Razvan Crainea (@razvancrainea)	19	8	1118	19
2.	Stefan Darius (@dariusstefan)	10	4	419	112
3.	Liviu Chircu (@liviuchircu)	5	3	80	19
4.	Maksym Sobolyev (@sobomax)	5	3	7	8
5.	Alexandra Titoc	3	1	4	2

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	May 2021 - Jun 2026
3.	Alexandra Titoc	Sep 2024 - Sep 2024
4.	Liviu Chircu (@liviuchircu)	Jun 2022 - Aug 2024
5.	Maksym Sobolyev (@sobomax)	Feb 2023 - Nov 2023

(1) including any documentation-related commits, excluding merge commits

Documentation

Contributors

Last edited by: Razvan Crainea (@razvancrainea), Liviu Chircu (@liviuchircu).

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0