Enforcer frameworksNGINX - LUA Module

Installing the Enforcer

Installing on Ubuntu

Ubuntu 22.04 and Higher

Once NGINX and the Lua module (OpenResty) are installed and configured, use the following commands to install the HUMAN NGINX enforcer and its dependencies (all commands must be be executed as root or with sudo privileges):

$sudo apt-get update && apt-get -qq -y install \
>    build-essential \
>    ca-certificates \
>    curl \
>    wget luarocks
$
$sudo luarocks install lustache
$sudo luarocks install luasocket
$sudo luarocks install lua-resty-http
$sudo luarocks install lua-resty-nettle
$
$sudo luarocks install perimeterx-nginx-plugin

Ubuntu 16.04 and Higher

1. Update existing dependencies for Ubuntu 16.04 or higher

$sudo apt-get update

2. Add the official NGINX repository to get the latest version of NGINX

$sudo add-apt-repository ppa:nginx/stable

If an add-apt-repository: command not found error is returned, run:

sudo apt-get -y install software-properties-common

3. Update existing dependencies for Ubuntu 16.04 or higher

$sudo apt-get update
$sudo apt-get upgrade

4. Install the dependencies for Ubuntu 16.04 or higher

$sudo apt-get -y install build-essential
$sudo apt-get -y install ca-certificates
$sudo apt-get -y install nginx
$sudo apt-get -y install libnginx-mod-http-lua
$sudo apt-get -y install lua-cjson
$sudo apt-get -y install libnettle6
$sudo apt-get -y install nettle-dev
$sudo apt-get -y install luarocks
$sudo apt-get -y install luajit
$sudo apt-get -y install libluajit-5.1-dev

5. Install the HUMAN NGINX enforcer

$sudo luarocks install perimeterx-nginx-plugin

Installing on CentOS 7

Important Notice

NGINX does not provide an NGINX http lua module for CentOS/RHEL via RPM. This means that you would need to compile the module from source.

1. Update and Install dependencies

$yum -y update
$yum install -y epel-release
$yum update -y
$yum groupinstall -y  "Development Tools"
$yum install -y wget rpmdevtools git luajit luajit-devel openssl-devel zlib-devel pcre-devel gcc gcc-c++ make perl-ExtUtils-Embed lua-json lua-devel  ca-certificates
$yum remove -y nettle luarocks

2. Create a temp directory

$sudo mkdir /tmp/nginx
$cd /tmp/nginx

3. Download required source files

$wget http://luarocks.github.io/luarocks/releases/luarocks-3.5.0.tar.gz
$wget http://nginx.org/download/nginx-1.18.0.tar.gz
$wget -O luajit-2.0.tar.gz https://github.com/LuaJIT/LuaJIT/archive/refs/tags/v2.0.5.tar.gz
$wget -O nginx_devel_kit.tar.gz https://github.com/simpl/ngx_devel_kit/archive/v0.3.1.tar.gz
$wget -O nginx_lua_module.tar.gz https://github.com/openresty/lua-nginx-module/archive/v0.10.15.tar.gz
$wget https://ftp.gnu.org/gnu/nettle/nettle-3.6.tar.gz

4. Unpackage all source files

$tar -xzf luarocks-3.5.0.tar.gz
$tar -xzf nettle-3.6.tar.gz
$tar -xvf luajit-2.0.tar.gz
$tar -xvf nginx-1.18.0.tar.gz
$tar -xvf nginx_devel_kit.tar.gz
$tar -xvf nginx_lua_module.tar.gz

5. Install luarocks

$cd /tmp/nginx/luarocks-3.5.0
$./configure
$make
$make install

6. Install Nettle

$cd /tmp/nginx/nettle-3.6
$./configure --prefix=/usr --disable-static
$make
$make check
$make install

7. Install LuaJIT

cd /tmp/nginx/LuaJIT-2.0.5
make install

8. Build and Install NGINX with required modules

$cd /tmp/nginx/nginx-1.18.0
$LUAJIT_LIB=/usr/local/lib LUAJIT_INC=/usr/local/include/luajit-2.0 \
>./configure \
>--user=nginx                          \
>--group=nginx                         \
>--prefix=/etc/nginx                   \
>--sbin-path=/usr/sbin/nginx           \
>--conf-path=/etc/nginx/nginx.conf     \
>--pid-path=/var/run/nginx.pid         \
>--lock-path=/var/run/nginx.lock       \
>--error-log-path=/var/log/nginx/error.log \
>--http-log-path=/var/log/nginx/access.log \
>--with-http_gzip_static_module        \
>--with-http_stub_status_module        \
>--with-debug                          \
>--with-http_ssl_module                \
>--with-pcre                           \
>--with-http_perl_module               \
>--with-file-aio                       \
>--with-http_realip_module             \
>--add-module=/tmp/nginx/ngx_devel_kit-0.3.1 \
>--add-module=/tmp/nginx/lua-nginx-module-0.10.15
$make install

9. Install HUMAN Nginx enforcer & dependencies

$luarocks install luasec
$luarocks install lustache
$luarocks install lua-resty-core
$luarocks install lua-resty-nettle
$luarocks install luasocket
$luarocks install lua-resty-http
$luarocks install lua-cjson
$luarocks install perimeterx-nginx-plugin

