modules/ims_qos: added patch for flow-description bug when request originates from...
[sip-router] / src / modules / app_lua / doc / app_lua_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14
15     <title>&adminguide;</title>
16
17     <section>
18         <title>Overview</title>
19         <para>
20                 This module allows executing Lua scripts from config file. It exports
21                 a set of functions to Lua in order to access the current processed
22                 SIP message. These functions are within Lua module 'sr'.
23         </para>
24         <para>
25                 Lua (http://www.lua.org) is a fast and easy to embed scripting
26                 language. Exported API from SIP router to Lua is documented in the
27                 dokuwiki.
28         </para>
29         <para>
30                 The module has two Lua contexts:
31         <itemizedlist>
32             <listitem>
33                 <para>
34                         <emphasis>first</emphasis> is used for functions lua_dofile()
35                         and lua_dostring().
36                 </para>
37             </listitem>
38             <listitem>
39                 <para>
40                     <emphasis>second</emphasis> is used for function lua_run()
41                         and parameter 'load'. Therefore lua_run() cannot execute functions
42                         from scripts loaded via lua_dofile() in config. This is kind of
43                         caching mode, avoiding reading file every time, but you must be sure
44                         you do not have someting that is executed by default and requires
45                         access to SIP message.
46                 </para>
47             </listitem>
48         </itemizedlist>
49         </para>
50     </section>
51     <section>
52         <title>Dependencies</title>
53         <section>
54             <title>&kamailio; Modules</title>
55             <para>
56                 The following modules must be loaded before this module:
57                 <itemizedlist>
58                     <listitem>
59                         <para>
60                             <emphasis>none</emphasis>.
61                         </para>
62                     </listitem>
63                 </itemizedlist>
64             </para>
65         </section>
66         <section>
67             <title>External Libraries or Applications</title>
68             <para>
69                 The following libraries or applications must be installed before running
70                 &kamailio; with this module loaded:
71                 <itemizedlist>
72                     <listitem>
73                         <para>
74                             <emphasis>liblua5.1-dev</emphasis> - Lua devel library.
75                         </para>
76                     </listitem>
77                 </itemizedlist>
78             </para>
79         </section>
80     </section>
81     <section>
82         <title>Parameters</title>
83         <section id="app_lua.p.load">
84             <title><varname>load</varname> (string)</title>
85             <para>
86                         Set the path to the Lua script to be loaded at startup. Then you
87                         can use lua_run(function, params) to execute a function from the
88                         script at runtime.
89             </para>
90             <para>
91                 <emphasis>
92                     Default value is <quote>null</quote>.
93                 </emphasis>
94             </para>
95             <example>
96                 <title>Set <varname>load</varname> parameter</title>
97                 <programlisting format="linespecific">
98 ...
99 modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
100 ...
101 </programlisting>
102             </example>
103         </section>
104
105         <section id="app_lua.p.register">
106             <title><varname>register</varname> (string)</title>
107             <para>
108                         Use this function to register optional SIP Router submodules
109                         to Lua. Available submodules are:
110             </para>
111                 <itemizedlist>
112                     <listitem>
113                         <para>
114                                 <emphasis>alias_db</emphasis> - register functions from
115                                 alias_db module under 'sr.alias_db'.
116                         </para>
117                     </listitem>
118                     <listitem>
119                         <para>
120                                 <emphasis>auth</emphasis> - register functions from auth module
121                                 under 'sr.auth'.
122                         </para>
123                     </listitem>
124                     <listitem>
125                         <para>
126                                 <emphasis>auth_db</emphasis> - register functions from auth_db
127                                 module under 'sr.auth_db'.
128                         </para>
129                     </listitem>
130                     <listitem>
131                         <para>
132                                 <emphasis>dispatcher</emphasis> - register functions from
133                                 dispatcher module under 'sr.dispatcher'.
134                         </para>
135                     </listitem>
136                     <listitem>
137                         <para>
138                                 <emphasis>maxfwd</emphasis> - register functions from maxfwd
139                                 module under 'sr.maxfwd'.
140                         </para>
141                     </listitem>
142                     <listitem>
143                         <para>
144                                 <emphasis>msilo</emphasis> - register functions from
145                                 msilo module under 'sr.msilo'.
146                         </para>
147                     </listitem>
148                     <listitem>
149                         <para>
150                                 <emphasis>presence</emphasis> - register functions from
151                                 presence module under 'sr.presence'.
152                         </para>
153                     </listitem>
154                     <listitem>
155                         <para>
156                                 <emphasis>presence_xml</emphasis> - register functions from
157                                 presence_xml module under 'sr.presence_xml'.
158                         </para>
159                     </listitem>
160                     <listitem>
161                         <para>
162                                 <emphasis>pua_usrloc</emphasis> - register functions from
163                                 pua_usrloc module under 'sr.pua_usrloc'.
164                         </para>
165                     </listitem>
166                     <listitem>
167                         <para>
168                                 <emphasis>registrar</emphasis> - register functions from
169                                 registrar module under 'sr.registrar'.
170                         </para>
171                     </listitem>
172                     <listitem>
173                         <para>
174                                 <emphasis>rls</emphasis> - register functions from
175                                 rls module under 'sr.rls'.
176                         </para>
177                     </listitem>
178                     <listitem>
179                         <para>
180                                 <emphasis>rr</emphasis> - register functions from rr module
181                                 under 'sr.rr'.
182                         </para>
183                     </listitem>
184                     <listitem>
185                         <para>
186                                 <emphasis>sanity</emphasis> - register functions from sanity
187                                 module under 'sr.sanity'.
188                         </para>
189                     </listitem>
190                     <listitem>
191                         <para>
192                                 <emphasis>sdpops</emphasis> - register functions from
193                                 sdpops module under 'sr.sdpops'.
194                         </para>
195                     </listitem>
196                     <listitem>
197                         <para>
198                                 <emphasis>siputils</emphasis> - register functions from
199                                 siputils module under 'sr.siputils'.
200                         </para>
201                     </listitem>
202                     <listitem>
203                         <para>
204                                 <emphasis>sl</emphasis> - register functions from sl module
205                                 under 'sr.sl'.
206                         </para>
207                     </listitem>
208                     <listitem>
209                         <para>
210                                 <emphasis>sqlops</emphasis> - register functions from sqlops
211                                 module under 'sr.sqlops'.
212                         </para>
213                     </listitem>
214                     <listitem>
215                         <para>
216                                 <emphasis>textops</emphasis> - register functions from
217                                 textops module under 'sr.textops'.
218                         </para>
219                     </listitem>
220                     <listitem>
221                         <para>
222                                 <emphasis>tm</emphasis> - register functions from tm module
223                                 under 'sr.tm'.
224                         </para>
225                     </listitem>
226                     <listitem>
227                         <para>
228                                 <emphasis>xhttp</emphasis> - register functions from xhttp
229                                 module under 'sr.xhttp'.
230                         </para>
231                     </listitem>
232                 </itemizedlist>
233             <para>
234                         Note that 'sr', 'sr.hdr' and 'sr.pv' modules are always registered
235                         to Lua.
236             </para>
237             <para>
238                 <emphasis>
239                     Default value is <quote>null</quote>.
240                 </emphasis>
241             </para>
242             <example>
243                 <title>Set <varname>register</varname> parameter</title>
244                 <programlisting format="linespecific">
245 ...
246 modparam("app_lua", "register", "sl")
247 ...
248 </programlisting>
249             </example>
250         </section>
251
252         <section id="app_lua.p.reload">
253             <title><varname>reload</varname> (boolean)</title>
254             <para>
255                         If reload is 1 enables the ability to reload the
256                         scripts using the RPC app_lua.reload command.
257             </para>
258             <para>
259                 <emphasis>
260                     Default value is <quote>0 (off)</quote>.
261                 </emphasis>
262             </para>
263             <example>
264                 <title>Set <varname>reload</varname> parameter</title>
265                 <programlisting format="linespecific">
266 ...
267 modparam("app_lua", "reload", 1)
268 ...
269 </programlisting>
270             </example>
271         </section>
272
273         </section>
274
275     <section>
276         <title>Functions</title>
277         <section id="app_lua.f.lua_dotfile">
278             <title>
279                 <function moreinfo="none">lua_dofile(path)</function>
280             </title>
281             <para>
282                 Execute the Lua script stored in 'path'. The parameter can be
283                 a string with pseudo-variables evaluated at runtime.
284             </para>
285                 <example>
286                 <title><function>lua_dofile</function> usage</title>
287                 <programlisting format="linespecific">
288 ...
289 lua_dofile("/usr/local/etc/kamailio/lua/myscript.lua");
290 ...
291 </programlisting>
292             </example>
293         </section>
294
295         <section id="app_lua.f.lua_dostring">
296             <title>
297                 <function moreinfo="none">lua_dostring(script)</function>
298             </title>
299             <para>
300                 Execute the Lua script stored in parameter. The parameter can be
301                 a string with pseudo-variables.
302             </para>
303                 <example>
304                 <title><function>lua_dostring</function> usage</title>
305                 <programlisting format="linespecific">
306 ...
307 if(!lua_dostring("sr.log([[err]], [[----------- Hello World from $fU\n]])"))
308 {
309     xdbg("SCRIPT: failed to execute lua script!\n");
310 }
311 ...
312 </programlisting>
313             </example>
314         </section>
315
316         <section id="app_lua.f.lua_run">
317             <title>
318                 <function moreinfo="none">lua_run(function, params)</function>
319             </title>
320             <para>
321                 Execute the Lua function 'func' giving params as parameters. There
322                 can be up to 3 string parameters. The function must exist in the
323                 script loaded at startup via parameter 'load'. Parameters can be
324                 strings with pseudo-variables that are evaluated at runtime.
325             </para>
326                 <example>
327                 <title><function>lua_run</function> usage</title>
328                 <programlisting format="linespecific">
329 ...
330 if(!lua_run("sr_append_fu_to_reply"))
331 {
332     xdbg("SCRIPT: failed to execute lua function!\n");
333 }
334 ...
335 lua_run("lua_funcx", "$rU", "2");
336 ...
337 </programlisting>
338             </example>
339         </section>
340
341         <section id="app_lua.f.lua_runstring">
342             <title>
343                 <function moreinfo="none">lua_runstring(script)</function>
344             </title>
345             <para>
346                 Execute the Lua script stored in parameter. The parameter can be
347                 a string with pseudo-variables. The script is executed in Lua context
348                 specific to loaded Lua files at startup.
349             </para>
350                 <example>
351                 <title><function>lua_runstring</function> usage</title>
352                 <programlisting format="linespecific">
353 ...
354 if(!lua_runstring("sr.log([[err]], [[----------- Hello World from $fU\n]])"))
355 {
356     xdbg("SCRIPT: failed to execute lua script!\n");
357 }
358 ...
359 </programlisting>
360             </example>
361         </section>
362
363     </section>
364
365     <section>
366         <title>Exported RPC Commands</title>
367         <section id="app_lua.r.list">
368             <title>
369             <function moreinfo="none">app_lua.list</function>
370             </title>
371             <para>
372             Lists the id and path for every script loaded by
373             the load parameter.
374             </para>
375             <para>
376             Name: <emphasis>app_lua.list</emphasis>
377             </para>
378             <para>Parameters: <emphasis>none</emphasis></para>
379             <para>
380             Example:
381             </para>
382             <programlisting  format="linespecific">
383                 &sercmd; app_lua.lists
384             </programlisting>
385         </section>
386         <section id="app_lua.r.reload">
387             <title>
388             <function moreinfo="none">app_lua.reload</function>
389             </title>
390             <para>
391             Marks the need to reload the selected script.
392             The actual reload is done by every working process when the next
393             call to lua_run function is executed.
394             If no parameter is added all the scripts are selected to be reloaded.
395             </para>
396             <para>
397             Name: <emphasis>app_lua.reload</emphasis>
398             </para>
399             <para>Parameters: <emphasis>id</emphasis></para>
400             <para>
401             Example:
402             </para>
403             <programlisting  format="linespecific">
404                 &sercmd; app_lua.reload 0
405             </programlisting>
406         </section>
407     </section>
408
409     <section>
410         <title>Example of usage</title>
411     <para>
412                 Create your Lua script and stored on file system,
413                 say: '/usr/local/etc/kamailio/lua/myscript.lua'.
414     </para>
415 <programlisting format="linespecific">
416 ...
417 function sr_append_fu_to_reply()
418         sr.hdr.append_to_reply("P-From: " .. sr.pv.get("$fu") .. "\r\n");
419 end
420 ...
421 </programlisting>
422     <para>
423                 Load the script via parameter 'load' and execute function
424                 via lua_run(...).
425     </para>
426 <programlisting format="linespecific">
427 ...
428 modparam("app_lua", "load", "/usr/local/etc/kamailio/lua/myscript.lua")
429 ...
430 route {
431     ...
432     if(!lua_run("sr_append_fu_to_reply"))
433     {
434         xdbg("SCRIPT: failed to execute lua function!\n");
435     }
436     ...
437 }
438 ...
439 </programlisting>
440     </section>
441 </chapter>
442