Product guides

Installing the Enforcer

Suggest Edits

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)

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

2. Make sure Nettle is removed

```sh
sudo yum -y remove nettle
```

3. Install the development tools

```sh
sudo yum groupinstall -y "Development Tools"
```

4. Compile and install Nettle

```sh
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

```sh
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

```sh
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

Updated 12 days ago