10. Optionally, if you are testing in a new environment you may need to configure the following:

  • Add the user “nginx” ShellShell 
    $sudo useradd --system --home /var/cache/nginx --shell /sbin/nologin --comment "nginx user" --user-group nginx
  • Create a systemd service for NGINX ShellShell 
    $sudo vi /usr/lib/systemd/system/nginx.service
  • Paste the following in the file you have just created: 
    $[Unit]
    $Description=nginx - high performance web server
    $Documentation=https://nginx.org/en/docs/
    $After=network-online.target remote-fs.target nss-lookup.target
    $Wants=network-online.target
    $[Service]
    $Type=forking
    $PIDFile=/var/run/nginx.pid
    $ExecStartPre=/usr/sbin/nginx -t -c /etc/nginx/nginx.conf
    $ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf
    $ExecReload=/bin/kill -s HUP $MAINPID
    $ExecStop=/bin/kill -s TERM $MAINPID
    $[Install]
    $WantedBy=multi-user.target
  • Enable and start the NGINX service ShellShell 
    $sudo systemctl is-enabled nginx.service
    $sudo systemctl start nginx.service
    $sudo systemctl enable nginx.service

Ubuntu 14.04

1. Update existing dependencies for Ubuntu 16.04 or higher

$sudo apt-get update
$sudo apt-get upgrade

2. Add the official NGINX repository to get the latest version of NGINX

$sudo add-apt-repository ppa:nginx/stable

If an add-apt-repository: command not found error is returned, run:

sudo apt-get -y install software-properties-common

3. Install the dependencies for Ubuntu 14.04:

$sudo apt-get -y install build-essential
$sudo apt-get -y install ca-certificates
$sudo apt-get -y install make
$sudo apt-get -y install wget
$sudo apt-get -y install nginx
$sudo apt-get -y install m4
$sudo apt-get -y install libnginx-mod-http-lua
$sudo apt-get -y install lua-cjson

4. Download and install LuaRocks

$wget http://luarocks.github.io/luarocks/releases/luarocks-2.4.4.tar.gz
$tar -xzf luarocks-2.4.4.tar.gz
$cd luarocks-2.4.4
$./configure
$sudo make clean && sudo make build && sudo make install
$cd ~

5. Download and install Nettle

$wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
$tar -xzf nettle-3.3.tar.gz
$cd nettle-3.3
$./configure
$sudo make clean && sudo make install
$cd ~

6. Install the remaining dependencies

$sudo apt-get -y install lua-sec
$sudo luarocks install lua-resty-nettle

7. Install the HUMAN NGINX Plugin

$sudo no_proxy=1 luarocks install perimeterx-nginx-plugin

Installing on CentOS 9

1. Install compat-lua packages, these packages contain Lua 5.1 version, which is compatible with OpenResty (epel repository has to be enabled):

$dnf install -y epel-release
$dnf config-manager --set-enabled crb
$dnf install -y compat-lua compat-lua-devel compat-lua-libs

2. Install Lua packages and PerimeterX Enforcer using “lua 5.1” version:

$luarocks install --lua-version 5.1 lustache
$luarocks install --lua-version 5.1 luasocket
$luarocks install --lua-version 5.1 lua-resty-http
$luarocks install --lua-version 5.1 luacheck
$luarocks install --lua-version 5.1 lua-resty-nettle
$luarocks install --lua-version 5.1 perimeterx-nginx-plugin

Adjust pxconfig.lua configuration file and restart OpenResty.

Installing on NGINX+

RHEL 7.4 and above

If you are already using NGINX+, the following steps cover installing the NGINX+ Lua module and HUMAN NGINX enforcer.

Please Note

The HUMAN NGINX plugin can be installed on NGINX+ up to version R15. There is currently a known bug in R16 which crashes NGINX when calling init_worker_by_lua_block (required by the HUMAN plugin). Until this bug is fixed, HUMAN will not support installations using R16.

1. Install the NGINX+ lua module according to the version of NGINX+ installed. (The example shows R15)

1sudo yum install -y nginx-plus-module-lua-r15

2. Make sure Nettle is removed

1sudo yum -y remove nettle

3. Install the development tools

1sudo yum groupinstall -y "Development Tools"

4. Compile and install Nettle

1mkdir /tmp
2cd /tmp/
3wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
4tar -xzf nettle-3.3.tar.gz
5cd nettle-3.3
6./configure
7make
8sudo make install

5. Install Luarocks and the HUMAN Lua enforcer dependencies

1sudo yum install -y luarocks lua-devel
2sudo luarocks install lua-cjson
3sudo luarocks install lustache
4sudo luarocks install lua-resty-nettle
5sudo luarocks install luasocket
6sudo luarocks install lua-resty-http

6. Install the HUMAN enforcer

1sudo luarocks install perimeterx-nginx-plugin

Amazon Linux, CentOS and RHEL 7.3 and lower

1. Install the Lua modules provided by NGINX

$yum install nginx-plus-module-lua

2. Remove pre-installed Nettle

$sudo yum -y remove nettle

3. Install Nettle

Download and compile nettle using the version appropriate for your environment:

$yum -y install m4 # prerequisite for nettle
$cd /tmp/
$wget https://ftp.gnu.org/gnu/nettle/nettle-3.3.tar.gz
$tar -xzf nettle-3.3.tar.gz
$cd nettle-3.3
$./configure
$make install

4. Install Luarocks and Dependencies

$sudo yum install luarocks
$sudo luarocks install lua-cjson
$sudo luarocks install lustache
$sudo luarocks install lua-resty-nettle
$sudo luarocks install luasocket
$sudo luarocks install lua-resty-http

5. Install HUMAN NGINX enforcer

$sudo luarocks install perimeterx-nginx-plugin

6. Modify Selinux (Consult with your internal System Administrator)

On CentOS 7 and other Linux operating systems you may need to modify or disable Selinux. If you get the following error:

nginx: lua atpanic: Lua VM crashed, reason: runtime code generation failed, restricted kernel?

You will need to make one of the following changes:

  • To disable SELinux: RUN setenforcer 0
  • To enable execmem for httpd_t: RUN setsebool httpd_execmem 1 -P