Skip to content

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

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

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

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

4. Connect the Wallarm API Security module

  1. Open the file /etc/nginx/nginx.conf:

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

  3. 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;
    
  4. 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:

  1. 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.

    User list in Wallarm console

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

    sudo /usr/share/wallarm-common/addnode
    
    sudo /usr/share/wallarm-common/addnode -H us1.api.wallarm.com
    
  3. Input the email and password for your account in the Wallarm Console.

  4. Input the filtering node name or click Enter to use an automatically generated name.

  5. 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:

  1. Open the Tarantool configuration file in the editing mode:

    sudo vim /etc/default/wallarm-tarantool
    
    sudo vim /etc/default/wallarm-tarantool
    
    sudo vim /etc/sysconfig/wallarm-tarantool
    
  2. 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.

  3. To apply changes, restart Tarantool:

    sudo systemctl restart wallarm-tarantool
    
    sudo systemctl restart wallarm-tarantool
    
    sudo systemctl restart wallarm-tarantool
    

7. Restart NGINX

sudo systemctl restart nginx
sudo service nginx restart
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 →