Installing dynamic Wallarm module for NGINX Plus¶

These instructions describe the steps to install Wallarm filtering node as a dynamic module for the official commercial version of NGINX Plus.

apt list wallarm-node

apt list wallarm-node

yum list wallarm-node

# run from the server with installed Wallarm filtering node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool

# run from the server with installed Wallarm filtering node
apt list wallarm-node-nginx
# run from the server with installed postanalytics
apt list wallarm-node-tarantool

# run from the server with installed Wallarm filtering node
yum list wallarm-node-nginx
# run from the server with installed postanalytics
yum list wallarm-node-tarantool

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

• SELinux disabled or configured upon the instructions

• Executing all commands as a superuser (e.g. root)

• For the request processing and postanalytics on different servers: postanalytics installed on the separate server 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 the instruction, vim is used

Installation options¶

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

• Primary processing in the NGINX-Wallarm module. The processing is not memory demanding and can be put on frontend servers without changing the server requirements.

• Statistical analysis of the processed requests in the postanalytics module. Postanalytics is memory demanding, which may require changes in the server configuration or installation of postanalytics on a separate server.

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

Installation commands for both options are described in the further instructions.

Installation¶

1. Install NGINX Plus and dependencies¶

Install NGINX Plus and its dependencies using these official NGINX instructions.

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 buster/3.2/' | 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.2/' | 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.2/' | 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.2/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.2/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.2/x86_64/Packages/wallarm-node-repo-1-6.el8.noarch.rpm

3. Install Wallarm API Security packages¶

Request processing and postanalytics on the same server¶

To run postanalytics and process the requests on the same server, the following packages are required:

• nginx-plus-module-wallarm for the NGINX Plus-Wallarm module

• wallarm-node for the postanalytics module, Tarantool database, and additional NGINX Plus-Wallarm packages

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

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

sudo yum install wallarm-node nginx-plus-module-wallarm

Request processing and postanalytics on different servers¶

To run postanalytics and process the requests on different servers, the following packages are required:

• wallarm-node-nginx and nginx-plus-module-wallarm for the NGINX Plus-Wallarm module

  Debian

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

  Ubuntu

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

  CentOS or Amazon Linux 2

  sudo yum install wallarm-node-nginx nginx-plus-module-wallarm
  

• wallarm-node-tarantool on the separate server for the postanalytics module and Tarantool database (installation steps are described in the instructions)

4. Connect the Wallarm API Security module¶

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

   sudo vim /etc/nginx/nginx.conf
   

2. 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;
   

3. Copy the configuration files for the system setup:

   sudo cp /usr/share/doc/nginx-plus-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.

   

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

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.

   The specified name can be changed in Wallarm Console → Nodes later.

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. Update Wallarm node configuration¶

Main configuration files of NGINX and Wallarm filtering node are located in the directories:

• /etc/nginx/conf.d/default.conf with NGINX settings

• /etc/nginx/conf.d/wallarm.conf with global filtering node settings

  The file is used for settings applied to all domains. To apply different settings to different domain groups, use the file default.conf or create new configuration files for each domain group (for example, example.com.conf and test.com.conf). More detailed information about NGINX configuration files is available in the official NGINX documentation.

• /etc/nginx/conf.d/wallarm-status.conf with Wallarm node monitoring settings. Detailed description is available within the link

• /etc/default/wallarm-tarantool or /etc/sysconfig/wallarm-tarantool with the Tarantool database settings

Request filtration mode¶

By default, the filtering node is in the status off and does not analyze incoming requests. To enable requests analysis, please follow the steps:

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

   sudo vim /etc/nginx/conf.d/default.conf
   

2. Add the line wallarm_mode monitoring; to the https, server or location block:

server {
    # port for which requests are filtered
    listen       80;
    # domain for which requests are filtered
    server_name  localhost;
    # Filtering node mode
    wallarm_mode monitoring;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

When operating in the monitoring mode, the filtering node searches attack signs in requests but does not block detected attacks. We recommend keeping the traffic flowing via the filtering node in the monitoring mode for several days after the filtering node deployment and only then enable the block mode. Learn recommendations on the filtering node operation mode setup →

Memory¶

The Wallarm node uses the in-memory storage Tarantool. For production environments, the recommended amount of RAM allocated for Tarantool is 75% of the total server memory. If testing the Wallarm node or having a small instance size, the lower amount can be enough (e.g. 25% of the total memory).

To allocate memory for Tarantool:

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

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:

   If testing the node

   SLAB_ALLOC_ARENA=0.5
   

   If deploying the node to the production environment

   SLAB_ALLOC_ARENA=24
   

   Detailed recommendations about allocating memory for Tarantool are described in these instructions.

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

Address of the separate postanalytics server¶

Add postanalytics server addresses to the file /etc/nginx/conf.d/wallarm.conf:

upstream wallarm_tarantool {
    server <ip1>:3313 max_fails=0 fail_timeout=0 max_conns=1;
    server <ip2>:3313 max_fails=0 fail_timeout=0 max_conns=1;

    keepalive 2;
    }

    # omitted

wallarm_tarantool_upstream wallarm_tarantool;

• max_conns value must be specified for each of the upstream Tarantool servers to prevent the creation of excessive connections.

• keepalive value must not be lower than the number of the Tarantool servers.

Other configurations¶

To update other NGINX and Wallarm node configurations, use the NGINX documentation and the list of available Wallarm node directives.

7. Restart NGINX Plus¶

usermod -aG wallarm <user_name>;

sudo systemctl restart nginx

sudo service nginx restart

sudo systemctl restart nginx

8. Test Wallarm node operation¶

1. Send the request with test SQLI and XSS attacks to the application address:

   curl http://localhost/?id='or+1=1--a-<script>prompt(1)</script>'
   

2. Open the Wallarm Console → Events section in the EU Cloud or US Cloud and ensure attacks are displayed in the list.
   

   

Settings customization¶

Dynamic Wallarm API Security module with default settings is installed for NGINX Plus. To customize Wallarm node settings, use the available directives.

Common customization options:

• Configuration of the filtration mode

• Logging Wallarm node variables

• Using the balancer of the proxy server behind the filtering node

• Limiting the single request processing time in the directive wallarm_process_time_limit

• Limiting the server reply waiting time in the NGINX directive proxy_read_timeout

• Limiting the maximum request size in the NGINX directive client_max_body_size

• Double‑detection of attacks with libdetection