This wiki discusses the adding and configuring of OpenLiteSpeed’s Lua module (mod_lua). Using this module, OpenLiteSpeed offers a convenient and efficient interface to the proven, fast, powerful scripting language, Lua.
For this guide, we assume you already have a working installation of OpenLiteSpeed 1.4.0 or higher. Module support is available in versions 1.3 or higher, but the Lua module is only available and supported starting with version 1.4.0. If the
mod_lua.so dynamic library is not in the OpenLiteSpeed
modules directory, the Lua module must be built.
LuaJIT is a Just-In-Time Compiler for the Lua programming language. This open source software provides LiteSpeed’s interface to Lua. If the LuaJIT library
libluajit.so is not currently installed, you should download the current version from luajit.org. Follow the installation instructions from this site. Note, however, that for LiteSpeed execution, the only necessary component of LuaJIT is
Building the LiteSpeed Lua module
Download OpenLiteSpeed 1.4.0 or higher if you have not done so. The Lua module is available starting with OpenLiteSpeed version 1.4.0.
Install OpenLiteSpeed with Lua.
There are some special considerations when building and installing LiteSpeed with the Lua module. If installing a complete system from download, an additional parameter must be specified to LiteSpeed’s
configure program to indicate Lua module compilation and where the LuaJIT header files exist.
If header files are in a standard directory:
./configure --with-lua=yes ... Else to specify the LuaJIT header file directory (recommended); e.g., /home/user/LuaJIT-2.0.3/src: ./configure --with-lua=/home/user/LuaJIT-2.0.3/src ...
After installation, the
mod_lua.so dynamic library is in the system
modules directory. Proceed on to registering the module.
Making the Lua Module Separately
If your installation of OpenLiteSpeed 1.4 (or higher) does not have Lua support, (e.g., it was not configured properly, or it was later decided to add Lua), the Lua module can not be added later using the general steps for adding modules. It is recommended that you reinstall with Lua support. If you do not wish to do so, though, you can follow the steps below to make the Lua module separately:
- Edit the
Makefile.ffile to correctly specify the location of LuaJIT components such as header files.
- Run the command
make -f Makefile.f(instead of the default
make) to create the library.
Registering the Module
Add the Lua module by going to WebAdmin Console > Server Configuration > Modules > Add
Enter the name of the module as
A number of user parameters may be specified. Most important is the location of the LuaJIT library
libluajit.so if not in the default
/usr/local/lib/ directory. Configuring these settings will be covered in the Configuration section below.
The default for the lib parameter is:
If the LuaJIT library is located somewhere else, if can be set as follows:
Save the module settings.
Gracefully Restart the server.
The module can be further configured at the virtual host, context, and script handler levels. More specific levels of configuration will always override more general levels. For example, virtual host-level configurations override server-level configurations and context-level configurations override virtual host-level configurations. Configurations are covered in the Configuration section below.
The Lua module executes Lua scripts as a script handler. By convention, Lua scripts are designated with suffix
Add the Lua module as a script handler by going to WebAdmin Console > Server Configuration > Script Handler > Add
- Suffix =
- Handler Type =
- Handler Name =
Save the script handler settings.
NOTE: Make sure after any configuration change the server is restarted.
Create a Lua script
hello.lua in a virtual host html directory:
ls.say(ls.logtime(), "LiteSpeed: Hello", _VERSION)
The default OpenLiteSpeed installation sets up a Virtual Host named
Example mapped to Listener
Default at Port 8088 with various files in its
html subdirectory. Put the test Lua script here.
Run the Lua script from a browser:
or alternatively, use
user@host> curl -k -i http://localhost:8088/hello.lua HTTP/1.1 200 OK Content-Length: 56 Date: Wed, 16 Jul 2014 15:08:16 GMT Server: LiteSpeed
In the WebAdmin Console, set:
- lib = The location of the LuaJIT library. (Default =
- maxruntime = The maximum script runtime in millisec. (Default = 0, no limit)
All modules must be registered at the server level. Once a module is registered, it’s settings are inherited by more specific setting levels (virtual host, context, and script handler). Configurations can be modified at these more specific levels. Settings at more specific levels always override more general levels. For example, virtual host-level configurations override server-level configurations and context-level configurations override virtual host-level configurations.
Lua in OpenLitespeed is intended to follow the OpenResty Lua specification API specified here: https://github.com/openresty/lua-nginx-module#nginx-api-for-lua
When using the Lua functions in the spec, you can use either the ngx or ls prefix. Thus ngx.print will work as will ls.print.