Lua and operating system dependencies

Lua and operating systems and CPU architectures

When writing Lua scripts, external libraries are often required to provide additional functionality. Only a small number of Lua libraries are implemented purely in the Lua language itself; a common example is lua-cjson. Most widely used libraries expose a Lua-level API while internally relying on native code to access operating system or system-level functionality. Typical examples are lua-curl for HTTP and network interactions and lua-socket for low-level networking features.

Because many Lua libraries rely on native code, they must be built specifically for the target operating system and CPU architecture of the runtime environment in which Airlock IAM runs. This limits the ability to bundle a fixed set of Lua libraries with the product and adds operational complexity. In addition, building compatible library versions may require a target-specific build environment, which is not always available on a developer’s local system.

Lua, Lua libraries and versioning

The correct execution of Lua scripts depends on the versions of several artefacts involved in the runtime environment:

  • -Lua interpreter version: The embedded Lua interpreter defines the supported Lua language version and ABI. Lua libraries must be built for this exact Lua version to be loadable and executable.
  • -Operating system library versions: The runtime environment determines which versions of system libraries are available. These versions directly affect which native Lua libraries can be used.
  • -Lua library versions: Native Lua libraries are built against specific versions of both the Lua runtime and the underlying system libraries. Only matching combinations are supported.

Using Lua library bundles in Airlock IAM

Lua can be extended with libraries by placing the necessary files in the correct folder of the instance directory. The following table explains the types of libraries and the expected directory locations:

Library type

File extension

Directory

Libraries written in Lua itself and provided as source code.

.lua

instances/common/scripting/lua/share

or

instances/<instance>/scripting/lua/share

Libraries written in C/C++ and provided as shared object libraries.

.so

instances/common/scripting/lua/lib

or

instances/<instance>/scripting/lua/lib

Once a library is placed in the directory structure outlined above, it can be used in scripts with the require function of Lua.

When adding additional libraries, you must ensure that the libraries are compatible with the installed version of Lua. See the Lua compatibility matrix here: Scriptable plugins.

Building libraries with Luarocks

The package manager for Lua is Luarocks. The package manager must be installed on a system running the same operating system as the target architecture of Airlock IAM. This is necessary to ensure that shared object libraries will work correctly on the IAM target operating system.

When installed and configured, additional packages can be built and installed locally using the following command:

 
Example
./luarocks install --tree <install_path> <lib_name> <lib_version>

Parameter

Description

Example

<install_path>

The directory where Luarocks should place the library files.

Luarocks knows the different library bundles types and will automatically add the share or lib path segments.

Luarocks will also add directory levels to manage different Lua versions in parallel.

instances/common/scripting/lua

<lib_name>

The name of the library.

lua-curl

<lib_version>

The version of the library.

0.3.13-1

Advanced Trouble Shooting

It may be that you are running an operating system or CPU architecture that is incompatible with the version of lua distributed with Airlock IAM.

 
Risk

Use the instructions provided here at your own risk.

Keep in mind, that with every update and bugfix release of Airlock IAM you have to again replace the lua binary.

To determine, if you are affected by this type of problem, run the following command on the Airlock IAM host:

  • -$IAM_HOME/res/scripting/lua

If the output looks like this, the CPU architecture does not match (example from MacOS on an ARM architecture):

  • -zsh: exec format error: ./lua

If the output looks like this, the system libraries installed with the operating system are not compatible with the lua executable (example from an older version of Red Hat Linux):

  • -./res/scripting/lua/lua: /lib64/libm.so.6: version `GLIBC_2.29' not found (required by ./res/scripting/lua/lua)

To solve this problem, you have to replace the lua executable, luarocks, lua-cjson and luasocket by following these instructions:

  1. Login to a system that uses the same CPU architecture and operating system architecture as the host running Airlock IAM.
  2. Use the following versions when working with lua. These are the versions bundled with Airlock IAM:
    LUA_8.6.0=“5.4.8”
    LUA_CJSON_8.6.0=“2.1.0.10-1”
    LUA_SOCKET_8.6.0=“3.1.0-1”
  3. Ensure the following libraries are installed on this system: cpp gcc glibc-devel glibc-headers
  4. cd to a working directory that is both writeable and empty.
  5. Download the lua source code from the web site and unpack it.
    LUA_8.6.0="5.4.8"
    curl -f -R -O “https://www.lua.org/ftp/lua-${LUA_8.6.0}.tar.gz”
    tar -zxf “lua-${LUA_8.6.0}.tar.gz”
  6. Build the lua executable with:
         cd “lua-${LUA_8.6.0}”
    make
    make local
  7. Copy the lua executable to the Airlock IAM installation folder
    cp ./install/bin/lua $IAM_INSTALL/res/scripting/lua/lua
    Note: this replaces the existing file with the newly compiled version.
  8. Download LuaRocks:
    cd ..
    LUAROCKS_8.6.0=“3.9.2”
    curl -f -R -O “https://luarocks.github.io/luarocks/releases/luarocks-${LUAROCKS_8.6.0}.tar.gz”
    tar -zxf “luarocks-${LUAROCKS_8.6.0}.tar.gz”
    Note: newer version of LunaRocks have changed the way libraries are stored in the filesystem. If you use a newer version, you have to make sure yourself that IAM can find the libraries.
  9. Build LuaRocks
    cd “luarocks-${LUAROCKS_8.6.0}”
    ./configure --with-lua=“../lua-${LUA_8.6.0}/install/”
    make
    Note: --with-lua must refer to the install folder of lua. In the folder luarocks-${LUAROCKS_8.6.0} you will find the luarocks executable.
  10. Build the libraries
    ./luarocks install --tree “$IAM_CONFIG_ROOT/instances/common/scripting/lua” --no-manifest --no-doc “lua-cjson” “${LUA_CJSON_8.6.0}”
    ./luarocks install --tree “$IAM_CONFIG_ROOT/instances/common/scripting/lua” --no-manifest --no-doc “luasocket” “${LUA_SOCKET_8.6.0}”
    Note: this builds the libraries in luarocks-${LUAROCKS_8.6.0} in the lib and share folders of the chosen IAM instance.
  11. Other libraries can be built in the same manner, should your installation require them.