# &adminguide;

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be installed (but not loaded) before this module:

- app_ruby_proc.

### 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.

## Parameters

### `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 required functions.

Default value is null.

#### Set `load` parameter

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

### `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: upt to version 5.7, 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 1.

#### Set `xval_mode` parameter

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

### `modproc` (str)

The name of or the path to the required per-process API module.

Default value is "app_ruby_proc.so".

#### Set `modproc` parameter

    ...
    modparam("app_ruby", "modproc", "app_ruby_proc2.so")
    ...

## Functions

### `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.

#### `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");
    ...

## RPC Commands

### `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:

    ...
    &kamctl; rpc app_ruby.reload
    ...

### `app_ruby.api_list`

List the functions available via Kemi framework.

Name: app_ruby.api_list

Parameters: none

Example:

    ...
    &kamctl; rpc app_ruby.api_list
    ...

## 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");
        }
        ...
    }
    ...