> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# 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):

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

```shell
sudo apt-get update
```

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

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

```shell
sudo apt-get update
sudo apt-get upgrade
```

#### 4. Install the dependencies for Ubuntu 16.04 or higher

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

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

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

```shell
sudo mkdir /tmp/nginx
cd /tmp/nginx
```

#### 3. Download required source files

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

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

```shell
cd /tmp/nginx/luarocks-3.5.0
./configure
make
make install
```

#### 6. Install Nettle

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

#### 7. Install LuaJIT

```plaintext
cd /tmp/nginx/LuaJIT-2.0.5
make install
```

#### 8. Build and Install NGINX with required modules

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

```shell
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
  ```shell
  sudo useradd --system --home /var/cache/nginx --shell /sbin/nologin --comment "nginx user" --user-group nginx
  ```
* Create a systemd service for NGINX
  ShellShell
  ```shell
  sudo vi /usr/lib/systemd/system/nginx.service
  ```
* Paste the following in the file you have just created:
  ```shell
  [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
  ```shell
  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

```shell
sudo apt-get update
sudo apt-get upgrade
```

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

```shell
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:

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

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

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

```shell
sudo apt-get -y install lua-sec
sudo luarocks install lua-resty-nettle
```

#### 7. Install the HUMAN NGINX Plugin

```shell
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):

```bash
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:

```bash
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](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/lua/)

```shell
yum install nginx-plus-module-lua
```

#### 2. Remove pre-installed Nettle

```shell
sudo yum -y remove nettle
```

#### 3. Install Nettle

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

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

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

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