Server-Side IntegrationNGINX - LUA Module

Installing the Enforcer

Installing on Ubuntu

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

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

    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