Installing the Enforcer | HUMAN Documentation

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)

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

2. Make sure Nettle is removed

sudo yum -y remove nettle

3. Install the development tools

sudo yum groupinstall -y "Development Tools"

4. Compile and install Nettle

mkdir /tmp
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
sudo make install

5. Install Luarocks and the HUMAN Lua enforcer dependencies

sudo yum install -y luarocks lua-devel
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

6. Install the HUMAN enforcer

sudo 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