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.
322 lines
7.5 KiB
322 lines
7.5 KiB
app_lua Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
asipto.com
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Copyright © 2010 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 (string)
|
|
3.2. reload (boolean)
|
|
3.3. log_mode (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. lua_dofile(path)
|
|
4.2. lua_dostring(script)
|
|
4.3. lua_run(func [, params])
|
|
4.4. lua_runstring(script)
|
|
|
|
5. RPC Commands
|
|
|
|
5.1. app_lua.list
|
|
5.2. app_lua.reload
|
|
5.3. app_lua.api_list
|
|
|
|
6. Example of usage
|
|
|
|
List of Examples
|
|
|
|
1.1. Build against LuaJIT libraries
|
|
1.2. Set load parameter
|
|
1.3. Set reload parameter
|
|
1.4. Set log_mode parameter
|
|
1.5. lua_dofile usage
|
|
1.6. lua_dostring usage
|
|
1.7. lua_run usage
|
|
1.8. lua_runstring 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 (string)
|
|
3.2. reload (boolean)
|
|
3.3. log_mode (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. lua_dofile(path)
|
|
4.2. lua_dostring(script)
|
|
4.3. lua_run(func [, params])
|
|
4.4. lua_runstring(script)
|
|
|
|
5. RPC Commands
|
|
|
|
5.1. app_lua.list
|
|
5.2. app_lua.reload
|
|
5.3. app_lua.api_list
|
|
|
|
6. Example of usage
|
|
|
|
1. Overview
|
|
|
|
This module allows executing Lua scripts from config file, implementing
|
|
the KEMI framework and exporting Lua module 'KSR'.
|
|
|
|
To read more about KEMI exports and available KSR submodules, see:
|
|
* https://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/
|
|
|
|
Note: to have the old Lua module 'sr' available, load the 'app_lua_sr'
|
|
Kamailio module.
|
|
|
|
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.
|
|
|
|
The module has two Lua contexts:
|
|
* first is used for functions lua_dofile() and lua_dostring().
|
|
* second 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.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* none.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* liblua5.1-dev - Lua devel library. Versions 5.2, 5.3 and 5.4 also
|
|
work.
|
|
|
|
This module can be compiled against LuaJIT compiler (instead of
|
|
standard Lua). Then this library is needed:
|
|
* libluajit-5.1-dev - LuaJIT devel library.
|
|
|
|
To enable that, LUAJIT variable has to be set.
|
|
|
|
Example 1.1. Build against LuaJIT libraries
|
|
E.g: $ LUAJIT="yes" make modules modules=modules/app_lua
|
|
|
|
(Warning: LuaJIT version is 5.1, so scripts prepared for higher Lua
|
|
versions may not work with LuaJIT)
|
|
|
|
3. Parameters
|
|
|
|
3.1. load (string)
|
|
3.2. reload (boolean)
|
|
3.3. log_mode (int)
|
|
|
|
3.1. load (string)
|
|
|
|
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.
|
|
|
|
Default value is “null”.
|
|
|
|
Example 1.2. Set load parameter
|
|
...
|
|
modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
|
|
...
|
|
|
|
3.2. reload (boolean)
|
|
|
|
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.
|
|
|
|
Default value is “1 (on)”.
|
|
|
|
Example 1.3. Set reload parameter
|
|
...
|
|
modparam("app_lua", "reload", 0)
|
|
...
|
|
|
|
3.3. log_mode (int)
|
|
|
|
Control what is printed in log messages. If bit 1 is set, then the
|
|
module prints debug messages for each KEMI export.
|
|
|
|
Default value is “0”.
|
|
|
|
Example 1.4. Set log_mode parameter
|
|
...
|
|
modparam("app_lua", "log_mode", 1)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. lua_dofile(path)
|
|
4.2. lua_dostring(script)
|
|
4.3. lua_run(func [, params])
|
|
4.4. lua_runstring(script)
|
|
|
|
4.1. lua_dofile(path)
|
|
|
|
Execute the Lua script stored in 'path'. The parameter can be a string
|
|
with pseudo-variables evaluated at runtime.
|
|
|
|
Example 1.5. lua_dofile usage
|
|
...
|
|
lua_dofile("/usr/local/etc/kamailio/lua/myscript.lua");
|
|
...
|
|
|
|
4.2. lua_dostring(script)
|
|
|
|
Execute the Lua script stored in parameter. The parameter can be a
|
|
string with pseudo-variables.
|
|
|
|
Example 1.6. lua_dostring usage
|
|
...
|
|
if(!lua_dostring("KSR.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
|
|
4.3. lua_run(func [, params])
|
|
|
|
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.
|
|
|
|
Example 1.7. lua_run usage
|
|
...
|
|
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");
|
|
...
|
|
|
|
4.4. lua_runstring(script)
|
|
|
|
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.
|
|
|
|
Example 1.8. lua_runstring usage
|
|
...
|
|
if(!lua_runstring("KSR.log([[err]], [[----------- Hello World from $fU\n]])"))
|
|
{
|
|
xdbg("SCRIPT: failed to execute lua script!\n");
|
|
}
|
|
...
|
|
|
|
5. RPC Commands
|
|
|
|
5.1. app_lua.list
|
|
5.2. app_lua.reload
|
|
5.3. app_lua.api_list
|
|
|
|
5.1. app_lua.list
|
|
|
|
Lists the id and path for every script loaded by the load parameter.
|
|
|
|
Name: app_lua.list
|
|
|
|
Parameters: none
|
|
|
|
Example:
|
|
...
|
|
kamcmd app_lua.list
|
|
...
|
|
|
|
5.2. app_lua.reload
|
|
|
|
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.
|
|
|
|
Name: app_lua.reload
|
|
|
|
Parameters: id
|
|
|
|
Example:
|
|
...
|
|
kamcmd app_lua.reload 0
|
|
...
|
|
|
|
5.3. app_lua.api_list
|
|
|
|
Lists the exported KEMI functions that can be used inside Lua scripts.
|
|
|
|
Name: app_lua.api_list
|
|
|
|
Parameters: none
|
|
|
|
Example:
|
|
...
|
|
kamcmd app_lua.api_list
|
|
...
|
|
|
|
6. Example of usage
|
|
|
|
Create your Lua script and stored on file system, say:
|
|
'/usr/local/etc/kamailio/lua/myscript.lua'.
|
|
...
|
|
function sr_append_fu_to_reply()
|
|
KSR.hdr.append_to_reply("P-From: " .. KSR.pv.get("$fu") .. "\r\n");
|
|
end
|
|
...
|
|
|
|
Load the script via parameter 'load' and execute function via
|
|
lua_run(...).
|
|
...
|
|
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");
|
|
}
|
|
...
|
|
}
|
|
...
|