Comprehensive Guide: Compiling lua-nginx-module with NGINX 1.26.2 Cloudpanel. Ubuntu 24.04

Web Technologies & Applications
, , ,
1

Comprehensive Guide: Compiling lua-nginx-module with NGINX 1.26.2

:warning: CRITICAL ENVIRONMENT NOTICE

Execution Environment Requirements

WARNING: This operation must be executed exclusively in a non-production environment.

Risk Assessment:

  • Data loss or corruption may be irreversible if executed in production
  • System state recovery may not be possible
  • No rollback mechanisms are guaranteed

Required Environment:

  • Development instance
  • Staging environment
  • Secondary/backup system
  • Test environment with equivalent configuration

Prerequisites:

  • Full system backup
  • Verified restore capabilities
  • Isolated network segment
  • Non-production datasets

DO NOT PROCEED with execution in any production environment under any circumstances.

This guide provides step-by-step instructions for compiling and installing lua-nginx-module with NGINX 1.26.2 on a Debian/Ubuntu system.

Prerequisites

First, switch to root user and install the required dependencies:

sudo su

# Install ModSecurity dependencies
apt install libmodsecurity3 libmodsecurity-dev

# Install PCRE dependencies
apt-get install libpcre3 libpcre3-dev

# Install additional required dependencies
apt-get install libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev

SSH Configuration (Optional)

If you need to modify SSH settings:

nano /etc/ssh/sshd_config
service ssh restart
passwd  # Set root password if needed

Download and Extract Required Components

Navigate to your desired directory (e.g., /root) and download/extract the necessary components:

# Download and extract NGINX
wget https://nginx.org/download/nginx-1.26.2.tar.gz
tar -xzvf nginx-1.26.2.tar.gz

# Clone LuaJIT repository
git clone https://luajit.org/git/luajit.git

# Download and extract NGX Devel Kit
wget https://github.com/vision5/ngx_devel_kit/archive/refs/tags/v0.3.3.tar.gz
tar -xzf v0.3.3.tar.gz

# Clone Lua Resty components
git clone https://github.com/openresty/lua-resty-core.git
git clone https://github.com/openresty/lua-resty-lrucache.git

# Download and extract lua-nginx-module
wget https://github.com/openresty/lua-nginx-module/archive/refs/tags/v0.10.27.tar.gz
tar -xzf v0.10.27.tar.gz

Compile and Install LuaJIT

cd /root/luajit/
make && sudo make install

Configure and Install NGINX with Lua Module

cd /root/nginx-1.26.2

# Set LuaJIT environment variables
export LUAJIT_LIB=/usr/local/lib
export LUAJIT_INC=/usr/local/include/luajit-2.1

# Configure NGINX with required modules and paths
./configure \
    --with-ld-opt="-Wl,-rpath,/usr/local/include/luajit-2.1" \
    --prefix=/usr/share/nginx \
    --conf-path=/etc/nginx/nginx.conf \
    --http-log-path=/var/log/nginx/access.log \
    --error-log-path=/var/log/nginx/error.log \
    --lock-path=/var/lock/nginx.lock \
    --pid-path=/run/nginx.pid \
    --modules-path=/usr/lib/nginx/modules \
    --http-client-body-temp-path=/var/lib/nginx/body \
    --http-fastcgi-temp-path=/var/lib/nginx/fastcgi \
    --http-proxy-temp-path=/var/lib/nginx/proxy \
    --http-scgi-temp-path=/var/lib/nginx/scgi \
    --http-uwsgi-temp-path=/var/lib/nginx/uwsgi \
    --with-pcre-jit \
    --with-compat \
    --with-ld-opt='-lpcre' \
    --add-dynamic-module=/root/ngx_devel_kit-0.3.3 \
    --add-dynamic-module=/root/lua-nginx-module-0.10.27

# Install NGINX
make install

Install Lua Resty Components

# Install lua-resty-core
cd /root/lua-resty-core
make install PREFIX=/etc/nginx

# Install lua-resty-lrucache
cd /root/lua-resty-lrucache
make install PREFIX=/etc/nginx

Configure NGINX Modules

Create module configuration files:

# Create NDK module configuration
echo "load_module modules/ndk_http_module.so;" > /usr/share/nginx/modules-available/mod-ndk-http-module.conf

# Create Lua module configuration
echo "load_module modules/ngx_http_lua_module.so;" > /usr/share/nginx/modules-available/mod-ngx-lua-module.conf

Create symbolic links in modules-enabled directory:

cd /etc/nginx/modules-enabled

ln -s /usr/share/nginx/modules-available/mod-ndk-http-module.conf 50-mod-ndk-http-module.conf
ln -s /usr/share/nginx/modules-available/mod-ngx-lua-module.conf 50-mod-ngx-lua-module.conf

Configure NGINX

Add the following line to your nginx.conf file to set the Lua package path:

lua_package_path "/etc/nginx/lib/lua/?.lua;;";

Post-Installation Verification

  1. Verify NGINX configuration:
nginx -t
  1. Check if Lua module is loaded:
nginx -V 2>&1 | grep lua
  1. Restart NGINX:
systemctl restart nginx

Common Issues and Troubleshooting

  1. If you encounter “module not found” errors, verify that the symbolic links are correctly created in the modules-enabled directory.

  2. If you see LuaJIT-related errors, ensure that the environment variables (LUAJIT_LIB and LUAJIT_INC) are correctly set.

  3. For permission issues, ensure that the nginx user has appropriate access to the Lua modules directory.

Directory Structure

After installation, verify these important directories:

  • NGINX configuration: /etc/nginx/
  • NGINX modules: /usr/lib/nginx/modules/
  • Lua modules: /etc/nginx/lib/lua/

Security Considerations

  1. Ensure proper file permissions on Lua scripts and modules
  2. Regularly update all components to their latest stable versions
  3. Implement appropriate access controls for Lua scripts
  4. Monitor error logs for any security-related issues

Remember to always back up your configuration files before making any changes and test in a staging environment first.