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.
264 lines
6.5 KiB
264 lines
6.5 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 "../../../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. It exports
|
|
a set of functions to Lua in order to access the current processed
|
|
SIP message. These functions are within Lua module 'sr'.
|
|
</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 someting that is executed by default and requires
|
|
access to SIP message.
|
|
</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.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Exported Parameters</title>
|
|
<section>
|
|
<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.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>load</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title><varname>register</varname> (string)</title>
|
|
<para>
|
|
Use this function to register optional SIP Router submodules
|
|
to Lua. Available submodules are:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sl</emphasis> - register functions from sl module
|
|
under 'sr.sl'.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Note that 'sr', 'sr.hdr' and 'sr.pv' modules are always registered
|
|
to Lua.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>null</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>register</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("lua", "register", "sr")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Exported Functions</title>
|
|
<section>
|
|
<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>
|
|
<title>
|
|
<function moreinfo="none">lua_dostring(script)</function>
|
|
</title>
|
|
<para>i
|
|
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("sr.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">lua_run(function, params)</function>
|
|
</title>
|
|
<para>
|
|
Execute the Lua 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.
|
|
</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_funcx", "$rU", "2");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">lua_runstring(script)</function>
|
|
</title>
|
|
<para>i
|
|
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("sr.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</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()
|
|
sr.hdr.append_to_reply("P-From: " .. sr.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>
|
|
|