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.
443 lines
12 KiB
443 lines
12 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>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.
|
|
</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.register">
|
|
<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>alias_db</emphasis> - register functions from
|
|
alias_db module under 'sr.alias_db'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>auth</emphasis> - register functions from auth module
|
|
under 'sr.auth'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>auth_db</emphasis> - register functions from auth_db
|
|
module under 'sr.auth_db'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>dispatcher</emphasis> - register functions from
|
|
dispatcher module under 'sr.dispatcher'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>maxfwd</emphasis> - register functions from maxfwd
|
|
module under 'sr.maxfwd'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>msilo</emphasis> - register functions from
|
|
msilo module under 'sr.msilo'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>presence</emphasis> - register functions from
|
|
presence module under 'sr.presence'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>presence_xml</emphasis> - register functions from
|
|
presence_xml module under 'sr.presence_xml'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>pua_usrloc</emphasis> - register functions from
|
|
pua_usrloc module under 'sr.pua_usrloc'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>registrar</emphasis> - register functions from
|
|
registrar module under 'sr.registrar'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>rls</emphasis> - register functions from
|
|
rls module under 'sr.rls'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>rr</emphasis> - register functions from rr module
|
|
under 'sr.rr'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sanity</emphasis> - register functions from sanity
|
|
module under 'sr.sanity'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sdpops</emphasis> - register functions from
|
|
sdpops module under 'sr.sdpops'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>siputils</emphasis> - register functions from
|
|
siputils module under 'sr.siputils'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sl</emphasis> - register functions from sl module
|
|
under 'sr.sl'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sqlops</emphasis> - register functions from sqlops
|
|
module under 'sr.sqlops'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>textops</emphasis> - register functions from
|
|
textops module under 'sr.textops'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>tm</emphasis> - register functions from tm module
|
|
under 'sr.tm'.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>xhttp</emphasis> - register functions from xhttp
|
|
module under 'sr.xhttp'.
|
|
</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("app_lua", "register", "sl")
|
|
...
|
|
</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.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0 (off)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>reload</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("app_lua", "reload", 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("sr.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(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 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("sr.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Exported 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">
|
|
&sercmd; app_lua.lists
|
|
</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">
|
|
&sercmd; app_lua.reload 0
|
|
</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()
|
|
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>
|
|
|