1app_lua Module 2 3Daniel-Constantin Mierla 4 5 asipto.com 6 7Edited by 8 9Daniel-Constantin Mierla 10 11 <miconda@gmail.com> 12 13 Copyright © 2010 Daniel-Constantin Mierla (asipto.com) 14 __________________________________________________________________ 15 16 Table of Contents 17 18 1. Admin Guide 19 20 1. Overview 21 2. Dependencies 22 23 2.1. Kamailio Modules 24 2.2. External Libraries or Applications 25 26 3. Parameters 27 28 3.1. load (string) 29 3.2. reload (boolean) 30 3.3. log_mode (int) 31 32 4. Functions 33 34 4.1. lua_dofile(path) 35 4.2. lua_dostring(script) 36 4.3. lua_run(func [, params]) 37 4.4. lua_runstring(script) 38 39 5. RPC Commands 40 41 5.1. app_lua.list 42 5.2. app_lua.reload 43 5.3. app_lua.api_list 44 45 6. Example of usage 46 47 List of Examples 48 49 1.1. Build against LuaJIT libraries 50 1.2. Set load parameter 51 1.3. Set reload parameter 52 1.4. Set log_mode parameter 53 1.5. lua_dofile usage 54 1.6. lua_dostring usage 55 1.7. lua_run usage 56 1.8. lua_runstring usage 57 58Chapter 1. Admin Guide 59 60 Table of Contents 61 62 1. Overview 63 2. Dependencies 64 65 2.1. Kamailio Modules 66 2.2. External Libraries or Applications 67 68 3. Parameters 69 70 3.1. load (string) 71 3.2. reload (boolean) 72 3.3. log_mode (int) 73 74 4. Functions 75 76 4.1. lua_dofile(path) 77 4.2. lua_dostring(script) 78 4.3. lua_run(func [, params]) 79 4.4. lua_runstring(script) 80 81 5. RPC Commands 82 83 5.1. app_lua.list 84 5.2. app_lua.reload 85 5.3. app_lua.api_list 86 87 6. Example of usage 88 891. Overview 90 91 This module allows executing Lua scripts from config file, implementing 92 the KEMI framework and exporting Lua module 'KSR'. 93 94 To read more about KEMI exports and available KSR submodules, see: 95 * http://kamailio.org/docs/tutorials/devel/kamailio-kemi-framework/ 96 97 Note: to have the old Lua module 'sr' available, load the 'app_lua_sr' 98 Kamailio module. 99 100 Lua (http://www.lua.org) is a fast and easy to embed scripting 101 language. Exported API from SIP router to Lua is documented in the 102 dokuwiki. 103 104 The module has two Lua contexts: 105 * first is used for functions lua_dofile() and lua_dostring(). 106 * second is used for function lua_run() and parameter 'load'. 107 Therefore lua_run() cannot execute functions from scripts loaded 108 via lua_dofile() in config. This is kind of caching mode, avoiding 109 reading file every time, but you must be sure you do not have 110 something that is executed by default and requires access to SIP 111 message. This is also the context used with KEMI framework. 112 1132. Dependencies 114 115 2.1. Kamailio Modules 116 2.2. External Libraries or Applications 117 1182.1. Kamailio Modules 119 120 The following modules must be loaded before this module: 121 * none. 122 1232.2. External Libraries or Applications 124 125 The following libraries or applications must be installed before 126 running Kamailio with this module loaded: 127 * liblua5.1-dev - Lua devel library. 128 129 This module can be compiled against LuaJIT compiler (instead of 130 standard Lua). Then this library is needed: 131 * libluajit-5.1-dev - LuaJIT devel library. 132 133 To enable that, LUAJIT variable has to be set. 134 135 Example 1.1. Build against LuaJIT libraries 136 E.g: $ LUAJIT="yes" make modules modules=modules/app_lua 137 138 (Warning: LuaJIT version is 5.1, so scripts prepared for higher Lua 139 versions may not work with LuaJIT) 140 1413. Parameters 142 143 3.1. load (string) 144 3.2. reload (boolean) 145 3.3. log_mode (int) 146 1473.1. load (string) 148 149 Set the path to the Lua script to be loaded at startup. Then you can 150 use lua_run(function, params) to execute a function from the script at 151 runtime. 152 153 Default value is “null”. 154 155 Example 1.2. Set load parameter 156... 157modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua") 158... 159 1603.2. reload (boolean) 161 162 If reload is 1 enables the ability to reload the scripts using the RPC 163 app_lua.reload command. To disable reload feature, set this parameter 164 to 0. 165 166 Default value is “1 (on)”. 167 168 Example 1.3. Set reload parameter 169... 170modparam("app_lua", "reload", 0) 171... 172 1733.3. log_mode (int) 174 175 Control what is printed in log messages. If bit 1 is set, then the 176 module prints debug messages for each KEMI export. 177 178 Default value is “0”. 179 180 Example 1.4. Set log_mode parameter 181... 182modparam("app_lua", "log_mode", 1) 183... 184 1854. Functions 186 187 4.1. lua_dofile(path) 188 4.2. lua_dostring(script) 189 4.3. lua_run(func [, params]) 190 4.4. lua_runstring(script) 191 1924.1. lua_dofile(path) 193 194 Execute the Lua script stored in 'path'. The parameter can be a string 195 with pseudo-variables evaluated at runtime. 196 197 Example 1.5. lua_dofile usage 198... 199lua_dofile("/usr/local/etc/kamailio/lua/myscript.lua"); 200... 201 2024.2. lua_dostring(script) 203 204 Execute the Lua script stored in parameter. The parameter can be a 205 string with pseudo-variables. 206 207 Example 1.6. lua_dostring usage 208... 209if(!lua_dostring("KSR.log([[err]], [[----------- Hello World from $fU\n]])")) 210{ 211 xdbg("SCRIPT: failed to execute lua script!\n"); 212} 213... 214 2154.3. lua_run(func [, params]) 216 217 Execute the Lua function 'func' giving 'params' as parameters. There 218 can be up to 3 string parameters after 'func' (overall, max 4 params, 219 first is the function). The function must exist in the Lua script 220 loaded at startup via parameter 'load'. Parameters can be strings with 221 pseudo-variables that are evaluated at runtime. 222 223 Example 1.7. lua_run usage 224... 225if(!lua_run("sr_append_fu_to_reply")) { 226 xdbg("SCRIPT: failed to execute lua function!\n"); 227} 228... 229lua_run("lua_func0"); 230lua_run("lua_func1", "$rU"); 231lua_run("lua_func2", "$rU", "2"); 232lua_run("lua_func3", "$rU", "2", "$si"); 233... 234 2354.4. lua_runstring(script) 236 237 Execute the Lua script stored in parameter. The parameter can be a 238 string with pseudo-variables. The script is executed in Lua context 239 specific to loaded Lua files at startup. 240 241 Example 1.8. lua_runstring usage 242... 243if(!lua_runstring("KSR.log([[err]], [[----------- Hello World from $fU\n]])")) 244{ 245 xdbg("SCRIPT: failed to execute lua script!\n"); 246} 247... 248 2495. RPC Commands 250 251 5.1. app_lua.list 252 5.2. app_lua.reload 253 5.3. app_lua.api_list 254 2555.1. app_lua.list 256 257 Lists the id and path for every script loaded by the load parameter. 258 259 Name: app_lua.list 260 261 Parameters: none 262 263 Example: 264... 265 kamcmd app_lua.list 266... 267 2685.2. app_lua.reload 269 270 Marks the need to reload the selected script. The actual reload is done 271 by every working process when the next call to lua_run function is 272 executed. If no parameter is added all the scripts are selected to be 273 reloaded. 274 275 Name: app_lua.reload 276 277 Parameters: id 278 279 Example: 280... 281 kamcmd app_lua.reload 0 282... 283 2845.3. app_lua.api_list 285 286 Lists the exported KEMI functions that can be used inside Lua scripts. 287 288 Name: app_lua.api_list 289 290 Parameters: none 291 292 Example: 293... 294 kamcmd app_lua.api_list 295... 296 2976. Example of usage 298 299 Create your Lua script and stored on file system, say: 300 '/usr/local/etc/kamailio/lua/myscript.lua'. 301... 302function sr_append_fu_to_reply() 303 KSR.hdr.append_to_reply("P-From: " .. KSR.pv.get("$fu") .. "\r\n"); 304end 305... 306 307 Load the script via parameter 'load' and execute function via 308 lua_run(...). 309... 310modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua") 311... 312route { 313 ... 314 if(!lua_run("sr_append_fu_to_reply")) 315 { 316 xdbg("SCRIPT: failed to execute lua function!\n"); 317 } 318 ... 319} 320... 321