Installing as a Dynamic Module for NGINX Stable¶

These instructions describe the steps to install Wallarm filtering node as a dynamic module for the open source version of NGINX stable that was installed from the NGINX repository. The node will perform traffic analysis in-line.

Use cases¶

Among all supported Wallarm deployment options, DEB/RPM packages for NGINX Stable is recommended for Wallarm deployment in these use cases:

• Your infrastructure is based on bare metal or virtual machines without using container-based methods. Typically, these setups are managed with Infrastructure as Code (IaC) tools like Ansible or SaltStack.

• Your services are built around NGINX Stable. Wallarm can extend its functionalities using these packages.

Requirements¶

• Access to the account with the Administrator role and two‑factor authentication disabled in Wallarm Console for the US Cloud or EU Cloud

• SELinux disabled or configured upon the instructions

• NGINX version 1.24.0

  Custom NGINX versions

  If you have a different version, refer to the instructions on how to connect the Wallarm module to custom build of NGINX

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

• Access to https://repo.wallarm.com to download packages. Ensure the access is not blocked by a firewall

• Access to https://us1.api.wallarm.com for working with US Wallarm Cloud or to https://api.wallarm.com for working with EU Wallarm Cloud. If access can be configured only via the proxy server, then use the instructions

• Access to the IP addresses of Google Cloud Storage listed within the link. When you allowlist, denylist, or graylist entire countries, regions, or data centers instead of individual IP addresses, the Wallarm node retrieves precise IP addresses related to the entries in the IP lists from the aggregated database hosted on Google Storage

• Installed text editor vim, nano, or any other. In the instruction, vim is used

1. Install NGINX stable and dependencies¶

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

• Installation from the built package

  DebianUbuntuCentOS or Amazon Linux 2.0.2021x and lower

  sudo apt -y install curl gnupg2 ca-certificates lsb-release debian-archive-keyring
  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 gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/nginx.gpg --import
  sudo chmod 644 /etc/apt/trusted.gpg.d/nginx.gpg
  sudo apt update
  sudo apt -y install nginx
  

  1. Install the dependencies required for NGINX stable:

     sudo apt -y install curl gnupg2 ca-certificates lsb-release
     

  2. Install NGINX stable:

     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 -y install nginx
     

  1. If an EPEL repository is added in CentOS 7.x, please disable installation of NGINX stable from this repository by adding exclude=nginx* to the file /etc/yum.repos.d/epel.repo.

     Example of the changed file /etc/yum.repos.d/epel.repo:

     [epel]
     name=Extra Packages for Enterprise Linux 7 - $basearch
     #baseurl=http://download.fedoraproject.org/pub/epel/7/$basearch
     metalink=https://mirrors.fedoraproject.org/metalink?repo=epel-7&arch=$basearch
     failovermethod=priority
     enabled=1
     gpgcheck=1
     gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-7
     exclude=nginx*
     
     [epel-debuginfo]
     name=Extra Packages for Enterprise Linux 7 - $basearch - Debug
     #baseurl=http://download.fedoraproject.org/pub/epel/7/$basearch/debug
     metalink=https://mirrors.fedoraproject.org/metalink?repo=epel-debug-7&arch=$basearch
     failovermethod=priority
     enabled=0
     gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-7
     gpgcheck=1
     
     [epel-source]
     name=Extra Packages for Enterprise Linux 7 - $basearch - Source
     #baseurl=http://download.fedoraproject.org/pub/epel/7/SRPMS
     metalink=https://mirrors.fedoraproject.org/metalink?repo=epel-source-7&arch=$basearch
     failovermethod=priority
     enabled=0
     gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-EPEL-7
     gpgcheck=1
     

  2. Install NGINX stable from the official repository:

     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 -y nginx
     

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

  NGINX for AlmaLinux, Rocky Linux or Oracle Linux 8.x

  This is the only option to install NGINX on AlmaLinux, Rocky Linux or Oracle Linux 8.x.

