Step‑by‑Step Guide to Install Nginx with Lua and Deploy a Lua‑Based WAF

Introduction

The article describes how to build a Web Application Firewall (WAF) using Nginx combined with Lua, commonly referred to as a Lua‑based WAF. It provides two installation approaches: compiling Nginx with Lua modules manually, and using the OpenResty bundle.

Method 1 – Install Nginx and Integrate Lua Modules

1. Install LuaJIT

LuaJIT is a Just‑In‑Time compiler for Lua. Clone the source from GitHub and install it:

git clone https://github.com/openresty/luajit2.git
cd luajit2
make PREFIX=/usr/local/luajit
make install PREFIX=/usr/local/luajit

Add the following environment variables to /etc/profile and reload:

export LUAJIT_LIB=/usr/local/luajit/lib
export LUAJIT_INC=/usr/local/luajit/include/luajit-2.1

source /etc/profile

2. Install ngx_devel_kit (NDK)

Download and extract the desired version:

cd /mnt
wget https://github.com/vision5/ngx_devel_kit/archive/v0.3.1.tar.gz
tar -xzvf v0.3.1.tar.gz

3. Install the latest lua‑nginx‑module

Download and extract the stable release:

cd /mnt
wget https://github.com/openresty/lua-nginx-module/archive/v0.10.15.tar.gz
tar -xzvf v0.10.15.tar.gz

4. Compile Nginx with Lua support

Configure Nginx with required modules and the previously built Lua modules:

cd /mnt/nginx-1.18.0
./configure \
  --prefix=/etc/nginx \
  --sbin-path=/usr/sbin/nginx \
  --modules-path=/usr/lib64/nginx/modules \
  --conf-path=/etc/nginx/nginx.conf \
  --error-log-path=/var/log/nginx/error.log \
  --http-log-path=/var/log/nginx/access.log \
  --pid-path=/var/run/nginx.pid \
  --lock-path=/var/run/nginx.lock \
  --user=nginx \
  --group=nginx \
  --with-http_gzip_static_module \
  --with-http_realip_module \
  --with-http_ssl_module \
  --with-openssl=/mnt/openssl-1.1.1g \
  --with-zlib=/mnt/zlib-1.2.11 \
  --with-pcre=/mnt/pcre-8.44 \
  --add-module=/mnt/lua-nginx-module-0.10.15 \
  --add-module=/mnt/ngx_devel_kit-0.3.1
make
make install

Note: OpenSSL, PCRE, and Zlib source packages must be downloaded and extracted to /mnt before configuring.

5. Resolve libluajit loading error

If Nginx fails with

error while loading shared libraries: libluajit-5.1.so.2: cannot open shared object file

, add the LuaJIT library path to the dynamic linker configuration:

echo "/usr/local/luajit/lib/" >> /etc/ld.so.conf
ldconfig

6. Test Lua execution

Add a simple Lua handler in an Nginx location block: content_by_lua 'ngx.say("hello, lua")'; After reloading Nginx, accessing the location should display “hello, lua”.

Method 2 – Install OpenResty Directly

OpenResty bundles Nginx, LuaJIT, and many useful modules. To install:

cd /opt
tar -xzvf openresty-1.15.8.3.tar.gz
cd openresty-1.15.8.3
./configure \
  --prefix=/opt/openresty \
  --with-pcre=/opt/pcre-8.44 \
  --with-zlib=/opt/zlib-1.2.11 \
  --with-openssl=/opt/openssl-1.1.1g \
  --with-poll_module \
  --with-http_v2_module \
  --with-http_realip_module \
  --with-http_addition_module \
  --with-stream \
  --with-stream_ssl_module \
  --with-stream_ssl_preread_module \
  --with-http_ssl_module
make
make install

After installation, the same Lua test used in Method 1 can be applied.

Installing the ngx_lua_waf Module

Clone the WAF repository and add its path to the OpenResty configuration:

cd /opt/openresty/lualib
git clone https://github.com/loveshell/ngx_lua_waf.git waf

lua_package_path "/opt/openresty/lualib/waf/?.lua";
lua_shared_dict limit 10m;
init_by_lua_file /opt/openresty/lualib/waf/init.lua;
access_by_lua_file /opt/openresty/lualib/waf/waf.lua;

The directory layout of the WAF is:

waf
├── config.lua
├── init.lua
├── wafconf
│   ├── args
│   ├── cookie
│   ├── post
│   ├── url
│   ├── user-agent
│   └── whiteurl
└── waf.lua

config.lua

defines the protection rules, such as URL denial, cookie matching, POST data inspection, IP whitelist/blacklist, CC‑attack rate limiting, and custom block pages.

Testing the WAF

Send a request that matches a rule, for example:

curl http://www.example.com/test.php?id=../etc/passwd

If the request is blocked, the WAF logs an entry similar to:

192.168.0.101 [2020-06-20 01:44:01] "GET localhost/index.php?id=/../../../etc/passwd" "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36" "../"

Successful installation is confirmed when the block page appears.