Skip to content

Installing as a Dynamic Module for NGINX

Commercial NGINX Plus and Open Source NGINX

This instruction addresses the filter node installation as a dynamic module for the open‑source stable NGINX.
Wallarm module for NGINX does not work with the mainline version of open‑source NGINX.

If you are running the commercial NGINX Plus, you need a different set of instructions. See Installing with NGINX Plus.

If you have a running NGINX installed in your network infrastructure, you can install Wallarm as a dynamic module for NGINX.

Use with Official vs. Custom Builds of NGINX

Wallarm is compatible with NGINX installed from official NGINX repositories.

If you are planning to install a custom build of NGINX, the dynamic module from the Wallarm repository might be incompatible and not load. To rebuild the dynamic module, contact Wallarm Support.

With your support request, provide the following information provided by the output of the given commands:

  • Linux kernel version: uname -a

  • Linux distributive: cat /etc/*release

  • NGINX version:

  • NGINX official build: /usr/sbin/nginx -V

  • NGINX custom build: <path to nginx>/nginx -V

  • Compatibility signature:

  • NGINX official build: egrep -ao '.,.,.,[01]{33}' /usr/sbin/nginx

  • NGINX custom build: egrep -ao '.,.,.,[01]{33}' <path to nginx>/nginx

  • The user (and the user's group) who is running the NGINX worker processes: grep ‑w 'user' <path‑to‑the‑NGINX‑configuration‑files/nginx.conf>

Installation Options

The processing of requests in the filter node is done in two stages:

  • Processing in NGINX-Module-Wallarm.

  • Postanalytics – statistical analysis of the processed requests.

The processing is not memory demanding and can be put on front end servers without changing the server requirements.

Postanalytics is memory demanding, which may require changes in the server configuration or installation of postanalytics on a separate server.

Wallarm also has the option of installing postanalytics in a separate server pool.

Installation of postanalytics on a separate server

If you are planning to install postanalytics on a separate server, you must install postanalytics first. See details in Separate postanalytics installation.

To install as a dynamic module for NGINX, you must:

  1. Install NGINX.

  2. Add the Wallarm repositories, from which you will download packages.

  3. Install the Wallarm packages.

  4. Configure postanalytics.

  5. Connect the Wallarm module.

  6. Set up the filter node for using a proxy server.

  7. Connect the filter node to the Wallarm cloud.

  8. Configure the server addresses of postanalytics.

  9. Configure the filtration mode.

  10. Configure logging.

  11. Restart NGINX.

Prerequisites

  • Prior to taking any steps listed below, either disable or configure SELinux if it is installed on the operating system.
  • Make sure that you execute all commands below as superuser (e.g. root).

1. Install NGINX

Stable version of NGINX module

Please note that the stable NGINX version should be installed because its mainline version is not compatible with the Wallarm NGINX module.

You can:

  • Use the official build.

    The instructions on how to install the stable NGINX for the distributions supported by Wallarm are listed below:

    apt install curl gnupg2 ca-certificates lsb-release
    echo "deb http://nginx.org/packages/debian `lsb_release -cs` nginx" | tee /etc/apt/sources.list.d/nginx.list
    curl -fsSL https://nginx.org/keys/nginx_signing.key | apt-key add -
    apt update
    apt install nginx
    
    apt install curl gnupg2 ca-certificates lsb-release
    echo "deb http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" | tee /etc/apt/sources.list.d/nginx.list
    curl -fsSL https://nginx.org/keys/nginx_signing.key | apt-key add -
    apt update
    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' > /etc/yum.repos.d/nginx.repo
    yum install nginx
    
  • Prepare a custom build with the similar compilation options. To do that, use the source code from the stable branch of the NGINX repository.

See the official NGINX installation instructions for extra information.

Installing on Amazon Linux 2

To install NGINX on Amazon Linux 2, use the CentOS 7 instruction.

2. Add the Wallarm Repositories

The installation and updating of the filter node is done from the Wallarm
repositories.

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

apt-get install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node jessie/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-get install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node stretch/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
apt-get install dirmngr
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/debian/wallarm-node buster/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node trusty/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node xenial/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
curl -fsSL https://repo.wallarm.com/wallarm.gpg | apt-key add -
sh -c "echo 'deb http://repo.wallarm.com/ubuntu/wallarm-node bionic/2.14/' > /etc/apt/sources.list.d/wallarm.list"
apt-get update
yum install --enablerepo=extras -y epel-release centos-release-SCL
rpm -i https://repo.wallarm.com/centos/wallarm-node/6/2.14/x86_64/Packages/wallarm-node-repo-1-5.el6.noarch.rpm
yum install -y epel-release
rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm
yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
rpm -i https://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/Packages/wallarm-node-repo-1-5.el7.noarch.rpm

Repository access

Your system must have access to https://repo.wallarm.com to download the packages.

Ensure the access is not blocked by a firewall.

Issue with CentOS GPG keys

If you have already added the Wallarm repository and got an error related to invalid CentOS GPG keys, then please follow these steps:

  1. Remove added repository using the yum remove wallarm-node-repo command.
  2. Add the repository using the command from the appropriate tab above.

Possible error messages:

  • http://repo.wallarm.com/centos/wallarm-node/7/2.14/x86_64/repodata/repomd.xml: [Errno -1] repomd.xml signature could not be verified for wallarm-node_2.14
  • One of the configured repositories failed (Wallarm Node for CentOS 7 - 2.14), and yum doesn't have enough cached data to continue.

3. Install the Wallarm Packages

Install the Requests Processing and Postanalytics on the Same Server

To run postanalytics and process the requests on the same server, you need to
install the following packages:

  • Wallarm module

  • In-memory storage Tarantool.

  • Postanalytics.

Run the following command to install the required packages:

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

Install Only the Requests Processing on the Server

To only process the requests on the server, you need to install the following
package:

  • Wallarm module

Run the following command to install the required package:

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

4. Configure Postanalytics

Info

Skip this step if you installed postanalytics on a separate server as you already have your postanalytics configured.

Postanalytics uses the in-memory storage Tarantool. The Tarantool database is used to keep in a circular buffer a local copy of the data stream processed by a WAF node, including request/response headers and request bodies (but not response bodies).

The recommended value is 75% of the total server memory. However, there is a more accurate way to define the required value. To make a WAF node efficient, the database should keep at least 15 minutes of transmitted data with about 2x overhead for data serialization. Following these points, the amount of memory can be estimated by the formula:

Speed of request processing per minute in bytes * 15 * 2

For example, if a WAF node is handling at peak 50 MBps of end user requests, the required Tarantool database memory consumption can be estimated as the following:

50 MBps / 8 (bits in a byte) * 60 (seconds in a minute) * 15 * 2 = 11,250,000,000 bytes (or ~ 10.4 GB)

The sizing of Tarantool memory is controlled using the SLAB_ALLOC_ARENA attribute in the /etc/default/wallarm‑tarantool configuration file. To allocate memory:

  1. Open for editing the configuration file of Tarantool:
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/default/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
vi /etc/sysconfig/wallarm-tarantool
  1. Set the SLAB_ALLOC_ARENA attribute to memory size. For example:
SLAB_ALLOC_ARENA=10.4
  1. Restart Tarantool:
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
service wallarm-tarantool restart
systemctl restart wallarm-tarantool
systemctl restart wallarm-tarantool

To learn how long a Tarantool instance is capable of keeping traffic details with the current level of WAF node load, you can use the wallarm‑tarantool/gauge‑timeframe_size monitoring metric.

To get more information about memory allocation, please use this documentation.

5. Connect the Wallarm Module

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

Ensure that you have the include /etc/nginx/conf.d/* line in the file. If you do not, 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:

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

6. Set up the Filter Node for Using a Proxy Server

Info

This setup step is intended for users who use their own proxy server for the operation of the protected web applications.

If you do not use a proxy server, skip this step of the setup.

You need to assign new values to the environment variables, which define the proxy server used, to configure Wallarm node for using your proxy server.

Add new values of the environment variables to the /etc/environment file:

  • Add https_proxy to define a proxy for the https protocol.

  • Add http_proxy to define a proxy for the http protocol.

  • Add no_proxy to define the list of the resources proxy should not be used for.

Assign the <scheme>://<proxy_user>:<proxy_pass>@<host>:<port> string values to the https_proxy and http_proxy variables.

  • <scheme> defines the protocol used. It should match the protocol that the current environment variable sets up proxy for.

  • <proxy_user> defines the username for proxy authorization.

  • <proxy_pass> defines the password for proxy authorization.

  • <host> defines a host of the proxy server.

  • <port> defines a port of the proxy server.

Assign a "<res_1>, <res_2>, <res_3>, <res_4>, ..." array value, where <res_1>, <res_2>, <res_3>, and <res_4> are the IP addresses and/or domains, to the no_proxy variable to define a list of the resources which proxy should not be used for. This array should consist of IP addresses and/or domains.

Resources that need to be addressed without a proxy

Add the following IP addresses and domain to the list of the resources that have to be addressed without a proxy for the system to operate correctly: 127.0.0.1, 127.0.0.8, 127.0.0.9, and localhost.
The 127.0.0.8 and 127.0.0.9 IP addresses are used for the operation of the Wallarm filter node.

The example of the correct /etc/environment file contents below demonstrates the following configuration:

  • HTTPS and HTTP requests are proxied to the 1.2.3.4 host with the 1234 port, using the admin username and the 01234 password for authorization on the proxy server.

  • Proxying is disabled for the requests sent to 127.0.0.1, 127.0.0.8, 127.0.0.9, and localhost.

https_proxy=http://admin:01234@1.2.3.4:1234
http_proxy=http://admin:01234@1.2.3.4:1234
no_proxy="127.0.0.1, 127.0.0.8, 127.0.0.9, localhost"

7. Connect the Filter Node to the Wallarm Cloud

API Access

The API choice for your filter node depends on the Cloud you are using. Please, select the API accordingly:

Ensure the access is not blocked by a firewall.

The filter node interacts with the Wallarm cloud.

To connect the node to the cloud using your cloud account requisites, proceed with the following steps:

  1. Make sure that your Wallarm account has the Administrator role enabled and two-factor authentication disabled, therefore allowing you to connect a filter node to the cloud.

    You can check the aforementioned parameters by navigating to the user account list in the Wallarm console.

    User list in Wallarm console

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

    Info

    You have to pick the script to run depending on the Cloud you are using.

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

    To specify the name of the created node, use the -n <node name> option.

  3. Provide your Wallarm account’s login and password when prompted.

8. Configure the Server Addresses of Postanalytics

Info

  • Skip this step if you installed postanalytics and the filter node on the same server.
  • Do this step if you installed postanalytics and the filter node on separate servers.

Add the server address of postanalytics to /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;
    }

    ...

    wallarm_tarantool_upstream wallarm_tarantool;

Required conditions

It is required that the following conditions are satisfied for the max_conns and the keepalive parameters:

  • The value of the keepalive parameter must not be lower than the number of the tarantool servers.
  • The value of the max_conns parameter must be specified for each of the upstream Tarantool servers to prevent the creation of excessive connections.

9. Configure the Filtration Mode

The etc/nginx/conf.d directory contains NGINX and Wallarm filter node configuration files.

By default, this directory contains the following configuration files:

  • The default.conf file defines the configuration of NGINX.

  • The wallarm.conf file defines the global configuration of Wallarm filter node.

  • The wallarm-status.conf file defines the Wallarm monitoring configuration.

You can create your own configuration files to define the operation of NGINX and Wallarm. It is recommended to create a separate configuration file with the server block for each group of the domains that should be processed in the same way.

To see detailed information about working with NGINX configuration files, proceed to the official NGINX documentation.

Wallarm directives define the operation logic of the Wallarm filter node. To see the list of Wallarm directives available, proceed to the Wallarm configuration options page.

A Configuration File Example

Let us suppose that you need to configure the server to work in the following conditions:

  • Only HTTP traffic is processed. There are no HTTPS requests processed.

  • The following domains receive the requests: example.com and www.example.com.

  • All requests must be passed to the server 10.80.0.5.

  • All incoming requests are considered less than 1MB in size (default setting).

  • The processing of a request takes no more than 60 seconds (default setting).

  • Wallarm must operate in the monitor mode.

  • Clients access the filter node directly, without an intermediate HTTP load balancer.

Creating a configuration file

You can create a custom NGINX configuration file (e.g. example.com.conf) or modify the default NGINX configuration file (default.conf).

When creating a custom configuration file, make sure that NGINX listens to the incoming connections on the free port.

To meet the listed conditions, the contents of the configuration file must be the following:

    server {
      listen 80;
      listen [::]:80 ipv6only=on;

      # the domains for which traffic is processed
      server_name example.com; 
      server_name www.example.com;

      # turn on the monitoring mode of traffic processing
      wallarm_mode monitoring; 
      # wallarm_instance 1;

      location / {
        # setting the address for request forwarding
        proxy_pass http://10.80.0.5; 
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      }
    }

10. Configure Logging

Configure the filter node variables logging using NGINX. This will allow to perform a quick filter node diagnostics with the help of the NGINX log file.

11. Restart NGINX

Providing user with root permission

If you are running NGINX as a user that does not have root permission, add this user to the wallarm group using the following command:

usermod -aG wallarm <user_name>;

where <user_name> is the name of the user without root permission.

systemctl restart nginx
systemctl restart nginx
systemctl restart nginx
service nginx restart
service nginx restart
service nginx restart
service nginx restart
systemctl restart nginx
systemctl restart nginx

The Installation Is Complete

Check that the filter node runs and filters the traffic. See Check the filter node operation.

Default Settings

A freshly installed filter node operates in blocking mode (see the wallarm_mode directive description) by default.

This may result in the inoperable Wallarm scanner. If you plan to use the scanner, then you need to perform additional actions to render scanner operational.

Additional Settings

The filter node may require some additional configuration after installation.

The document below lists a few of the typical setups that you can apply if needed.

To get more information about other available settings, proceed to the “Configuration” section of the Administrator’s Guide.

Configuring the Display of the Client's Real IP

If the filter node is deployed behind a proxy server or load balancer without any additional configuration, the request source address may not be equal to the actual IP address of the client. Instead, it may be equal to one of the IP addresses of the proxy server or the load balancer.

In this case, if you want the filter node to receive the client's IP address as a request source address, you need to perform an additional configuration of the proxy server or the load balancer.

Adding Wallarm Scanner Addresses to the Whitelist

The Wallarm scanner checks the resources of your company for vulnerabilities. Scanning is conducted using IP addresses from one of the following lists (depending on the type of Wallarm Cloud you are using):

If you are using the Wallarm scanner, you need to configure the whitelists on your network scope security software (such as firewalls, intrusion detection systems, etc.) to contain Wallarm scanner IP addresses.

For example, a Wallarm filter node with default settings is placed in the blocking mode, thus rendering the Wallarm scanner unable to scan the resources behind the filter node.

To make the scanner operational again, whitelist the scanner's IP addresses on this filter node.

Limiting the Single Request Processing Time

Use the wallarm_process_time_limit Wallarm directive to specify the limit of the duration for processing a single request by the filter node.

If processing the request consumes more time than specified in the directive, then the information on the error is entered into the log file and the request is marked as an overlimit_res attack.

Limiting the Server Reply Waiting Time

Use the proxy_read_timeout NGINX directive to specify the timeout for reading the proxy server reply.

If the server sends nothing during this time, the connection is closed.

Limiting the Maximum Request Size

Use the client_max_body_size NGINX directive to specify the limit for the maximum size of the body of the client's request.

If this limit is exceeded, NGINX replies to the client with the 413 (Payload Too Large) code, also known as the Request Entity Too Large message.