app_ruby Module

Daniel-Constantin Mierla

asipto.com

Edited by

Daniel-Constantin Mierla


Table of Contents

1. Admin Guide
1. Overview
2. Dependencies
2.1. Kamailio Modules
2.2. External Libraries or Applications
3. Parameters
3.1. load (str)
3.2. xval_mode (int)
4. Functions
4.1. ruby_run(function, params)
5. RPC Commands
5.1. app_ruby.reload
5.2. app_ruby.api_list
6. Example of usage

List of Examples

1.1. Set load parameter
1.2. Set xval_mode parameter
1.3. jsdt_run usage

Chapter 1. Admin Guide

1. Overview

This module allows executing Ruby scripts from the Kamailio configuration file. It exports all KEMI functions to Ruby in order to access the currently processed SIP message. These functions are available within the Ruby module 'KSR'.

IMPORTANT: because of Ruby language policy (which require that a public submodule name has to start with an uppercase letter), the KSR submodule names are with all letters uppercase. For example, what is documented as KSR.sl in KEMI docs, must be used as KSR::SL in Ruby scripts.

2. Dependencies

2.1. Kamailio Modules

The following modules must be loaded before this module:

  • none.

2.2. External Libraries or Applications

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

  • libruby - the ruby library (for compilation on Debian, ruby-dev package is needed.

3. Parameters

3.1. load (str)

Set the path to the Ruby file to be loaded at startup. Then you can use Ruby_run(function, params) to execute a function from the script at runtime. If you use it for KEMI configuration, then it has to include the requited functions.

Default value is null.

Example 1.1. Set load parameter

...
modparam("app_ruby", "load", "/usr/local/etc/kamailio/ruby/myscript.rb")
...

3.2. xval_mode (int)

Control if the external sub-module functions returning extended-values should propagate their string return value (when set to 0) or be replaced by NULL/nil (when set to 1).

When set to 0, the KSR::PV Ruby submodule is implemented with the internal functions from the app_ruby module, otherwise the ones from core are used.

Note: when set to 1, there were crashing reports that are under investigation, this option being provided as intermediary solution to preserve the behaviour from older versions.

Default value is 0.

Example 1.2. Set xval_mode parameter

...
modparam("app_ruby", "xval_mode", 1)
...

4. Functions

4.1.  ruby_run(function, params)

Execute the Ruby function 'func' giving params as parameters. There can be up to 3 string parameters. The function must exist in the script loaded at startup via parameter 'load'. Parameters can be strings with pseudo-variables that are evaluated at runtime.

Example 1.3. jsdt_run usage

...
if(!ruby_run("rb_append_fu_to_reply"))
{
    xdbg("SCRIPT: failed to execute ruby function!\n");
}
...
ruby_run("rb_funcx", "$rU", "2");
...

5. RPC Commands

5.1.  app_ruby.reload

Marks the need to reload the js script. The actual reload is done by every working process when the next call to ruby_run() function or KEMI config is executed.

Name: app_ruby.reload

Parameters: none

Example:

...
kamcmd app_ruby.reload
...

5.2.  app_ruby.api_list

List the functions available via Kemi framework.

Name: app_ruby.api_list

Parameters: none

Example:

...
kamcmd app_ruby.api_list
...

6. Example of usage

Create your Ruby script and store it on the file system, say: '/usr/local/etc/kamailio/ruby/myscript.rb'.

...
def ksr_sl_reply()
	KSR.dbg("==== from ruby - src ip: " + KSR::PV.get("$si") + "\n")
	KSR::SL.sl_send_reply(200, "OK-Ruby")
end
...

Load the script via parameter 'load' and execute function via ruby_run(...).

...
modparam("app_ruby", "load", "/usr/local/etc/kamailio/ruby/myscript.rb")
...
request_route {
    ...
    if(!ruby_run("ksr_sl_reply")) {
        xdbg("SCRIPT: failed to execute ruby function!\n");
    }
    ...
}
...