kamailio/src/modules/app_ruby

app_ruby Module

Daniel-Constantin Mierla

   asipto.com

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2018 Daniel-Constantin Mierla (asipto.com)
     __________________________________________________________________

   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)
              3.3. modproc (str)

        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. Set modproc parameter
   1.4. jsdt_run usage

Chapter 1. Admin Guide

   Table of Contents

   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)
        3.3. modproc (str)

   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

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
   2.2. External Libraries or Applications

2.1. Kamailio Modules

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

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)
   3.2. xval_mode (int)
   3.3. modproc (str)

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 required 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: 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”.

   Example 1.2. Set xval_mode parameter
...
modparam("app_ruby", "xval_mode", 0)
...

3.3. modproc (str)

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

   Default value is "app_ruby_proc.so".

   Example 1.3. Set modproc parameter
...
modparam("app_ruby", "modproc", "app_ruby_proc2.so")
...

4. Functions

   4.1. ruby_run(function, params)

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.4. 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
   5.2. app_ruby.api_list

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