More detailed information about the NGINX 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 -y install dirmngr
curl -fSsL https://repo.wallarm.com/wallarm.gpg | sudo gpg --no-default-keyring --keyring gnupg-ring:/etc/apt/trusted.gpg.d/wallarm.gpg --import
sudo chmod 644 /etc/apt/trusted.gpg.d/wallarm.gpg
sh -c "echo 'deb https://repo.wallarm.com/debian/wallarm-node bullseye/4.6/' | 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 https://repo.wallarm.com/ubuntu/wallarm-node bionic/4.6/' | 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 https://repo.wallarm.com/ubuntu/wallarm-node focal/4.6/' | 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 https://repo.wallarm.com/ubuntu/wallarm-node jammy/4.6/' | 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/4.6/x86_64/wallarm-node-repo-4.6-0.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/4.6/x86_64/wallarm-node-repo-4.6-0.el7.noarch.rpm

sudo yum install -y epel-release
sudo rpm -i https://repo.wallarm.com/centos/wallarm-node/8/4.6/x86_64/wallarm-node-repo-4.6-0.el8.noarch.rpm

3. Install Wallarm packages¶

The following packages are required:

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

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

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

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

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

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

4. Connect the Wallarm 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 filtering node interacts with the Wallarm Cloud. You need to connect the node to the Cloud.

When connecting node to the Cloud, you can set the node name, under which it will be displayed in the Wallarm Console UI and put the node into the appropriate node group (used to logically organize nodes in UI).

To connect the node to the Cloud, use a Wallarm token of the appropriate type:

• You may add -n <HOST_NAME> parameter to set a custom name for your node instance. Final instance name will be: HOST_NAME_NodeUUID.

6. Enable Wallarm to analyze the traffic¶

By default, the deployed Wallarm node does not analyze incoming traffic. To start analysis, configure Wallarm to proxy traffic via the /etc/nginx/conf.d/default.conf file on the machine with the installed node:

1. Set an IP address for Wallarm to proxy legitimate traffic to. It can be an IP of an application instance, load balancer, or DNS name, etc., depending on your architecture.

   To do so, edit the proxy_pass value, e.g. Wallarm should send legitimate requests to http://10.80.0.5:

   server {
       listen 80;
       listen [::]:80 ipv6only=on;
   
       ...
   
       location / {
           proxy_pass http://10.80.0.5; 
           ...
       }
   }
   

2. For the Wallarm node to analyze the incoming traffic, set the wallarm_mode directive to monitoring:

   server {
       listen 80;
       listen [::]:80 ipv6only=on;
       wallarm_mode monitoring;
   
       ...
   }
   

   The monitoring mode is the recommended one for the first deployment and solution testing. Wallarm provides safe blocking and blocking modes as well, read more.

7. Restart NGINX¶

usermod -aG wallarm <user_name>;

sudo systemctl restart nginx

sudo service nginx restart

sudo systemctl restart nginx

sudo systemctl restart nginx

8. Configure sending traffic to the Wallarm instance¶

Update targets of your load balancer to send traffic to the Wallarm instance. For details, please refer to the documentation on your load balancer.

9. Test Wallarm node operation¶

1. Send the request with test Path Traversal attack to a protected resource address:

   curl http://localhost/etc/passwd
   

2. Open Wallarm Console → Events section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.
   

10. Fine-tune the deployed solution¶

The dynamic Wallarm module with default settings is installed for NGINX stable. The filtering node may require some additional configuration after deployment.

Wallarm settings are defined using the NGINX directives or the Wallarm Console UI. Directives should be set in the following files on the machine with the Wallarm node:

• /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

Below there are a few of the typical settings that you can apply if needed:

• Configuration of the filtration mode

• Allocating resources for Wallarm nodes

• 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

• Configuring dynamic DNS resolution in NGINX