CGILua 5.0

Installing and configuring

Contents

• Choosing a launcher
  
• Building
  • Automatic build
  • Manual build
• Pre-installation
• Installation
• Configuration
  • CGILua Configuration
  • Error Handling

Choosing a launcher

Building

CGILua depends on Lua 5 (it was tested with versions 5.0 through 5.0.2).
The FastCGI launcher depends on a FastCGI developer's kit (it was tested with Open Market's FastCGI library version 2.4.0) and a FastCGI module for the HTTP server (it was tested with Open Market's FastCGI module version 2.4.2).
The Apache module depends on Apache version 2 (it was tested on 2.0.48).
The ISAPI extension has been tested on IIS 5.1 (Windows XP).
The Servlet launcher depends on LuaJava, Log4J and a servlet container (such as Tomcat). It has been tested on Tomcat 5.0.28, with LuaJava 1.0 Beta 4 and Log4J 1.2.9.

Automatic build (CGI, FastCGI and Mod)

CGILua's distribution provides a set of Makefiles that should build the system correctly for the CGI, FastCGI and Mod launchers (ISAPI and Servlet currently require manual building).

The file config should be edited to inform directory names, compiler options and building choices.

After that, a launcher should be chosen: cgi, fcgi or mod. For instance,

  make mod

  make modinstall

The Makefiles use sed to edit the templates and bin2c (provided by the Lua distribution) to convert Lua-compiled code into C source code before compilation of mod_lua.c.

Manual build (all launchers)

There are some binary files that must be built for each launcher:

• CGI
cgi.c is the only source file. It depends on Lua libraries and includes. This is a simple stand-alone interpreter used as the cgi launcher.
• FastCGI
fastcgi.c, lfcgi.c and lfcgi.h are the source files. They depend on Lua and FastCGI libraries and includes. This is a simple stand-alone interpreter used as the fastcgi launcher.
• mod_lua
mod_lua.c and apache2_lib.c are the source files. They depend on Lua and on Apache 2 installation. The Makefile uses the utility libtool that comes with Apache (usually at apache2/build/libtool) to build the module and install it.
• ISAPI
  Compile isapi_lib.c to produce cgilua_isapi.dll.
• Servlet
  You have two options to compile cgilua servlet launcher, use the provided Ant build file or use the provided Makefile.

  Ant

  If you don't know how to use Ant you should read the manual at http://ant.apache.org/manual/index.html.
  Edit the build.xml to modify the properties cgilua.dir and libext.
  

  The cgilua.dir property defines the installation directory for cgilua. This directory is used as the base for lua modules loading.

  The libext property must contain the shared library extension used by your OS. Example:

• Windows: ".dll"
• MacOS: ".dylib"
• Unix: ".so"

          After editing the build.xml file, run the default target.

        Makefile

• lfs
lfs.c and lfs.h are the source files. They depend on Lua 5.0 and Compat-5.1 or Lua 5.1.

Pre-installation: editing template files

CGILua 5.0 follows some improvements added by Lua 5.1. Therefore, if CGILua is compiled using Lua 5.0 it will need the compatibilization package Compat-5.1 which redefines some functions according to the new behavior. Each launcher checks the Lua _VERSION variable to decide if the compatibilization file should be loaded.

The variables _PATH and _CPATH are also checked and defined (if needed) to assure the system will function correctly. However, to correctly define these variables, the launcher script should be edited. The set of Makefiles use sed to do that automatically: the scripts are provided as templates (with a t_ prefix); some strings in capital letters should be substituted by the values defined in the config file; the resulting file should be saved without the t_ prefix. Note that sometimes the strings are quoted: the quotes should be maintained.

Configuration samples

t_fastcgi.conf

The file launcher/fastcgi/t_fastcgi.conf is a sample Apache configuration (.conf) file; the string FCGI_DIR must be replaced by the FastCGI installation directory. The contents of the file could be copied to the Apache main configuration file (httpd.conf) or it could be Included there.

t_mod2.conf

The file launcher/mod2/t_mod2.conf is a sample configuration for the Apache 2 module; the string CGILUA_DIR must be replaced by the directory where CGILua is installed. Note that the directive LuaMain is ignored if the launcher/mod2/mod2.lua is pre-compiled and included in the C source file (default option).

Installation

CGILua's architecture is divided into two layers. The lower level is closer to the web server and to the operating system and is represented by the launchers implementation of the Server API (SAPI); the higher level is represented by the CGILua API and is portable over the launchers.

Following this division, the installation is also divided into two parts. One is closely related to the HTTP server and the launcher while the other does not depend even on the launcher.

Launcher installation

CGI, FastCGI and Mod

Each launcher is composed by a C file (compiled to an executable) and a Lua file. This Lua file should live on the very same directory of the executable or could be pre-compiled and included inside the corresponding C file. The following table shows where these files should be installed.

Lua Apache Module offers a directive LuaMain which should be used to indicate where the file is installed.

Apache module configuration

Lua Apache module has some configuration directives that must be used:

• LuaHandler handler
  Registers a handler to be processed by the module. This should be used in conjunction with AddHandler directive or <Files> construction (both associate a name with a file type). Only the file types specified by the handler defined with LuaHandler will be processed by the module.
• LuaMain path
  Indicates where the launcher's Lua file is intalled.

ISAPI

• Copy cgilua_isapi.dll and all dependent libraries to IIS working directory.
  This directory is usually "$(WINDOWS)\system32\inetsrv\".

• Configure ".lua" and ".lp" to execute cgilua_isapi.dll.
  In order to configure this in IIS go to the Web Site property page, Home Directory, Configuration.
  In the Mappings tab add each extension pointing to cgilua_isapi.dll.

• Edit the provided isapi.reg file to point to the installation directory of CGILua.
  Run isapi.reg, this will create a key in the registry at the location "HKLM\Software\CGILua\5.0\MainScriptPath", pointing to isapi.lua.

• Restart IIS and try to run a lua or lp file.

• Install LuaJava JNI library in a path included by the java system variable "java.library.path" (Usually the most suitable paths are "$(JAVA_HOME)/jre/bin" and "$(CATALINA_HOME)/bin").
• Make sure Tomcat if configured to use the specified JRE.
• Install LuaJava, Log4J and cgilua jar files in "$(CATALINA_HOME)/common/lib"
• Create a simple Tomcat application with a ".lua" file and "run" it.

  <servlet>
    <servlet-name>cgilua</servlet-name>
    <servlet-class>org.keplerproject.cgilua.servlet.CGILuaServlet</servlet-class>
    
    <!-- Full path of CGILua servlet lua launcher -->
    <init-param>
      <param-name>cgilua.launcherpath</param-name>
      <param-value>C:/Program Files/CGILua/servlet.lua</param-value>
    </init-param>
    
    <!-- CGILua installation dir -->
    <init-param>
      <param-name>cgilua.basedir</param-name>
      <param-value>C:/Program Files/CGILua</param-value>
    </init-param>

    <!-- Number of LuaState's created for the pool to handle requests. -->
    <init-param>
      <param-name>cgilua.poolsize</param-name>
      <param-value>30</param-value>
    </init-param>
  </servlet>

  <!-- CGILua files extension mappings -->
  <servlet-mapping>
    <servlet-name>cgilua</servlet-name>
    <url-pattern>*.lua</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
    <servlet-name>cgilua</servlet-name>
    <url-pattern>*.lp</url-pattern>
  </servlet-mapping>

CGILua installation

Every launcher loads CGILua's library and executes the function which processes the request. This function loads some internal libraries, prepares the environment for the script and runs it.

CGILua contains a set of internal libraries and offers some libraries to the user's script.

To provide protection over the whole environment, CGILua redefines the function require in order to maintain the original values for package.path and package.cpath variables. Furthermore, the function loadlib is allowed only for scripts loaded by require (in fact, this function will be less important when Lua 5.1 comes around).

Configuration

CGILua 5.0 offers a single configuration file, called config.lua and a set of functions to alter the default configuration.

CGILua configuration

CGILua system configuration is placed at config.lua. Some of the configuration parameters are listed below:

• script handlers, by calling cgilua.addscripthandler (when using Apache module's launcher, these handlers must conform to the Apache configuration);
• POST data sizes, by calling cgilua.setmaxinput and cgilua.setmaxfilesize;
• opening and closing functions, by calling cgilua.addopenfunction and cgilua.addclosefunction. This functions are executed just before and after the script execution, even if an error occurs.

Error Handling

There are three functions to handle errors in CGILua:

The function cgilua.seterrorhandler defines the error handler, a function called by Lua when an error has just occurred. The error handler has access to the execution stack before the error is thrown and so it can build an error message using stack information. Lua also provides a function to do that: debug.traceback.

The function cgilua.seterroroutput defines the function that decides what to do with the message. It could be sent to the client's browser or written to the log file or sent to an e-mail address (with the help of LuaSocket, for example).

The function cgilua.errorlog is provided to write directly to the http server error log file.