Installing the filtering node (NGINX)¶

Installation overview¶

The processing of requests in the Wallarm node is divided into two stages:

Primary processing in the NGINX-Wallarm module
Statistical analysis of the processed requests in the postanalytics module

Depending on the system architecture, the NGINX-Wallarm and postanalytics modules can be installed on the same server or on different servers.

These instructions describe the installation of the NGINX-Wallarm and postanalytics modules on the same server. The Wallarm node will be installed as a dynamic module for the open source version of NGINX stable that was installed from the NGINX repository.

The list of all Wallarm node installation forms →

Requirements¶

Access to the account with the Administrator or Deploy role and two‑factor authentication disabled in the Wallarm Console for the EU Cloud or US Cloud
Executing all commands as a superuser (e.g. root)
Supported 64-bit operating system:
- Debian 9.x (stretch)
- Debian 10.x (buster)
- Ubuntu 18.04 LTS (bionic)
- Ubuntu 20.04 LTS (focal)
- CentOS 7.x
- Amazon Linux 2
- CentOS 8.x
SELinux disabled or configured upon the instructions
Access to https://repo.wallarm.com to download packages. Ensure the access is not blocked by a firewall
Access to https://api.wallarm.com:444 for working with EU Wallarm Cloud or to https://us1.api.wallarm.com:444 for working with US Wallarm Cloud. If access can be configured only via the proxy server, then use the instructions
Access to GCP storage addresses to download an actual list of IP addresses registered in whitelisted, blacklisted, or greylisted countries or data centers
Installed text editor vim, nano, or any other. In these instructions, vim is used

Installation¶

1. Install NGINX stable and dependencies¶

These are the following options to install NGINX stable from the NGINX repository:

Installation from the built package

Debian

sudo apt install curl gnupg2 ca-certificates lsb-release
echo "deb http://nginx.org/packages/debian `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo apt-key add -
sudo apt update
sudo apt install nginx

Ubuntu

sudo apt install curl gnupg2 ca-certificates lsb-release
echo "deb http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list
curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo apt-key add -
sudo apt update
sudo apt install nginx

CentOS or Amazon Linux 2

echo -e '\n[nginx-stable] \nname=nginx stable repo \nbaseurl=http://nginx.org/packages/centos/$releasever/$basearch/ \ngpgcheck=1 \nenabled=1 \ngpgkey=https://nginx.org/keys/nginx_signing.key \nmodule_hotfixes=true' | sudo tee /etc/yum.repos.d/nginx.repo
sudo yum install nginx

Compilation of the source code from the stable branch of the NGINX repository and installation with the same options

More detailed information about installation is available in the official NGINX documentation.

2. Add Wallarm repositories¶

Wallarm node is installed and updated from the Wallarm repositories. To add repositories, use the commands for your platform:

Debian 9.x (stretch)

sudo apt install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch/3.0/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update

Debian 10.x (buster)

sudo apt install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node buster/3.0/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update

Ubuntu 18.04 LTS (bionic)

curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/3.0/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update

Ubuntu 20.04 LTS (focal)

curl -fsSL https://repo.wallarm.com/wallarm.gpg | sudo apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node focal/3.0/' | sudo tee /etc/apt/sources.list.d/wallarm.list"
sudo apt update

CentOS 7.x

sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/3.0/x86_64/Packages/wallarm-node-repo-1-6.el7.noarch.rpm

Amazon Linux 2

sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/7/3.0/x86_64/Packages/wallarm-node-repo-1-6.el7.noarch.rpm

CentOS 8.x

sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/8/3.0/x86_64/Packages/wallarm-node-repo-1-6.el8.noarch.rpm

3. Install Wallarm API Security packages¶

Depending on your operating system, run one of the commands:

Debian

sudo apt install --no-install-recommends wallarm-node nginx-module-wallarm

Ubuntu

sudo apt install --no-install-recommends wallarm-node nginx-module-wallarm

CentOS or Amazon Linux 2

sudo yum install wallarm-node nginx-module-wallarm

4. Connect the Wallarm API Security module¶

Open the file /etc/nginx/nginx.conf:
```
sudo vim /etc/nginx/nginx.conf
```
Ensure that the include /etc/nginx/conf.d/* line is added to the file. If there is no such line, add it.

Add the following directive right after the worker_processes directive:

load_module modules/ngx_http_wallarm_module.so;

Configuration example with the added directive:

user  nginx;
worker_processes  auto;
load_module modules/ngx_http_wallarm_module.so;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;

Copy the configuration files for the system setup:

sudo cp /usr/share/doc/nginx-module-wallarm/examples/*.conf /etc/nginx/conf.d/

5. Connect the filtering node to Wallarm Cloud¶

The Wallarm node interacts with the Wallarm Cloud. To connect the filtering node to the Cloud, proceed with the following steps:

Make sure that your Wallarm account has the Administrator or Deploy role enabled and two-factor authentication disabled in the Wallarm Console.

You can check mentioned settings by navigating to the users list in the EU Cloud or US Cloud.

Run the addnode script in a system with the installed Wallarm node:

EU Cloud

sudo /usr/share/wallarm-common/addnode

US Cloud

sudo /usr/share/wallarm-common/addnode -H us1.api.wallarm.com

Input the email and password for your account in the Wallarm Console.
Input the filtering node name or click Enter to use an automatically generated name.
Open the Wallarm Console → Nodes section in the EU Cloud or US Cloud and ensure a new filtering node is added to the list.

6. Allocate resources for the postanalytics module¶

The Wallarm node uses the in-memory storage Tarantool. The recommended memory size for Tarantool is 75% of the total server memory. To allocate memory for Tarantool:

Open the Tarantool configuration file in the editing mode:

Debian

sudo vim /etc/default/wallarm-tarantool

Ubuntu

sudo vim /etc/default/wallarm-tarantool

CentOS or Amazon Linux 2

sudo vim /etc/sysconfig/wallarm-tarantool

Specify memory size in GB in the SLAB_ALLOC_ARENA directive. The value can be an integer or a float (a dot . is a decimal separator). For example, 24 GB:
```
SLAB_ALLOC_ARENA=24
```
Detailed recommendations about allocating memory for Tarantool are described in these instructions.

To apply changes, restart Tarantool:

Debian

sudo systemctl restart wallarm-tarantool

Ubuntu

sudo systemctl restart wallarm-tarantool

CentOS or Amazon Linux 2

sudo systemctl restart wallarm-tarantool

7. Restart NGINX¶

Debian

sudo systemctl restart nginx

Ubuntu

sudo service nginx restart

CentOS or Amazon Linux 2

sudo systemctl restart nginx

Next steps¶

Installation is completed. Now you need to configure the filtering node to filter traffic.

See Configure the proxying and filtering rules →