lua Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Installing the module
        1.3. Using the module
        1.4. Dependencies

              1.4.1. OpenSIPS Modules
              1.4.2. External Libraries or Applications

        1.5. Exported Parameters

              1.5.1. luafilename (string)
              1.5.2. lua_auto_reload (int)
              1.5.3. warn_missing_free_fixup (int)
              1.5.4. lua_allocator (string)

        1.6. Exported Functions

              1.6.1. lua_exec(func, [param])
              1.6.2. lua_meminfo()

        1.7. Exported MI Functions

              1.7.1. watch

   2. OpenSIPS Lua API

        2.1. Available functions

              2.1.1. xdbg(message)
              2.1.2. xlog([level],message)
              2.1.3. WarnMissingFreeFixup
              2.1.4. getpid
              2.1.5. getmem
              2.1.6. getmeminfo
              2.1.7. gethostname
              2.1.8. getType(msg)
              2.1.9. isMyself(host, port)
              2.1.10. grepSockInfo(host, port)
              2.1.11. getURI_User(msg)
              2.1.12. getExpires(msg)
              2.1.13. getHeader(msg, header)
              2.1.14. getContact(msg)
              2.1.15. getRoute(msg)
              2.1.16. moduleFunc(msg, function, args1, args2, ...)
              2.1.17. getStatus(msg)
              2.1.18. getMethod(msg)
              2.1.19. getSrcIp(msg)
              2.1.20. getDstIp(msg)
              2.1.21. AVP_get(name)
              2.1.22. AVP_set(name, value)
              2.1.23. AVP_destroy(name)
              2.1.24. pseudoVar(msg, variable)
              2.1.25. pseudoVarSet(msg, variable, value)
              2.1.26. scriptVarGet(variable)
              2.1.27. scriptVarSet(variable, value)
              2.1.28. add_lump_rpl(msg, header)

   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set luafilename parameter
   1.2. lua_exec() usage

Chapter 1. Admin Guide

1.1. Overview

   The time needed when writing a new OpenSIPS module
   unfortunately is quite high, while the options provided by the
   configuration file are limited to the features implemented in
   the modules.

   With this Lua module, you can easily implement your own
   OpenSIPS extensions in Lua.

1.2. Installing the module

   This Lua module is loaded in opensips.cfg (just like all the
   other modules) with loadmodule("/path/to/lua.so");.

   For the Lua module to compile, you need a recent version of Lua
   (tested with 5.1) linked dynamically. The default version of
   your favorite Linux distribution should work fine.

1.3. Using the module

   With the Lua module, you can access to lua function on the
   OpenSIPS side. You need to define a file to load and call a
   function from it. Write a function "mongo_alias" and then write
   in your opensips.cfg
...
if (lua_exec("mongo_alias")) {
        ...
}
...

   On the Lua side, you have access to opensips functions and
   variables (AVP, pseudoVar, ...). Read the documentation below
   for further informations.

1.4. Dependencies

1.4.1. OpenSIPS Modules

   None ;-)

1.4.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * Lua 5.1.x or later
     * memcached

   This module has been developed and tested with Lua 5.1.?, but
   should work with any 5.1.x release. Earlier versions do not
   work.

   On current Debian systems, at least the following packages
   should be installed:
     * lua5.1
     * liblua5.1-0-dev
     * libmemcached-dev
     * libmysqlclient-dev

   It was reported that other Debian-style distributions (such as
   Ubuntu) need the same packages.

   On OpenBSD systems, at least the following packages should be
   installed:
     * Lua

1.5. Exported Parameters

1.5.1. luafilename (string)

   This is the file name of your script. This may be set once
   only, but it may include an arbitary number of functions and
   "use" as many Lua module as necessary.

   The default value is "/etc/opensips/opensips.lua"

   Example 1.1. Set luafilename parameter
...
modparam("lua", "luafilename", "/etc/opensips/opensips.lua")
...

1.5.2. lua_auto_reload (int)

   Define this value to 1 if you want to reload automatically the
   lua script. Disabled by default.

1.5.3. warn_missing_free_fixup (int)

   When you call a function via moduleFunc() you could have a
   memleak. Enable this warns you when you're doing it. Enabled by
   default.

1.5.4. lua_allocator (string)

   Change the default memory allocator for the lua module.
   Possible values are :
     * opensips (default)
     * malloc

1.6. Exported Functions

1.6.1. lua_exec(func, [param])

   Calls a Lua function with passing it the current SIP message.
   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   ONREPLY_ROUTE and BRANCH_ROUTE.

   Parameters:
     * func (string) - Lua function name
     * param (string, optional) - Parameter to be passed to the
       Lua function.

   Example 1.2. lua_exec() usage
