mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
378 lines
10 KiB
378 lines
10 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This module allows executing Lua scripts from config file, implementing
|
|
the KEMI framework and exporting Lua module 'KSR'.
|
|
</para>
|
|
<para>
|
|
To read more about KEMI exports and available KSR submodules, see:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<ulink url="https://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/">https://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/</ulink>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Note: to have the old Lua module 'sr' available, load the 'app_lua_sr'
|
|
&kamailio; module.
|
|
</para>
|
|
<para>
|
|
Lua (http://www.lua.org) is a fast and easy to embed scripting
|
|
language. Exported API from SIP router to Lua is documented in the
|
|
dokuwiki.
|
|
</para>
|
|
<para>
|
|
The module has two Lua contexts:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>first</emphasis> is used for functions lua_dofile()
|
|
and lua_dostring().
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>second</emphasis> is used for function lua_run()
|
|
and parameter 'load'. Therefore lua_run() cannot execute functions
|
|
from scripts loaded via lua_dofile() in config. This is kind of
|
|
caching mode, avoiding reading file every time, but you must be sure
|
|
you do not have something that is executed by default and requires
|
|
access to SIP message. This is also the context used with KEMI
|
|
framework.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>none</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before running
|
|
&kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>liblua5.1-dev</emphasis> - Lua devel library. Versions 5.2, 5.3 and 5.4 also work.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This module can be compiled against LuaJIT compiler (instead of
|
|
standard Lua). Then this library is needed:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<emphasis>libluajit-5.1-dev</emphasis> - LuaJIT devel library.
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
To enable that, LUAJIT variable has to be set.
|
|
<example>
|
|
<title>Build against LuaJIT libraries</title>
|
|
E.g: $ LUAJIT="yes" make modules modules=modules/app_lua
|
|
</example>
|
|
(Warning: LuaJIT version is 5.1, so scripts prepared for higher Lua versions
|
|
may not work with LuaJIT)
|
|
</para>
|
|
</para>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="app_lua.p.load">
|
|
<title><varname>load</varname> (string)</title>
|
|
<para>
|
|
Set the path to the Lua script to be loaded at startup. Then you
|
|
can use lua_run(function, params) to execute a function from the
|
|
script at runtime. The script can be in Lua-source or bytecode.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>load</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="app_lua.p.reload">
|
|
<title><varname>reload</varname> (boolean)</title>
|
|
<para>
|
|
If reload is 1 enables the ability to reload the
|
|
scripts using the RPC app_lua.reload command. To disable reload
|
|
feature, set this parameter to 0.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1 (on)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reload</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("app_lua", "reload", 0)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="app_lua.p.log_mode">
|
|
<title><varname>log_mode</varname> (int)</title>
|
|
<para>
|
|
Control what is printed in log messages. If bit 1 is set, then
|
|
the module prints debug messages for each KEMI export.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>log_mode</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("app_lua", "log_mode", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="app_lua.f.lua_dotfile">
|
|
<title>
|
|
<function moreinfo="none">lua_dofile(path)</function>
|
|
</title>
|
|
<para>
|
|
Execute the Lua script stored in 'path'. The parameter can be
|
|
a string with pseudo-variables evaluated at runtime.
|
|
</para>
|
|
<example>
|
|
<title><function>lua_dofile</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
lua_dofile("/usr/local/etc/kamailio/lua/myscript.lua");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="app_lua.f.lua_dostring">
|
|
<title>
|
|
<function moreinfo="none">lua_dostring(script)</function>
|
|
</title>
|
|
<para>
|
|
Execute the Lua script stored in parameter. The parameter can be
|
|
a string with pseudo-variables.
|
|
</para>
|
|
<example>
|
|
<title><function>lua_dostring</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(!lua_dostring("KSR.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="app_lua.f.lua_run">
|
|
<title>
|
|
<function moreinfo="none">lua_run(func [, params])</function>
|
|
</title>
|
|
<para>
|
|
Execute the Lua function 'func' giving 'params' as parameters. There
|
|
can be up to 3 string parameters after 'func' (overall, max 4 params,
|
|
first is the function). The function must exist in the Lua
|
|
script loaded at startup via parameter 'load'. Parameters can be
|
|
strings with pseudo-variables that are evaluated at runtime.
|
|
</para>
|
|
<example>
|
|
<title><function>lua_run</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(!lua_run("sr_append_fu_to_reply")) {
|
|
xdbg("SCRIPT: failed to execute lua function!\n");
|
|
}
|
|
...
|
|
lua_run("lua_func0");
|
|
lua_run("lua_func1", "$rU");
|
|
lua_run("lua_func2", "$rU", "2");
|
|
lua_run("lua_func3", "$rU", "2", "$si");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="app_lua.f.lua_runstring">
|
|
<title>
|
|
<function moreinfo="none">lua_runstring(script)</function>
|
|
</title>
|
|
<para>
|
|
Execute the Lua script stored in parameter. The parameter can be
|
|
a string with pseudo-variables. The script is executed in Lua context
|
|
specific to loaded Lua files at startup.
|
|
</para>
|
|
<example>
|
|
<title><function>lua_runstring</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if(!lua_runstring("KSR.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>RPC Commands</title>
|
|
<section id="app_lua.r.list">
|
|
<title>
|
|
<function moreinfo="none">app_lua.list</function>
|
|
</title>
|
|
<para>
|
|
Lists the id and path for every script loaded by
|
|
the load parameter.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>app_lua.list</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&kamcmd; app_lua.list
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section id="app_lua.r.reload">
|
|
<title>
|
|
<function moreinfo="none">app_lua.reload</function>
|
|
</title>
|
|
<para>
|
|
Marks the need to reload the selected script.
|
|
The actual reload is done by every working process when the next
|
|
call to lua_run function is executed.
|
|
If no parameter is added all the scripts are selected to be reloaded.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>app_lua.reload</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>id</emphasis></para>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&kamcmd; app_lua.reload 0
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
<section id="app_lua.r.api_list">
|
|
<title>
|
|
<function moreinfo="none">app_lua.api_list</function>
|
|
</title>
|
|
<para>
|
|
Lists the exported KEMI functions that can be used inside Lua
|
|
scripts.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>app_lua.api_list</emphasis>
|
|
</para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>
|
|
Example:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&kamcmd; app_lua.api_list
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example of usage</title>
|
|
<para>
|
|
Create your Lua script and stored on file system,
|
|
say: '/usr/local/etc/kamailio/lua/myscript.lua'.
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
function sr_append_fu_to_reply()
|
|
KSR.hdr.append_to_reply("P-From: " .. KSR.pv.get("$fu") .. "\r\n");
|
|
end
|
|
...
|
|
</programlisting>
|
|
<para>
|
|
Load the script via parameter 'load' and execute function
|
|
via lua_run(...).
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
|
|
...
|
|
route {
|
|
...
|
|
if(!lua_run("sr_append_fu_to_reply"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua function!\n");
|
|
}
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</section>
|
|
</chapter>
|
|
|