...
if (lua_exec("mongo_alias")) {
        ...
}
...

1.6.2. lua_meminfo()

   Logs informations about memory.

1.7. Exported MI Functions

1.7.1.  watch

   Name: watch

   Parameters: none
     * action (optional) - 'add' or 'delete'
     * extension (optional) - required if action is provided

   MI FIFO Command Format:
  opensips-cli -x mi watch

Chapter 2. OpenSIPS Lua API

2.1. Available functions

   This module provides access to a limited number of OpenSIPS
   core functions.

2.1.1. xdbg(message)

   An alias for xlog(DBG, message)

2.1.2. xlog([level],message)

   Logs the message with OpenSIPS's logging facility. The logging
   level is one of the following:
     * ALERT
     * CRIT
     * ERR
     * WARN
     * NOTICE
     * INFO
     * DBG

2.1.3. WarnMissingFreeFixup

   Dynamically change the variable warn_missing_free_fixup.

2.1.4. getpid

   Returns the current pid.

2.1.5. getmem

   Returns a table with the size of allocated memory and the
   fragmentation.

2.1.6. getmeminfo

   Returns a table with memory infos.

2.1.7. gethostname

   Returns the value of the current hostname.

2.1.8. getType(msg)

   Returns "SIP_REQUEST" or "SIP_REPLY".

2.1.9. isMyself(host, port)

   Test if the host and optionally the port represent one of the
   addresses that OpenSIPS listens on.

2.1.10. grepSockInfo(host, port)

   Similar to isMyself(), but without taking a look into the
   aliases.

2.1.11. getURI_User(msg)

   Returns the user of the To URI.

2.1.12. getExpires(msg)

   Returns the expires header of the current message.

2.1.13. getHeader(msg, header)

   Returns the value of the specified header.

2.1.14. getContact(msg)

   Returns a table with the contact header.

2.1.15. getRoute(msg)

   Returns a table with the Route header.

2.1.16. moduleFunc(msg, function, args1, args2, ...)

   You can pass arguments to this function.

2.1.17. getStatus(msg)

   Returns the current status if the SIP message is a SIP_REPLY.

2.1.18. getMethod(msg)

   Returns the current method.

2.1.19. getSrcIp(msg)

   Returns the IP address of the source.

2.1.20. getDstIp(msg)

   Returns the IP address of the destination.

2.1.21. AVP_get(name)

   Returns an AVP variable.

2.1.22. AVP_set(name, value)

   Defines an AVP variable.

2.1.23. AVP_destroy(name)

   Destroys an AVP variable.

2.1.24. pseudoVar(msg, variable)

   Returns a pseudoVar.

2.1.25. pseudoVarSet(msg, variable, value)

   Sets the value of a pseudoVar.

2.1.26. scriptVarGet(variable)

   Returns a script variable.

2.1.27. scriptVarSet(variable, value)

   Sets the value of a script variable.

2.1.28. add_lump_rpl(msg, header)

   Add header to the reply.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Arnaud Chong + Eric Gouyer 38 1 4335 0
   2. Razvan Crainea (@razvancrainea) 34 27 274 230
   3. Vlad Patrascu (@rvlad-patrascu) 25 17 319 276
   4. Liviu Chircu (@liviuchircu) 13 10 15 63
   5. Bogdan-Andrei Iancu (@bogdan-iancu) 8 6 9 3
   6. Maksym Sobolyev (@sobomax) 7 5 16 13
   7. Vlad Paiu (@vladpaiu) 5 3 7 9
   8. Julián Moreno Patiño 3 1 1 1
   9. Peter Lemenkov (@lemenkov) 3 1 1 1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                     Name                   Commit Activity
   1. Maksym Sobolyev (@sobomax)          Feb 2023 - Nov 2023
   2. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Jun 2023
   3. Razvan Crainea (@razvancrainea)     Feb 2012 - Feb 2023
   4. Bogdan-Andrei Iancu (@bogdan-iancu) May 2014 - Jan 2020
   5. Liviu Chircu (@liviuchircu)         Mar 2014 - Mar 2019
   6. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   7. Julián Moreno Patiño                Feb 2016 - Feb 2016
   8. Vlad Paiu (@vladpaiu)               Feb 2012 - Jun 2012
   9. Arnaud Chong + Eric Gouyer          Dec 2011 - Dec 2011

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Razvan Crainea
   (@razvancrainea), Peter Lemenkov (@lemenkov), Liviu Chircu
   (@liviuchircu), Vlad Paiu (@vladpaiu), Arnaud Chong + Eric
   Gouyer.

   Documentation Copyrights:

   Copyright © 2006-2011 Arnaud Chong, Eric Gouyer